@abdess76/i18nkit 1.0.0

package/bin/core/sync-checker-utils.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * @fileoverview Output formatters for sync-checker results.
+ * @module sync-checker-utils
+ */
+
+const { logListWithLimit } = require('./log-utils');
+
+function logMissingKeys(missingByLang, log) {
+  for (const [lang, keys] of Object.entries(missingByLang)) {
+    if (keys.length === 0) {
+      continue;
+    }
+    logListWithLimit({ items: keys, label: `Missing in ${lang}.json`, limit: 10, log });
+    log();
+  }
+}
+
+function logIdenticalValues(identicalValues, log) {
+  if (identicalValues.length === 0) {
+    return;
+  }
+  const truncate = v => (typeof v === 'string' && v.length > 40 ? `${v.substring(0, 37)}...` : v);
+  logListWithLimit({
+    items: identicalValues,
+    label: 'Identical values across languages',
+    limit: 10,
+    log,
+    formatter: ({ key, value }) => `${key}: "${truncate(value)}"`,
+  });
+  log();
+}
+
+function logIcuMismatches(icuMismatches, log) {
+  if (icuMismatches.length === 0) {
+    return;
+  }
+  log(`ICU structure mismatches (${icuMismatches.length}):`);
+  icuMismatches.slice(0, 5).forEach(({ key, hasIcu, missingIcu }) => {
+    log(`  [!] ${key}`);
+    log(`      Has ICU: ${hasIcu.join(', ')} | Missing ICU: ${missingIcu.join(', ')}`);
+  });
+  if (icuMismatches.length > 5) {
+    log(`  ... and ${icuMismatches.length - 5} more`);
+  }
+  log();
+}
+
+function logIcuMessages(icuMessages, log) {
+  if (icuMessages.length === 0) {
+    return;
+  }
+  logListWithLimit({
+    items: icuMessages,
+    label: 'ICU/Pluralization messages',
+    limit: 5,
+    log,
+    formatter: ({ key }) => key,
+  });
+  log();
+}
+
+function logSyncIssues(sr, log) {
+  logMissingKeys(sr.missingByLang, log);
+  logIdenticalValues(sr.identicalValues, log);
+  logIcuMismatches(sr.icuMismatches, log);
+  logIcuMessages(sr.icuMessages, log);
+}
+
+function logSyncSummary(sr, log) {
+  log('Summary');
+  log('-'.repeat(50));
+  log(`Total keys:        ${sr.allKeys.size}`);
+  log(`Languages:         ${sr.langFiles.length}`);
+  log(`Missing keys:      ${Object.values(sr.missingByLang).reduce((a, b) => a + b.length, 0)}`);
+  log(`Identical values:  ${sr.identicalValues.length}`);
+  log(`ICU messages:      ${sr.icuMessages.length}`);
+  log(`ICU mismatches:    ${sr.icuMismatches.length}`);
+}
+
+function logSyncHeader(log) {
+  log('Transloco Sync Check');
+  log('='.repeat(50));
+}
+
+function handleInsufficientLangs(langFiles, log) {
+  log(
+    `Need at least 2 language files to compare.\nFound: ${langFiles.map(f => f.name).join(', ') || 'none'}`,
+  );
+  return { success: true, langFiles, result: null };
+}
+
+module.exports = {
+  logSyncIssues,
+  logSyncSummary,
+  logSyncHeader,
+  handleInsufficientLangs,
+};

package/bin/core/sync-checker.js

