localize-sync 1.0.0

package/bin/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { loadConfig } from '../src/utils/loadconfig.js';
+import { check } from '../src/commands/check.js';
+import { report } from '../src/commands/report.js';
+import { translate } from '../src/commands/translate.js';
+
+program
+  .name('localize-sync')
+  .description('Auto detect and translate missing i18n JSON keys')
+  .version('1.0.0');
+
+const sharedOptions = (cmd) => {
+  return cmd
+    .option('-d, --dir <path>', 'Path to locales directory')
+    .option('-s, --source <lang>', 'Source language file (without .json)');
+};
+
+sharedOptions(
+  program.command('check').description('Check missing and extra keys across all locale files')
+).action(async (options) => {
+  const config = await loadConfig(options);
+  await check(config);
+});
+
+sharedOptions(
+  program.command('report').description('Generate a JSON report of translation coverage')
+).action(async (options) => {
+  const config = await loadConfig(options);
+  const results = await check(config);
+  await report(results, config);
+});
+
+sharedOptions(
+  program.command('translate').description('Auto translate missing keys using MyMemory API')
+).action(async (options) => {
+  const config = await loadConfig(options);
+  const results = await check(config);
+  await translate(results, config);
+});
+
+sharedOptions(
+  program.command('all').description('Run check, translate and report together')
+).action(async (options) => {
+  const config = await loadConfig(options);
+  const results = await check(config);
+  await translate(results, config);
+  const updatedResults = await check(config);
+  await report(updatedResults, config);
+});
+
+program.parse();

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "localize-sync",
+  "version": "1.0.0",
+  "description": "Auto translate i18n JSON files using MyMemory API",
+  "type": "module",
+  "bin": {
+    "localize-sync": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js"
+  },
+  "keywords": [
+    "i18n",
+    "translate",
+    "cli",
+    "localization",
+    "json"
+  ],
+  "author": "Amir Hossein Jamshidi",
+  "license": "MIT"
+}

package/readme

