@abdess76/i18nkit 1.0.0

package/bin/commands/extract-utils.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * @fileoverview Extract command utilities.
+ * File scanning, progress tracking, and output formatting.
+ * @module commands/extract-utils
+ */
+
+const path = require('path');
+const { getFileContent, setNestedValue, slugify, pathToScope } = require('../core');
+
+const noop = () => undefined;
+
+function createIntervalCallback(state) {
+  return () => {
+    state.dots = (state.dots + 1) % 4;
+    const dots = '.'.repeat(state.dots);
+    const spaces = ' '.repeat(3 - state.dots);
+    process.stdout.write(`\rScanning${dots}${spaces} ${state.scanned}/${state.total} files`);
+  };
+}
+
+function createProgressTracker(ctx) {
+  const { verbose, jsonOutput, totalFiles } = ctx;
+  const skipProgress = verbose || jsonOutput || !process.stdout.isTTY || totalFiles <= 50;
+  if (skipProgress) {
+    return { start: noop, stop: noop, increment: noop };
+  }
+
+  const state = { dots: 0, scanned: 0, total: totalFiles, interval: null };
+
+  return {
+    start: () => {
+      process.stdout.write('Scanning');
+      state.interval = setInterval(createIntervalCallback(state), 200);
+    },
+    stop: () => {
+      if (state.interval) {
+        clearInterval(state.interval);
+        process.stdout.write(`\r${' '.repeat(50)}\r`);
+      }
+    },
+    increment: () => {
+      state.scanned++;
+    },
+  };
+}
+
+function updateStats(stats, context, isNew) {
+  stats.total++;
+  if (isNew) {
+    stats.added++;
+  }
+  stats.byContext[context] = (stats.byContext[context] ?? 0) + 1;
+}
+
+function buildFinding(extraction, ctx) {
+  const { text, rawText, context, attr } = extraction;
+  const { relativePath, result, keyMapping, scope, stats } = ctx;
+
+  const keyPath = keyMapping[text]?.split('.') ?? [...scope, context, slugify(text)];
+  const { path: finalPath, isNew } = setNestedValue(result, keyPath, text);
+  const fullKey = finalPath.join('.');
+  const displayText = text.length > 80 ? `${text.substring(0, 77)}...` : text;
+
+  updateStats(stats, context, isNew);
+
+  return {
+    file: relativePath,
+    text,
+    rawText: rawText ?? text,
+    displayText,
+    context,
+    key: fullKey,
+    attr,
+    isNew,
+  };
+}
+
+function extractSingleSource(parser, source, extractCtx) {
+  const { options, seen, results } = extractCtx;
+  for (const r of parser.extract(source, '', options)) {
+    const key = `${r.context}:${r.text}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      results.push(r);
+    }
+  }
+}
+
+function extractFromContent(fileData, ctx) {
+  const { parsers, skipTranslated, extractTsObjects } = ctx;
+  const results = [];
+  const seen = new Set();
+  const sources = [fileData.template, fileData.typescript].filter(Boolean);
+  const extractCtx = { options: { skipTranslated, extractTsObjects }, seen, results };
+
+  for (const parser of parsers) {
+    for (const source of sources) {
+      extractSingleSource(parser, source, extractCtx);
+    }
+  }
+  return results;
+}
+
+function handleEmptyExtractions(stats) {
+  stats.clean++;
+  return [];
+}
+
+function mapExtractionsToFindings(extractions, filePath, ctx) {
+  const { srcDir, result, stats, keyMapping } = ctx;
+  stats.needsWork++;
+  const scope = pathToScope(filePath, srcDir);
+  const relativePath = path.relative(srcDir, filePath);
+  const findingCtx = { relativePath, result, keyMapping, scope, stats };
+  return extractions.map(e => buildFinding(e, findingCtx));
+}
+
+function processFile(filePath, ctx) {
+  const { processedTemplates, verbose, stats } = ctx;
+  const fileData = getFileContent(filePath, processedTemplates, verbose);
+  if (!fileData) {
+    return [];
+  }
+
+  stats.files++;
+  const extractions = extractFromContent(fileData, ctx);
+  if (extractions.length === 0) {
+    return handleEmptyExtractions(stats);
+  }
+
+  return mapExtractionsToFindings(extractions, filePath, ctx);
+}
+
+function scanFiles(files, ctx) {
+  const progress = createProgressTracker({ ...ctx, totalFiles: files.length });
+  progress.start();
+  const findings = files.flatMap(filePath => {
+    progress.increment();
+    return processFile(filePath, ctx);
+  });
+  progress.stop();
+  return findings;
+}
+
+function getFindingMarker(merge, isNew) {
+  if (!merge) {
+    return '-';
+  }
+  return isNew ? '+' : '=';
+}
+
+function formatFindingLines(finding, merge) {
+  return [
+    `  [${finding.context}] ${finding.key}`,
+    `    ${getFindingMarker(merge, finding.isNew)} "${finding.displayText}"`,
+  ];
+}
+
+function logFileGroup(file, fileFindings, ctx) {
+  ctx.log(`\n${file}`);
+  fileFindings.forEach(f => formatFindingLines(f, ctx.merge).forEach(l => ctx.log(l)));
+}
+
+function logVerboseFindings(findings, ctx) {
+  const findingsByFile = Object.groupBy(findings, f => f.file);
+  Object.entries(findingsByFile).forEach(([file, ff]) => logFileGroup(file, ff, ctx));
+}
+
+function logContextBreakdown(contexts, log) {
+  if (contexts.length === 0) {
+    return;
+  }
+  log('\nBy context:');
+  contexts.toSorted((a, b) => b[1] - a[1]).forEach(([k, v]) => log(`  ${k}: ${v}`));
+}
+
+function logSummary(stats, ctx) {
+  const { merge, log } = ctx;
+  log('\nSummary');
+  log('-'.repeat(50));
+  log(`Files scanned:     ${stats.files}`);
+  log(`Translated:        ${stats.clean}`);
+  log(`Need translation:  ${stats.needsWork}`);
+  log(`Strings found:     ${stats.total}`);
+  if (merge) {
+    log(`New strings:       ${stats.added}`);
+  }
+  logContextBreakdown(Object.entries(stats.byContext), log);
+}
+
+function getExtractMode(skipTranslated) {
+  return skipTranslated ? 'Extract Untranslated' : 'Extract All';
+}
+
+function logHeader(ctx) {
+  const { srcDir, outputFile, backupDir, skipTranslated, dryRun, backup, log } = ctx;
+  log(`Transloco ${getExtractMode(skipTranslated)}`);
+  log('='.repeat(50));
+  log(`Source: ${srcDir}`);
+  if (!dryRun) {
+    log(`Output: ${outputFile}`);
+  }
+  if (backup) {
+    log(`Backup: ${backupDir}`);
+  }
+  log();
+}
+
+module.exports = {
+  scanFiles,
+  logVerboseFindings,
+  logSummary,
+  logHeader,
+};

package/bin/commands/extract.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * @fileoverview Extract command - scans source files for translatable strings.
+ * Supports Angular templates, TypeScript, and PrimeNG components.
+ * @module commands/extract
+ */
+
+const fs = require('../core/fs-adapter');
+const path = require('path');
+
+const {
+  readJsonFileSync,
+  readJsonFile,
+  writeJsonFile,
+  flattenJson,
+  unflattenJson,
+  mergeDeep,
+  collectFiles,
+  applyFindings,
+} = require('../core');
+const { scanFiles, logVerboseFindings, logSummary, logHeader } = require('./extract-utils');
+
+async function initSingleLang(lang, sourceJson, ctx) {
+  const { i18nDir, format, log } = ctx;
+  const langFile = path.join(i18nDir, `${lang}.json`);
+  const existing = await readJsonFile(langFile);
+  const base = existing && format === 'flat' ? unflattenJson(existing) : existing || {};
+  const merged = mergeDeep(base, sourceJson);
+  const output = format === 'flat' ? flattenJson(merged) : merged;
+  await writeJsonFile(langFile, output);
+  log(`  Created/Updated: ${lang}.json`);
+}
+
+async function initLanguageFiles(result, ctx) {
+  const { initLangs, i18nDir, log } = ctx;
+  if (initLangs.length === 0) {
+    return;
+  }
+  log('\nInitializing language files...');
+  await fs.mkdir(i18nDir, { recursive: true });
+  await Promise.all(initLangs.map(lang => initSingleLang(lang, result, ctx)));
+}
+
+function logFindingsSummary(findings, ctx) {
+  const { verbose, log } = ctx;
+  if (verbose || findings.length === 0) {
+    return;
+  }
+  const unique = [...new Map(findings.map(f => [f.key, f])).values()];
+  if (unique.length <= 15) {
+    log('\nStrings extracted:');
+    unique.forEach(i => log(`  ${i.key}: "${i.displayText}"`));
+  } else {
+    log(`\nUse --verbose to see all ${unique.length} strings`);
+  }
+}
+
+async function writeReport(findings, stats, ctx) {
+  const { reportDir } = ctx;
+  await writeJsonFile(path.join(reportDir, 'report.json'), { stats, findings });
+  ctx.log(`Report: ${path.join(reportDir, 'report.json')}`);
+}
+
+function formatResult(result, format) {
+  return format === 'flat' ? flattenJson(result) : result;
+}
+
+function logDryRunOutput(result, format, log) {
+  log('\n[DRY RUN] Generated JSON:');
+  log(JSON.stringify(formatResult(result, format), null, 2));
+}
+
+async function writeMainOutput(ctx) {
+  const { outputFile, format, result, log } = ctx;
+  await writeJsonFile(outputFile, formatResult(result, format));
+  log(`\nExtracted: ${outputFile}`);
+}
+
+function shouldWriteReport(ctx) {
+  return (ctx.jsonOutput || ctx.autoApply) && !ctx.dryRun;
+}
+
+async function writeOutputs(findings, stats, ctx) {
+  if (ctx.dryRun && !ctx.autoApply) {
+    logDryRunOutput(ctx.result, ctx.format, ctx.log);
+    return;
+  }
+  if (!ctx.dryRun) {
+    await writeMainOutput(ctx);
+  }
+  if (shouldWriteReport(ctx)) {
+    await writeReport(findings, stats, ctx);
+  }
+  logFindingsSummary(findings, ctx);
+}
+
+async function loadMergeResult(ctx) {
+  const { outputFile, format, merge, log } = ctx;
+  if (!merge) {
+    return {};
+  }
+  const existing = await readJsonFile(outputFile);
+  if (!existing) {
+    return {};
+  }
+  log(`Merging with existing: ${path.basename(outputFile)}\n`);
+  return format === 'flat' ? unflattenJson(existing) : existing;
+}
+
+function getAutoApplyOpts(ctx) {
+  const { srcDir, backupDir, adapter, backup, dryRun, verbose, interactive, log } = ctx;
+  return { srcDir, backupDir, adapter, backup, dryRun, verbose, interactive, log };
+}
+
+async function runAutoApply(findings, ctx) {
+  ctx.log(`\n${'='.repeat(50)}`);
+  await applyFindings(findings, getAutoApplyOpts(ctx));
+}
+
+async function handleResults(findings, stats, ctx) {
+  await writeOutputs(findings, stats, ctx);
+  if (!ctx.dryRun) {
+    await initLanguageFiles(ctx.result, ctx);
+  }
+  if (ctx.autoApply) {
+    await runAutoApply(findings, ctx);
+  }
+}
+
+function buildRunContext(ctx, data) {
+  return { ...ctx, ...data, processedTemplates: new Set() };
+}
+
+function loadKeyMapping(keyMappingFile) {
+  return fs.existsSync(keyMappingFile) ? readJsonFileSync(keyMappingFile) || {} : {};
+}
+
+function initStats() {
+  return { files: 0, clean: 0, needsWork: 0, total: 0, added: 0, byContext: {} };
+}
+
+function logVerboseIfNeeded(findings, ctx) {
+  if (ctx.verbose && findings.length > 0) {
+    logVerboseFindings(findings, ctx);
+  }
+}
+
+async function scanAndPrepare(ctx) {
+  const keyMapping = loadKeyMapping(ctx.keyMappingFile);
+  const result = await loadMergeResult(ctx);
+  const stats = initStats();
+  const files = await collectFiles(ctx.srcDir, ctx.excludedFolders);
+  const runCtx = buildRunContext(ctx, { result, stats, keyMapping });
+  return { result, stats, findings: scanFiles(files, runCtx) };
+}
+
+async function processResults(data, ctx) {
+  logVerboseIfNeeded(data.findings, ctx);
+  logSummary(data.stats, ctx);
+  if (data.stats.total > 0) {
+    await handleResults(data.findings, data.stats, { ...ctx, result: data.result });
+  }
+}
+
+function buildExtractResult(data, strict) {
+  const { result, findings, stats } = data;
+  if (stats.total === 0) {
+    return { result, findings, stats, exitCode: 0, message: 'No untranslated strings found.' };
+  }
+  return { result, findings, stats, exitCode: strict ? 1 : 0 };
+}
+
+module.exports = {
+  name: 'extract',
+  category: 'extraction',
+  description: 'Extract i18n strings from source files',
+
+  options: [
+    { flag: '--src <path>', description: 'Source directory (default: src/app)' },
+    { flag: '--output <path>', description: 'Output JSON file' },
+    { flag: '--lang <code>', description: 'Language code for output file' },
+    { flag: '--merge', description: 'Merge with existing JSON file' },
+    { flag: '--include-translated', description: 'Include all strings' },
+    { flag: '--extract-ts-objects', description: 'Extract from TypeScript objects' },
+    { flag: '--format <type>', description: 'Output format: nested or flat' },
+    { flag: '--auto-apply', description: 'Extract AND apply in one command' },
+  ],
+
+  examples: ['i18nkit --dry-run', 'i18nkit --lang fr --merge', 'i18nkit --auto-apply --backup'],
+
+  async run(ctx) {
+    logHeader(ctx);
+    const data = await scanAndPrepare(ctx);
+    await processResults(data, ctx);
+    return buildExtractResult(data, ctx.strict);
+  },
+};

package/bin/commands/find-orphans.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * @fileoverview Find-orphans command - detects unused translation keys.
+ * Scans source files to identify keys not referenced in code.
+ * @module commands/find-orphans
+ */
+
+const { findOrphans } = require('../core');
+
+module.exports = {
+  name: 'find-orphans',
+  category: 'validation',
+  description: 'Find translation keys not used in source code',
+
+  options: [{ flag: '--strict', description: 'Exit with error if orphans found' }],
+
+  examples: ['i18nkit --find-orphans', 'i18nkit --find-orphans --strict'],
+
+  async run(ctx) {
+    const { srcDir, i18nDir, format, excludedFolders, verbose, strict, log, exitCodes } = ctx;
+
+    const result = await findOrphans({
+      srcDir,
+      i18nDir,
+      format,
+      excludedFolders,
+      verbose,
+      strict,
+      log,
+      exitCodes: { success: exitCodes.SUCCESS, untranslated: exitCodes.UNTRANSLATED },
+    });
+
+    return { exitCode: result.exitCode ?? exitCodes.SUCCESS };
+  },
+};

package/bin/commands/help.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * @fileoverview Help command - displays CLI usage and available commands.
+ * Auto-detects project type and shows relevant plugin information.
+ * @module commands/help
+ */
+
+const { generateFullHelp, detectProject, getResolver } = require('../core');
+
+module.exports = {
+  name: 'help',
+
+  run(ctx) {
+    const detected = detectProject(ctx.cwd);
+    const resolver = getResolver(ctx.cwd);
+    const { getAllCommands } = require('./index');
+
+    console.log(
+      generateFullHelp({
+        packageInfo: require('../../package.json'),
+        detected,
+        plugins: {
+          parsers: resolver.getByType('parser'),
+          adapters: resolver.getByType('adapter'),
+          providers: resolver.getByType('provider'),
+        },
+        commands: getAllCommands(),
+      }),
+    );
+
+    return { exitCode: 0 };
+  },
+};

package/bin/commands/index.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * @fileoverview CLI command registry with auto-discovery.
+ * Loads command modules from this directory and manages aliases.
+ * @module commands
+ */
+
+const fs = require('../core/fs-adapter');
+const path = require('path');
+
+/**
+ * @typedef {Object} Command
+ * @property {string} name
+ * @property {string} [category]
+ * @property {string} [description]
+ * @property {Array<string>} [aliases]
+ * @property {Array<Object>} [options]
+ * @property {Array<string>} [examples]
+ * @property {function} run
+ */
+
+const COMMANDS_DIR = __dirname;
+const EXCLUDED_FILES = ['index.js'];
+
+function loadCommand(filePath) {
+  try {
+    const cmd = require(filePath);
+    return cmd?.name && typeof cmd.run === 'function' ? cmd : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Auto-discover and load all command modules from this directory
+ * @returns {Map<string, Command>}
+ */
+function discoverCommands() {
+  const commands = new Map();
+
+  const files = fs
+    .readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.js') && !EXCLUDED_FILES.includes(f));
+
+  for (const file of files) {
+    const command = loadCommand(path.join(COMMANDS_DIR, file));
+    if (!command) {
+      continue;
+    }
+
+    commands.set(command.name, command);
+    command.aliases?.forEach(alias => commands.set(alias, command));
+  }
+
+  return commands;
+}
+
+const COMMANDS = discoverCommands();
+
+/**
+ * @param {string} name
+ * @returns {Command|undefined}
+ */
+function getCommand(name) {
+  return COMMANDS.get(name);
+}
+
+/**
+ * @returns {Command[]}
+ */
+function getAllCommands() {
+  return [...new Set(COMMANDS.values())];
+}
+
+module.exports = {
+  getCommand,
+  getAllCommands,
+};

package/bin/commands/translate.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * @fileoverview Translate command - automated translation via external APIs.
+ * Supports MyMemory (free) and DeepL (API key required).
+ * @module commands/translate
+ */
+
+const { translateFile } = require('../core');
+
+function parseTranslatePair(translatePair) {
+  return (translatePair || '').split(':');
+}
+
+function validateTranslatePair(source, target, exitCodes) {
+  if (!source || !target) {
+    console.error('Invalid --translate format. Use: --translate fr:en');
+    return { exitCode: exitCodes.ERROR };
+  }
+  return null;
+}
+
+function getTranslateOptions(ctx) {
+  const { i18nDir, provider, useDeepL, translateEmail, verbose, dryRun, log } = ctx;
+  return { i18nDir, provider, useDeepL, email: translateEmail, verbose, dryRun, log };
+}
+
+module.exports = {
+  name: 'translate',
+  category: 'translation',
+  description: 'Translate a language file to another language',
+
+  options: [
+    { flag: '--translate <src:tgt>', description: 'Source and target languages (e.g., fr:en)' },
+    { flag: '--deepl', description: 'Use DeepL API instead of MyMemory' },
+    { flag: '--email <email>', description: 'Email for MyMemory rate limits' },
+  ],
+
+  examples: ['i18nkit --translate fr:en', 'i18nkit --translate fr:en --deepl'],
+
+  async run(ctx) {
+    const { translatePair, exitCodes } = ctx;
+    const [source, target] = parseTranslatePair(translatePair);
+    const error = validateTranslatePair(source, target, exitCodes);
+    if (error) {
+      return error;
+    }
+    await translateFile(source, target, getTranslateOptions(ctx));
+    return { exitCode: exitCodes.SUCCESS };
+  },
+};

package/bin/commands/version.js

@@ -0,0 +1,17 @@
+'use strict';
+
+/**
+ * @fileoverview Version command - displays package and Node.js versions.
+ * @module commands/version
+ */
+
+module.exports = {
+  name: 'version',
+
+  run() {
+    const pkg = require('../../package.json');
+    console.log(`${pkg.name} v${pkg.version}`);
+    console.log(`Node.js ${process.version}`);
+    return { exitCode: 0 };
+  },
+};

package/bin/commands/watch.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * @fileoverview Watch command - file system watcher for incremental extraction.
+ * Monitors source files and re-runs extraction on changes.
+ * @module commands/watch
+ */
+
+const { watchFiles } = require('../core');
+const extract = require('./extract');
+
+module.exports = {
+  name: 'watch',
+  category: 'development',
+  description: 'Watch for file changes and re-run extraction',
+
+  examples: ['i18nkit --watch', 'i18nkit --watch --verbose'],
+
+  run(ctx) {
+    const { srcDir, excludedFolders, log } = ctx;
+
+    const runExtract = async () => {
+      try {
+        await extract.run(ctx);
+      } catch (err) {
+        console.error('Error:', err.message);
+      }
+    };
+
+    watchFiles({ srcDir, excludedFolders, log, onFileChange: runExtract, onStart: runExtract });
+
+    return { exitCode: null };
+  },
+};