@@ -0,0 +1,199 @@
+'use strict';
+
+/**
+ * @fileoverview Cross-language file synchronization checker.
+ * Detects missing keys, identical values, and ICU format mismatches.
+ * @module sync-checker
+ */
+
+const path = require('path');
+const fs = require('./fs-adapter');
+const {
+  readJsonFile,
+  flattenKeys,
+  getNestedValue,
+  isICUMessage,
+  normalizeData,
+} = require('./json-utils');
+const {
+  logSyncIssues,
+  logSyncSummary,
+  logSyncHeader,
+  handleInsufficientLangs,
+} = require('./sync-checker-utils');
+
+const isTranslationFile = entry =>
+  entry.isFile() &&
+  entry.name.endsWith('.json') &&
+  !entry.name.includes('report') &&
+  !entry.name.includes('extracted');
+
+async function readI18nDirectory(i18nDir) {
+  try {
+    return await fs.readdir(i18nDir, { withFileTypes: true });
+  } catch {
+    throw new Error(`i18n directory not found: ${i18nDir}`);
+  }
+}
+
+async function loadLangFilesForSync(i18nDir) {
+  const dirEntries = await readI18nDirectory(i18nDir);
+  return dirEntries
+    .filter(isTranslationFile)
+    .map(f => ({ name: f.name.replace('.json', ''), path: path.join(i18nDir, f.name) }));
+}
+
+async function normalizeLangData(langFiles, format) {
+  const langData = {};
+  const allKeys = new Set();
+  const results = await Promise.all(
+    langFiles.map(async ({ name, path: filePath }) => {
+      const data = await readJsonFile(filePath);
+      if (!data) {
+        throw new Error(`Cannot parse ${name}.json`);
+      }
+      return { name, data };
+    }),
+  );
+  for (const { name, data } of results) {
+    const normalized = normalizeData(data, format);
+    const keys = flattenKeys(normalized);
+    langData[name] = { data: normalized, keys: new Set(keys) };
+    keys.forEach(k => allKeys.add(k));
+  }
+  return { langData, allKeys };
+}
+
+function getKeyEntries(key, langFiles, langData) {
+  return langFiles
+    .filter(({ name }) => langData[name].keys.has(key))
+    .map(({ name }) => [name, getNestedValue(langData[name].data, key.split('.'))]);
+}
+
+function detectIcuStatus(entries) {
+  return {
+    icuLangs: entries.filter(([, v]) => isICUMessage(v)).map(([l]) => l),
+    nonIcuLangs: entries.filter(([, v]) => v && !isICUMessage(v)).map(([l]) => l),
+  };
+}
+
+const hasIcuMismatch = (icu, nonIcu) => icu.length > 0 && nonIcu.length > 0;
+const hasUniqueValue = entries => new Set(Object.values(Object.fromEntries(entries))).size === 1;
+
+function classifyKeyResult(key, entries, icuStatus) {
+  const { icuLangs, nonIcuLangs } = icuStatus;
+  if (hasIcuMismatch(icuLangs, nonIcuLangs)) {
+    return { type: 'icuMismatch', key, hasIcu: icuLangs, missingIcu: nonIcuLangs };
+  }
+  if (icuLangs.length > 0) {
+    return { type: 'icuMessage', key, langs: icuLangs };
+  }
+  if (hasUniqueValue(entries)) {
+    return { type: 'identical', key, value: entries[0]?.[1] };
+  }
+  return null;
+}
+
+function analyzeKeyForSync(key, langFiles, langData) {
+  const entries = getKeyEntries(key, langFiles, langData);
+  if (entries.length < 2) {
+    return null;
+  }
+  return classifyKeyResult(key, entries, detectIcuStatus(entries));
+}
+
+const CATEGORY_MAP = {
+  icuMismatch: 'icuMismatches',
+  icuMessage: 'icuMessages',
+  identical: 'identicalValues',
+};
+const addToCategory = (cat, res) => {
+  const k = res?.type && CATEGORY_MAP[res.type];
+  if (k) {
+    cat[k].push(res);
+  }
+};
+
+function categorizeKeysForSync(allKeys, langFiles, langData) {
+  const categories = { identicalValues: [], icuMessages: [], icuMismatches: [] };
+  for (const key of allKeys) {
+    addToCategory(categories, analyzeKeyForSync(key, langFiles, langData));
+  }
+  return categories;
+}
+
+function buildSyncResult(langFiles, langData, allKeys) {
+  const missingByLang = Object.fromEntries(
+    langFiles.map(({ name }) => [name, [...allKeys.difference(langData[name].keys)]]),
+  );
+  const { identicalValues, icuMessages, icuMismatches } = categorizeKeysForSync(
+    allKeys,
+    langFiles,
+    langData,
+  );
+  return { allKeys, langFiles, missingByLang, identicalValues, icuMessages, icuMismatches };
+}
+
+const hasCriticalSyncIssues = sr =>
+  Object.values(sr.missingByLang).some(k => k.length > 0) || sr.icuMismatches.length > 0;
+
+function buildCheckSyncResult(ctx) {
+  const { syncResult, strict, exitCodes, log } = ctx;
+  const failed = strict && hasCriticalSyncIssues(syncResult);
+  if (failed) {
+    log('\nSync check failed (--strict mode)');
+  }
+  return {
+    success: !failed,
+    exitCode: failed ? exitCodes.untranslated : exitCodes.success,
+    result: syncResult,
+  };
+}
+
+async function performSyncCheck(langFiles, format, log) {
+  log(`Comparing: ${langFiles.map(f => f.name).join(', ')}\n`);
+  const { langData, allKeys } = await normalizeLangData(langFiles, format);
+  const syncResult = buildSyncResult(langFiles, langData, allKeys);
+  logSyncIssues(syncResult, log);
+  logSyncSummary(syncResult, log);
+  return syncResult;
+}
+
+const getExitCodes = options => options.exitCodes || { success: 0, untranslated: 1 };
+const parseSyncOptions = opts => ({
+  i18nDir: opts.i18nDir,
+  format: opts.format || 'nested',
+  log: opts.log || console.log,
+  strict: opts.strict || false,
+  exitCodes: getExitCodes(opts),
+});
+
+/**
+ * Compares language files for missing keys, ICU mismatches, and duplicates
+ * @param {SyncOptions} [options]
+ * @returns {Promise<SyncCheckResult>}
+ * @example
+ * const { success, result } = await checkSync({ i18nDir: './src/i18n', strict: true });
+ * console.log(result.missingByLang);
+ */
+async function checkSync(options = {}) {
+  const opts = parseSyncOptions(options);
+  logSyncHeader(opts.log);
+  const langFiles = await loadLangFilesForSync(opts.i18nDir);
+  if (langFiles.length < 2) {
+    return handleInsufficientLangs(langFiles, opts.log);
+  }
+  const syncResult = await performSyncCheck(langFiles, opts.format, opts.log);
+  return buildCheckSyncResult({
+    syncResult,
+    strict: opts.strict,
+    exitCodes: opts.exitCodes,
+    log: opts.log,
+  });
+}
+
+module.exports = {
+  checkSync,
+  isTranslationFile,
+  readI18nDirectory,
+};