@@ -0,0 +1,120 @@
+# localize-sync
+
+Auto-detect and translate missing i18n JSON keys using the MyMemory API.
+
+## Install
+
+```bash
+npm install -g localize-sync
+```
+
+Or use without installing:
+
+```bash
+npx localize-sync <command>
+```
+
+---
+
+## How it works
+
+`localize-sync` treats one JSON file as the **source of truth** (default: `fa.json`) and compares all other JSON files in the same directory against it. Missing keys are automatically translated via the [MyMemory API](https://mymemory.translated.net/).
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `check` | Show missing and extra keys across all locale files |
+| `translate` | Auto-translate missing keys |
+| `report` | Generate a `i18n-report.json` coverage report |
+| `all` | Run check → translate → report in sequence |
+
+---
+
+## Options
+
+| Flag | Alias | Default | Description |
+|---|---|---|---|
+| `--dir <path>` | `-d` | `./locales` | Path to your locales directory |
+| `--source <lang>` | `-s` | `fa` | Source language filename (without `.json`) |
+
+---
+
+## Usage
+
+```bash
+# Check missing keys (source: fa.json, dir: ./locales)
+localize-sync check
+
+# Translate missing keys in a custom directory
+localize-sync translate --dir ./src/translations
+
+# Use a different source language
+localize-sync all --source en
+
+# Combine both options
+localize-sync all --dir ./src/i18n --source en
+```
+
+---
+
+## Config file (optional)
+
+Instead of passing flags every time, create an `i18n.config.js` in your project root:
+
+```js
+// i18n.config.js
+export default {
+  dir: './src/locales',
+  source: 'fa',
+}
+```
+
+Priority order: `CLI flags` > `i18n.config.js` > `defaults`
+
+---
+
+## Example
+
+Given this structure:
+
+```
+locales/
+  fa.json   ← source of truth
+  en.json   ← partially translated
+  de.json   ← empty
+```
+
+Running `localize-sync all` will:
+
+1. Detect missing keys in `en.json` and `de.json`
+2. Translate them automatically from Persian
+3. Save a coverage report to `i18n-report.json`
+
+---
+
+## Report output
+
+```json
+{
+  "en": {
+    "total": 9,
+    "translated": 9,
+    "coverage": "100%",
+    "missingKeys": [],
+    "extraKeys": []
+  }
+}
+```
+
+---
+
+## Notes
+
+- Translation is powered by [MyMemory](https://mymemory.translated.net/) — free, no API key required
+- A 300ms delay is applied between requests to avoid rate limiting
+- If a translation fails, a `⚠️ MISSING: <original>` placeholder is inserted
+
+---

package/src/commands/check.js

@@ -0,0 +1,57 @@
+import fs from 'fs';
+import path from 'path';
+import { flattenKeys } from '../utils/flattenKeys.js';
+
+export async function check(config) {
+  const files = fs.readdirSync(config.dir).filter((f) => f.endsWith('.json'));
+
+  if (files.length === 0) {
+    console.error('❌ No JSON files found in:', config.dir);
+    process.exit(1);
+  }
+
+  const sourceFile = `${config.source}.json`;
+
+  if (!files.includes(sourceFile)) {
+    console.error(`❌ Source file "${sourceFile}" not found in ${config.dir}`);
+    process.exit(1);
+  }
+
+  const sourceData = JSON.parse(fs.readFileSync(path.join(config.dir, sourceFile), 'utf-8'));
+  const sourceKeys = flattenKeys(sourceData);
+
+  console.log(`\n📋 Source: ${sourceFile} — ${Object.keys(sourceKeys).length} keys\n`);
+
+  const results = [];
+
+  files
+    .filter((f) => f !== sourceFile)
+    .forEach((file) => {
+      const lang = file.replace('.json', '');
+      const targetData = JSON.parse(fs.readFileSync(path.join(config.dir, file)));
+      const targetKeys = flattenKeys(targetData);
+
+      const missingKeys = Object.keys(sourceKeys).filter((k) => !(k in targetKeys));
+      const extraKeys = Object.keys(targetKeys).filter((k) => !(k in sourceKeys));
+
+      console.log(`🌍 ${file}`);
+      console.log(
+        `   ✅ Translated: ${Object.keys(targetKeys).length} / ${Object.keys(sourceKeys).length}`
+      );
+
+      if (missingKeys.length > 0) {
+        console.log(`   ❌ Missing keys (${missingKeys.length}):`);
+      } else {
+        console.log(`   🎉 All keys are translated!`);
+      }
+
+      if (extraKeys.length > 0) {
+        console.log(`   ⚠️  Extra keys (${extraKeys.length}):`);
+        extraKeys.forEach((k) => console.log(`      - ${k}`));
+      }
+
+      results.push({ lang, sourceKeys, targetKeys, missingKeys, extraKeys });
+    });
+
+  return results;
+}

package/src/commands/report.js

@@ -0,0 +1,20 @@
+import fs from 'fs';
+import path from 'path';
+
+export async function report(results, config) {
+  const output = {};
+
+  results.forEach(({ lang, sourceKeys, targetKeys, missingKeys, extraKeys }) => {
+    output[lang] = {
+      total: Object.keys(sourceKeys).length,
+      translated: Object.keys(targetKeys).length,
+      coverage: `${Math.round((Object.keys(targetKeys).length / Object.keys(sourceKeys).length) * 100)}%`,
+      missingKeys,
+      extraKeys
+    };
+  });
+
+  const reportPath = path.resolve(process.cwd(), 'i18n-report.json');
+  fs.writeFileSync(reportPath, JSON.stringify(output, null, 2), 'utf-8');
+  console.log(`\n📄 Report saved: ${reportPath}\n`);
+}

package/src/commands/translate.js

@@ -0,0 +1,39 @@
+import fs from 'fs';
+import path from 'path';
+import { translateText } from '../utils/translateText.js';
+
+export async function translate(results, config) {
+  for (const result of results) {
+    const { lang, missingKeys, sourceKeys } = result;
+    const filePath = path.join(config.dir, `${lang}.json`);
+    const targetData = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    if (missingKeys.length === 0) {
+      console.log(`✅ ${lang}.json - Nothing to translate`);
+      continue;
+    }
+
+    console.log(`\n🌍 ${lang}.json - Translating ${missingKeys.length} keys...\n`);
+
+    for (const flatKey of missingKeys) {
+      const originalText = sourceKeys[flatKey];
+      process.stdout.write(`   🔄 ${flatKey}: "${originalText}" → `);
+      const translated = await translateText(originalText, config.source, lang);
+
+      const parts = flatKey.split('.');
+      let current = targetData;
+      parts.forEach((part, index) => {
+        if (index === parts.length - 1) {
+          current[part] = translated ?? `⚠️ MISSING: ${originalText}`;
+        } else {
+          if (!current[part]) current[part] = {};
+          current = current[part];
+        }
+      });
+      console.log(translated ? `"${translated}"` : `⚠️ Translation failed, placeholder inserted`);
+      await new Promise((r) => setTimeout(r, 300));
+    }
+
+    fs.writeFileSync(filePath, JSON.stringify(targetData, null, 2), 'utf-8');
+    console.log(`\n💾 ${lang}.json saved`);
+  }
+}

package/src/utils/flattenKeys.js

@@ -0,0 +1,12 @@
+export function flattenKeys(obj, prefix = '') {
+  return Object.keys(obj).reduce((acc, key) => {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    const value = obj[key];
+    if (typeof value === 'object' && value !== null) {
+      Object.assign(acc, flattenKeys(value, fullKey));
+    } else {
+      acc[fullKey] = String(value);
+    }
+    return acc;
+  }, {});
+}

package/src/utils/loadconfig.js

@@ -0,0 +1,44 @@
+import fs from 'fs';
+import path from 'path';
+
+const DEFAULTS = {
+  dir: './locales',
+  source: 'fa'
+};
+
+export async function loadConfig(flags = {}) {
+  let fileConfig = {};
+  const configPath = path.resolve(process.cwd(), 'i18n.config.js');
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const imported = await import(configPath);
+      fileConfig = imported.default || {};
+      console.log('⚙️  Config loaded from i18n.config.js');
+    } catch (err) {
+      console.warn('⚠️  Failed to load i18n.config.js, using defaults');
+    }
+  }
+
+  const config = {
+    dir: flags.dir || fileConfig.dir || DEFAULTS.dir,
+    source: flags.source || fileConfig.source || DEFAULTS.source
+  };
+
+  const resolvedDir = path.isAbsolute(config.dir)
+    ? config.dir
+    : path.resolve(process.cwd(), config.dir);
+  if (!fs.existsSync(resolvedDir)) {
+    console.log(`❌ Directory not found: ${resolvedDir}`);
+    process.exit(1);
+  }
+
+  const stat = fs.statSync(resolvedDir);
+  if (!stat.isDirectory()) {
+    console.error(`❌ Path is not a directory: ${resolvedDir}`);
+    process.exit(1);
+  }
+
+  config.dir = resolvedDir;
+  return config;
+}

package/src/utils/translateText.js

@@ -0,0 +1,28 @@
+import fetch from 'node-fetch';
+
+const LANG_MAP = {
+  en: 'en-US',
+  de: 'de-DE',
+  fr: 'fr-FR',
+  ar: 'ar-SA',
+  es: 'es-ES',
+  it: 'it-IT',
+  tr: 'tr-TR'
+};
+
+export async function translateText(text, fromLang, toLang) {
+  const langPair = `${LANG_MAP[fromLang] || fromLang}|${LANG_MAP[toLang] || toLang}`;
+  const url = `https://api.mymemory.translated.net/get?q=${encodeURIComponent(text)}&langpair=${langPair}`;
+
+  try {
+    const res = await fetch(url);
+    const data = await res.json();
+    if (data.responseStatus === 200) {
+      return data.responseData.translatedText;
+    }
+    return null;
+  } catch (err) {
+    console.error(`❌ Error translating "${text}":`, err.message);
+    return null;
+  }
+}