package/bin/core/translator.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * @fileoverview Automated translation of i18n JSON files.
+ * Supports DeepL API and free MyMemory service with duplicate caching.
+ * @module translator
+ */
+
+const path = require('path');
+const { readJsonFile, writeJsonFile, flattenJson, unflattenJson } = require('./json-utils');
+
+async function prepareTranslationData(sourceLang, i18nDir) {
+  const sourceFile = path.join(i18nDir, `${sourceLang}.json`);
+  const sourceJson = await readJsonFile(sourceFile);
+  if (!sourceJson) {
+    throw new Error(`Source file not found or invalid: ${sourceFile}`);
+  }
+
+  const flat = flattenJson(sourceJson);
+  const entries = Object.entries(flat).filter(([, v]) => v && typeof v === 'string');
+  const keys = entries.map(([k]) => k);
+  const values = entries.map(([, v]) => v);
+  const uniqueValues = [...new Set(values)];
+
+  return { keys, values, uniqueValues };
+}
+
+function logTranslateHeader(ctx) {
+  const { sourceLang, targetLang, useDeepL, log } = ctx;
+  log('Transloco Auto-Translate');
+  log('='.repeat(50));
+  log(`Source: ${sourceLang}.json -> Target: ${targetLang}.json`);
+  log(`Provider: ${useDeepL ? 'DeepL' : 'MyMemory (free)'}`);
+  log();
+}
+
+function logTranslationSummary(ctx) {
+  const { valuesCount, failedCount, useDeepL, email, log } = ctx;
+  log('\nSummary');
+  log('-'.repeat(50));
+  log(`Strings translated: ${valuesCount - failedCount}/${valuesCount}`);
+  if (failedCount > 0) {
+    log(`Failed translations: ${failedCount} (kept original text)`);
+  }
+  log(`Provider: ${useDeepL ? 'DeepL API' : 'MyMemory (free)'}`);
+  if (!useDeepL && !email) {
+    log('Tip: Use --email=your@email.com for higher rate limits');
+  }
+}
+
+async function executeDeepLTranslation(ctx) {
+  const { uniqueValues, sourceLang, targetLang, provider } = ctx;
+  const translated = await provider.translateBatch(uniqueValues, sourceLang, targetLang);
+  return {
+    translationMap: new Map(uniqueValues.map((v, i) => [v, translated[i]])),
+    failedCount: 0,
+  };
+}
+
+function executeMyMemoryTranslation(ctx) {
+  const { uniqueValues, sourceLang, targetLang, provider, email, verbose } = ctx;
+  return provider.translateBatch(uniqueValues, sourceLang, targetLang, {
+    email,
+    verbose,
+    onProgress: (processed, total) => {
+      if (processed < total) {
+        process.stdout.write(`\r  Progress: ${processed}/${total}`);
+      }
+    },
+  });
+}
+
+function executeTranslation(ctx) {
+  return ctx.useDeepL ? executeDeepLTranslation(ctx) : executeMyMemoryTranslation(ctx);
+}
+
+async function saveTranslationResult(ctx) {
+  const { targetJson, targetFile, startTime, dryRun = false, log = console.log } = ctx;
+
+  if (dryRun) {
+    log('\n[DRY RUN] Would write:');
+    log(JSON.stringify(targetJson, null, 2));
+    return;
+  }
+
+  await writeJsonFile(targetFile, targetJson);
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+  log(`\nTranslated: ${targetFile} (${elapsed}s)`);
+}
+
+function buildTranslatedOutput(ctx) {
+  const { keys, values, translationMap, i18nDir, targetLang } = ctx;
+  const translatedFlat = Object.fromEntries(
+    keys.map((k, i) => [k, translationMap.get(values[i]) ?? values[i]]),
+  );
+  return {
+    targetJson: unflattenJson(translatedFlat),
+    targetFile: path.join(i18nDir, `${targetLang}.json`),
+  };
+}
+
+function logDuplicateInfo(ctx) {
+  const { values, uniqueValues, verbose, log } = ctx;
+  if (values.length > uniqueValues.length && verbose) {
+    log(`  ${values.length - uniqueValues.length} duplicate strings will use cache`);
+  }
+}
+
+async function performTranslation(ctx) {
+  const { uniqueValues, sourceLang, targetLang, provider, useDeepL, email, verbose, log } = ctx;
+  log(`Translating ${uniqueValues.length} unique strings...`);
+
+  const result = await executeTranslation({
+    uniqueValues,
+    sourceLang,
+    targetLang,
+    provider,
+    useDeepL,
+    email,
+    verbose,
+  });
+  log();
+  return result;
+}
+
+function handleEmptyTranslation(log) {
+  log('No strings to translate.');
+  return { success: true, translated: 0 };
+}
+
+function buildTranslationContext(ctx) {
+  const { uniqueValues, sourceLang, targetLang, provider, useDeepL, email, verbose, log } = ctx;
+  return { uniqueValues, sourceLang, targetLang, provider, useDeepL, email, verbose, log };
+}
+
+function buildOutputContext(ctx, translationMap) {
+  const { keys, values, i18nDir, targetLang } = ctx;
+  return { keys, values, translationMap, i18nDir, targetLang };
+}
+
+async function runTranslation(ctx) {
+  logDuplicateInfo(ctx);
+  const startTime = Date.now();
+  const { translationMap, failedCount } = await performTranslation(buildTranslationContext(ctx));
+  const { targetJson, targetFile } = buildTranslatedOutput(buildOutputContext(ctx, translationMap));
+  await saveTranslationResult({
+    targetJson,
+    targetFile,
+    startTime,
+    dryRun: ctx.dryRun,
+    log: ctx.log,
+  });
+  logTranslationSummary({
+    valuesCount: ctx.values.length,
+    failedCount,
+    useDeepL: ctx.useDeepL,
+    email: ctx.email,
+    log: ctx.log,
+  });
+  return { success: true, translated: ctx.values.length - failedCount, failed: failedCount };
+}
+
+function parseTranslateOptions(options) {
+  const {
+    i18nDir,
+    provider,
+    useDeepL = false,
+    email,
+    verbose = false,
+    dryRun = false,
+    log = console.log,
+  } = options;
+  return { i18nDir, provider, useDeepL, email, verbose, dryRun, log };
+}
+
+/**
+ * Translates a JSON language file using DeepL or MyMemory
+ * @param {string} sourceLang - Source language code (e.g., 'en')
+ * @param {string} targetLang - Target language code (e.g., 'fr')
+ * @param {TranslateOptions} [options]
+ * @returns {Promise<TranslateResult>}
+ * @example
+ * await translateFile('en', 'fr', { i18nDir: './src/i18n', provider: deepLProvider });
+ */
+async function translateFile(sourceLang, targetLang, options = {}) {
+  const opts = parseTranslateOptions(options);
+  logTranslateHeader({ sourceLang, targetLang, useDeepL: opts.useDeepL, log: opts.log });
+  const data = await prepareTranslationData(sourceLang, opts.i18nDir);
+  if (data.keys.length === 0) {
+    return handleEmptyTranslation(opts.log);
+  }
+  return runTranslation({ ...data, sourceLang, targetLang, ...opts });
+}
+
+module.exports = {
+  translateFile,
+};