i18ntk 2.6.0 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-05-05
+
+### Added
+- **`i18ntk-translate`**: Zero-dependency CLI tool that converts English source JSON locale files into any target language via Google's free Translate API.
+- **Placeholder protection**: Intelligent detection, masking, and unmasking of dynamic placeholder tokens (`{name}`, `{{count}}`, `%d`, `%s`, `:param`, `{{variable}}`, `%{name}`, `${var}`, etc.) to prevent corruption during translation.
+- **Custom regex support**: `--custom-regex` flag to define additional placeholder patterns for detection and protection.
+- **Interactive control flow**: Two-level user controls — global choice (skip all / send all / ask per key) and per-key interactive mode where each affected key can be individually flagged.
+- **Fully automated CLI mode**: `--no-confirm --skip-placeholders` or `--no-confirm --send-placeholders` flags for unattended CI/CD use.
+- **Post-translation report**: Comprehensive report (stdout, file, or both) listing every skipped key with its original value and a reminder for manual translation.
+- **Multi-file batch processing**: `--source-dir` and `--files` flags support translating all JSON files in a directory at once.
+- **Dry-run mode**: `--dry-run` flag previews which keys would be skipped without making API calls.
+- **UTF-8 BOM output**: `--bom` flag for output files with UTF-8 byte order mark.
+- **Custom translation function**: `--translate-fn` flag to inject an alternative translation API while maintaining the placeholder safety workflow.
+- **Rate-limit handling**: Exponential backoff/retry logic for Google Translate API rate limits and network errors.
+- **Deep JSON traversal**: Full support for nested objects and arrays, preserving data types, null values, and non-string leaf values.
+
+### Changed
+- Version bumped to 3.0.0 (major release with new translation tool feature).
+
 ## [2.6.0] - 2026-05-03
 
 ### Security

package/README.md

@@ -1,6 +1,6 @@
-# i18ntk v2.6.0
+# i18ntk v3.0.0
 
-Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, and translation completion.
+Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic locale translation, and runtime translation loading.
 
 ![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)
 
@@ -9,27 +9,25 @@ Zero-dependency internationalization toolkit for setup, scanning, analysis, vali
 [![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)
 [![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)
 [![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
-[![socket](https://socket.dev/api/badge/npm/package/i18ntk/2.6.0)](https://socket.dev/npm/package/i18ntk/overview/2.6.0)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/3.0.0)](https://socket.dev/npm/package/i18ntk/overview/3.0.0)
 
 ## Upgrade Notice
 
-Versions earlier than `2.6.0` may contain known stability and security issues.
-They are considered unsupported for production use. Upgrade to `2.6.0` or newer.
+Versions earlier than `3.0.0` may contain known stability and security issues.
+They are considered unsupported for production use. Upgrade to `3.0.0` or newer.
 
-## v2.6.0 — Deep-Code Audit Release
+## v3.0.0 - Auto Translate Release
 
-v2.6.0 is a comprehensive hardening release from a two-pass code audit fixing 35+ bugs and security issues across 18 files. Highlights:
+v3.0.0 adds automatic JSON locale translation through the management menu and the standalone `i18ntk-translate` command. Highlights:
 
-- **Critical**: Fixed silent-write failures where `safeWriteFileSync` was called incorrectly across 4 modules.
-- **Security**: Replaced all remaining raw `fs` calls with validated `SecurityUtils` wrappers.
-- **Security**: Fixed path traversal bypass in the fallback `SecurityUtils` implementation.
-- **Security**: Fixed Windows path traversal false negatives (fragile `path.sep` comparison).
-- **Security**: Added `safeUnlinkSync` and `safeRmdirSync` for validated file/directory deletion.
-- **Runtime**: Fixed process event handler leak, missing `setInterval.unref()`, and JSON parse error handling.
-- **TypeScript**: Fixed `BasicI18nRuntime.translate/t` return type from `Promise<string>` to `string`.
-- **Scripts**: Fixed `npm_execpath` fallback in build/release scripts.
+- **Auto Translate (Beta)**: Translate one or more source JSON files into one or more target languages from menu option 14.
+- **Standalone CLI**: Use `i18ntk-translate <source-file> <target-lang>` for direct automation and batch translation.
+- **Dry-run preview**: Review translated/skipped counts before writing target files.
+- **Placeholder protection**: Detect and preserve placeholders such as `{name}`, `{{count}}`, `%s`, `%d`, `:id`, `%{name}`, and `${value}`.
+- **Post-translation report**: Print or write translated and skipped key counts.
+- **Zero dependencies**: Translation support uses built-in Node.js modules and the free Google Translate endpoint.
 
-For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migration notes, see [docs/migration-guide-v2.6.0.md](./docs/migration-guide-v2.6.0.md).
+For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migration notes, see [docs/migration-guide-v3.0.0.md](./docs/migration-guide-v3.0.0.md).
 
 ## What i18ntk Does
 
@@ -38,6 +36,7 @@ For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migrati
 - Translation completeness analysis and usage tracking
 - Validation, sizing, and summary reporting
 - Missing-key completion and fixer workflows
+- Automatic translation of JSON locale files
 - Runtime translation helpers for application code
 - Support for JS/TS, React, Vue, Angular, and generic projects
 
@@ -48,6 +47,7 @@ For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migrati
 3. Confirm the source language and locale directories.
 4. Run `i18ntk --command=analyze` or `i18ntk --command=validate` to inspect translation coverage.
 5. Use `i18ntk --command=complete` to fill missing keys when needed.
+6. Use `i18ntk --command=translate` or menu option 14 to auto-translate source JSON files.
 
 The full onboarding flow is documented in [docs/getting-started.md](docs/getting-started.md).
 
@@ -100,6 +100,7 @@ i18ntk --command=usage
 i18ntk --command=scanner
 i18ntk --command=sizing
 i18ntk --command=complete
+i18ntk --command=translate
 i18ntk --command=summary
 ```
 
@@ -117,6 +118,7 @@ i18ntk-summary
 i18ntk-doctor
 i18ntk-fixer
 i18ntk-backup
+i18ntk-translate
 ```
 
 Note: `i18ntk --command=backup` in the manager flow is disabled in current builds.
@@ -133,12 +135,42 @@ Use the standalone `i18ntk-backup` executable when backup operations are require
 - `--dry-run`
 - `--help`
 
+Auto Translate also supports:
+
+- `--source-lang <code>`
+- `--files <pattern>`
+- `--skip-placeholders`
+- `--send-placeholders`
+- `--report-file <path>`
+- `--report-stdout`
+
 Example:
 
 ```bash
 i18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports
 ```
 
+## Auto Translate
+
+Interactive menu flow:
+
+```bash
+i18ntk
+# choose "Auto Translate (Beta)"
+```
+
+Direct CLI examples:
+
+```bash
+i18ntk-translate locales/en/common.json de
+i18ntk-translate locales/en/common.json fr --dry-run --report-stdout
+i18ntk-translate locales/en es --files "*.json" --no-confirm --skip-placeholders
+```
+
+The manager flow accepts comma- or space-separated target language codes, previews the first target language with a dry run, asks for confirmation, then writes translated files under matching target-language directories such as `locales/de/common.json`.
+
+See [docs/auto-translate.md](docs/auto-translate.md) for full usage details.
+
 ## Runtime API
 
 Use `i18ntk/runtime` when your application needs to read locale JSON files at runtime.
@@ -169,7 +201,7 @@ Example `.i18ntk-config`:
 
 ```json
 {
-  "version": "2.6.0",
+  "version": "3.0.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -190,11 +222,12 @@ See [docs/api/CONFIGURATION.md](docs/api/CONFIGURATION.md) for the full configur
 - [API Reference](https://github.com/vladnoskv/i18ntk/blob/main/docs/api/API_REFERENCE.md)
 - [Configuration Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/api/CONFIGURATION.md)
 - [Runtime API Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/runtime.md)
+- [Auto Translate Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/auto-translate.md)
 - [Scanner Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/scanner-guide.md)
 - [Environment Variables](https://github.com/vladnoskv/i18ntk/blob/main/docs/environment-variables.md)
+- [Migration Guide v3.0.0](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v3.0.0.md)
 - [Migration Guide v2.6.0](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v2.6.0.md)
 - [Migration Guide v2.5.1](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v2.5.1.md)
-- [Migration Guide v2.5.0](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v2.5.0.md)
 
 ## Community
 

package/main/i18ntk-translate.js

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+
+/**
+ * I18NTK TRANSLATION GENERATOR
+ *
+ * Zero-dependency translation utility that converts English source JSON
+ * language files into any target language via Google's free Translate API.
+ *
+ * Usage:
+ *   i18ntk-translate <source-file> <target-lang> [options]
+ *   i18ntk-translate locales/en/common.json de
+ *   i18ntk-translate locales/en/common.json fr --no-confirm --skip-placeholders
+ *   i18ntk-translate locales/en/common.json es --dry-run
+ *
+ * Options:
+ *   --source-dir <dir>         Source directory (default: ./locales/en)
+ *   --output-dir <dir>         Output directory (default: ./locales/<lang>)
+ *   --custom-regex <regex>     Additional placeholder regex pattern
+ *   --no-confirm               Skip all confirmation dialogs
+ *   --skip-placeholders        Skip all strings containing placeholders
+ *   --send-placeholders        Translate all strings including placeholders
+ *   --concurrency <n>          Max concurrent API requests (default: 3)
+ *   --dry-run                  Preview mode without API calls
+ *   --report-file <path>       Write report to file
+ *   --report-stdout            Print report to stdout
+ *   --bom                      Output UTF-8 with BOM
+ *   --translate-fn <module>    Path to custom translation function module
+ *   --retry-count <n>          Max retries per request (default: 3)
+ *   --retry-delay <ms>         Base delay for retry backoff (default: 1000)
+ *   --timeout <ms>             HTTP request timeout (default: 15000)
+ *   --source-lang <code>       Source language code (default: en)
+ *   --files <pattern>          Glob pattern for multiple files (e.g. *.json)
+ *   -h, --help                 Show help
+ */
+
+const fs = require('fs');
+const path = require('path');
+const packageJson = require('../package.json');
+const ExitCodes = require('../utils/exit-codes');
+const { isInteractive } = require('../utils/prompt-helper');
+const { detectPlaceholders, maskPlaceholders, unmaskPlaceholders } = require('../utils/translate/placeholder');
+const { translateBatch } = require('../utils/translate/api');
+const { collectLeaves, setLeaf, deepClone } = require('../utils/translate/traverse');
+const { generateReport, writeReport, formatSummaryLine } = require('../utils/translate/report');
+const {
+  confirmGlobalChoice,
+  confirmPerKey,
+  previewSkipped,
+} = require('../utils/translate/cli');
+
+const BOM = '\uFEFF';
+
+function printHelp() {
+  console.log([
+    '',
+    `I18NTK Translation Generator - v${packageJson.version}`,
+    '',
+    'Usage:',
+    '  i18ntk-translate <source-file> <target-lang> [options]',
+    '  i18ntk-translate <source-file> <target-lang> --source-dir <dir> [options]',
+    '',
+    'Examples:',
+    '  i18ntk-translate locales/en/common.json de',
+    '  i18ntk-translate locales/en/common.json fr --dry-run',
+    '  i18ntk-translate locales/en/ es --files "*.json"',
+    '  i18ntk-translate locales/en/common.json ja --no-confirm --skip-placeholders',
+    '  i18ntk-translate locales/en/common.json ko --report-file report.txt',
+    '',
+    'Options:',
+    '  --source-dir <dir>         Source directory containing locale files',
+    '  --output-dir <dir>         Output directory for translated files',
+    '  --source-lang <code>       Source language code (default: en)',
+    '  --custom-regex <regex>     Additional placeholder regex pattern',
+    '  --no-confirm               Automate: skip confirmation dialogs',
+    '  --skip-placeholders        Skip all strings with placeholder tokens',
+    '  --send-placeholders        Translate all strings including placeholders',
+    '  --concurrency <n>          Max concurrent API requests (default: 3)',
+    '  --dry-run                  Preview: show what would be skipped',
+    '  --report-file <path>       Write post-translation report to file',
+    '  --report-stdout            Print post-translation report to stdout',
+    '  --bom                      Write output files with UTF-8 BOM',
+    '  --translate-fn <module>    Path to custom translation function module',
+    '  --retry-count <n>          Max retries per failed request (default: 3)',
+    '  --retry-delay <ms>         Base backoff delay in ms (default: 1000)',
+    '  --timeout <ms>             HTTP request timeout in ms (default: 15000)',
+    '  -h, --help                 Show this help',
+  ].join('\n'));
+}
+
+function parseArgs(argv) {
+  const args = {
+    sourceFile: null,
+    targetLang: null,
+    sourceDir: null,
+    outputDir: null,
+    sourceLang: 'en',
+    customRegex: [],
+    noConfirm: false,
+    skipPlaceholders: false,
+    sendPlaceholders: false,
+    concurrency: 3,
+    dryRun: false,
+    reportFile: null,
+    reportStdout: false,
+    bom: false,
+    translateFnPath: null,
+    retryCount: 3,
+    retryDelay: 1000,
+    timeout: 15000,
+    filesPattern: null,
+    help: false,
+    unknown: [],
+  };
+
+  const positional = [];
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '-h' || arg === '--help') { args.help = true; }
+    else if (arg === '--no-confirm') { args.noConfirm = true; }
+    else if (arg === '--skip-placeholders') { args.skipPlaceholders = true; }
+    else if (arg === '--send-placeholders') { args.sendPlaceholders = true; }
+    else if (arg === '--dry-run') { args.dryRun = true; }
+    else if (arg === '--report-stdout') { args.reportStdout = true; }
+    else if (arg === '--bom') { args.bom = true; }
+    else if (arg === '--source-dir' && i + 1 < argv.length) { args.sourceDir = argv[++i]; }
+    else if (arg === '--output-dir' && i + 1 < argv.length) { args.outputDir = argv[++i]; }
+    else if (arg === '--source-lang' && i + 1 < argv.length) { args.sourceLang = argv[++i]; }
+    else if (arg === '--custom-regex' && i + 1 < argv.length) { args.customRegex.push(argv[++i]); }
+    else if (arg === '--concurrency' && i + 1 < argv.length) { args.concurrency = parseInt(argv[++i], 10) || 3; }
+    else if (arg === '--report-file' && i + 1 < argv.length) { args.reportFile = argv[++i]; }
+    else if (arg === '--translate-fn' && i + 1 < argv.length) { args.translateFnPath = argv[++i]; }
+    else if (arg === '--retry-count' && i + 1 < argv.length) { args.retryCount = parseInt(argv[++i], 10) || 3; }
+    else if (arg === '--retry-delay' && i + 1 < argv.length) { args.retryDelay = parseInt(argv[++i], 10) || 1000; }
+    else if (arg === '--timeout' && i + 1 < argv.length) { args.timeout = parseInt(argv[++i], 10) || 15000; }
+    else if (arg === '--files' && i + 1 < argv.length) { args.filesPattern = argv[++i]; }
+    else if (arg.startsWith('-')) { args.unknown.push(arg); }
+    else { positional.push(arg); }
+  }
+
+  if (positional.length >= 1) args.sourceFile = positional[0];
+  if (positional.length >= 2) args.targetLang = positional[1];
+
+  if (args.sendPlaceholders && args.skipPlaceholders) {
+    console.error('Error: --skip-placeholders and --send-placeholders are mutually exclusive.');
+    process.exit(1);
+  }
+
+  return args;
+}
+
+function loadCustomTranslateFn(modulePath) {
+  if (!modulePath) return null;
+  try {
+    const resolved = path.isAbsolute(modulePath) ? modulePath : path.resolve(process.cwd(), modulePath);
+    const mod = require(resolved);
+    if (typeof mod === 'function') return mod;
+    if (mod && typeof mod.translate === 'function') return mod.translate;
+    if (mod && typeof mod.default === 'function') return mod.default;
+    console.error(`Warning: Custom translate module "${modulePath}" does not export a function.`);
+    return null;
+  } catch (e) {
+    console.error(`Error: Failed to load translate function module "${modulePath}": ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function resolveSourceFiles(sourceFile, sourceDir, filesPattern) {
+  if (sourceDir) {
+    const resolvedDir = path.resolve(process.cwd(), sourceDir);
+    if (!fs.existsSync(resolvedDir)) {
+      console.error(`Error: Source directory "${resolvedDir}" does not exist.`);
+      process.exit(1);
+    }
+    const entries = fs.readdirSync(resolvedDir);
+    const pattern = filesPattern || '*.json';
+    const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+    const files = entries.filter((f) => regex.test(f) && f.endsWith('.json')).sort();
+    if (files.length === 0) {
+      console.error(`Error: No JSON files matching "${pattern}" found in "${resolvedDir}".`);
+      process.exit(1);
+    }
+    return files.map((f) => path.join(resolvedDir, f));
+  }
+
+  if (sourceFile) {
+    const resolved = path.resolve(process.cwd(), sourceFile);
+    if (!fs.existsSync(resolved)) {
+      console.error(`Error: Source file "${resolved}" does not exist.`);
+      process.exit(1);
+    }
+    return [resolved];
+  }
+
+  console.error('Error: No source file specified. Use --source-dir or provide a source file.');
+  process.exit(1);
+}
+
+function classifyLeaves(leaves, customRegex) {
+  const withPlaceholders = [];
+  const withoutPlaceholders = [];
+
+  for (const leaf of leaves) {
+    const placeholders = detectPlaceholders(leaf.value, customRegex);
+    if (placeholders.length > 0) {
+      withPlaceholders.push({ ...leaf, placeholders });
+    } else {
+      withoutPlaceholders.push(leaf);
+    }
+  }
+
+  return { withPlaceholders, withoutPlaceholders };
+}
+
+async function resolvePlaceholderStrategy(args) {
+  const interactive = isInteractive({ noPrompt: args.noConfirm });
+
+  if (args.sendPlaceholders) {
+    return { strategy: 'send', interactiveMode: false };
+  }
+  if (args.skipPlaceholders) {
+    return { strategy: 'skip', interactiveMode: false };
+  }
+  if (args.noConfirm) {
+    return { strategy: 'skip', interactiveMode: false };
+  }
+  if (!interactive) {
+    return { strategy: 'skip', interactiveMode: false };
+  }
+
+  const choice = await confirmGlobalChoice();
+  return { strategy: choice.strategy, interactiveMode: choice.interactive };
+}
+
+async function resolvePerKeyDecisions(withPlaceholders, interactive) {
+  const decisions = {};
+
+  if (!interactive) {
+    for (const leaf of withPlaceholders) {
+      decisions[leaf.keyPath] = 'skip';
+    }
+    return decisions;
+  }
+
+  let bulkDecision = null;
+  for (const leaf of withPlaceholders) {
+    if (bulkDecision) {
+      decisions[leaf.keyPath] = bulkDecision;
+      continue;
+    }
+    const choice = await confirmPerKey(leaf.keyPath, leaf.value, leaf.placeholders);
+    if (choice === 'skip-all') {
+      bulkDecision = 'skip';
+      decisions[leaf.keyPath] = 'skip';
+    } else if (choice === 'send-all') {
+      bulkDecision = 'send';
+      decisions[leaf.keyPath] = 'send';
+    } else {
+      decisions[leaf.keyPath] = choice;
+    }
+  }
+
+  return decisions;
+}
+
+function buildTranslateList(withPlaceholders, withoutPlaceholders, strategy, decisions) {
+  const toTranslate = [];
+  const toSkip = [];
+
+  for (const leaf of withoutPlaceholders) {
+    toTranslate.push(leaf);
+  }
+
+  if (strategy === 'send') {
+    for (const leaf of withPlaceholders) {
+      toTranslate.push(leaf);
+    }
+  } else {
+    for (const leaf of withPlaceholders) {
+      const decision = decisions[leaf.keyPath] || 'skip';
+      if (decision === 'send') {
+        toTranslate.push(leaf);
+      } else {
+        toSkip.push(leaf);
+      }
+    }
+  }
+
+  return { toTranslate, toSkip };
+}
+
+function maskAllForTranslation(toTranslate, customRegex) {
+  return toTranslate.map((leaf) => {
+    const { masked, map } = maskPlaceholders(leaf.value, customRegex);
+    return { ...leaf, masked, placeholderMap: map, needsUnmask: map.size > 0 };
+  });
+}
+
+async function runTranslation(maskedBatch, targetLang, options) {
+  const batchItems = maskedBatch.map((item) => ({ value: item.masked, keyPath: item.keyPath }));
+  const results = await translateBatch(batchItems, targetLang, options);
+  return results;
+}
+
+function applyResults(sourceData, translatedResults, maskedBatch, toSkip, bom) {
+  const output = deepClone(sourceData);
+
+  for (let i = 0; i < maskedBatch.length; i++) {
+    const item = maskedBatch[i];
+    const translated = translatedResults[i];
+    let finalValue;
+    if (item.needsUnmask) {
+      finalValue = unmaskPlaceholders(translated, item.placeholderMap);
+    } else {
+      finalValue = translated;
+    }
+    setLeaf(output, item.keyPath, finalValue);
+  }
+
+  for (const leaf of toSkip) {
+    setLeaf(output, leaf.keyPath, leaf.value);
+  }
+
+  return output;
+}
+
+function writeOutput(outputData, outputPath, bom) {
+  const dir = path.dirname(outputPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  let content = JSON.stringify(outputData, null, 2) + '\n';
+  if (bom) {
+    content = BOM + content;
+  }
+  fs.writeFileSync(outputPath, content, 'utf-8');
+}
+
+async function processFile(sourcePath, targetLang, args) {
+  const fileName = path.basename(sourcePath);
+  const targetDir = args.outputDir || path.join(path.dirname(path.dirname(sourcePath)), targetLang);
+  const targetPath = path.join(targetDir, fileName);
+
+  let sourceData;
+  try {
+    const raw = fs.readFileSync(sourcePath, 'utf-8');
+    sourceData = JSON.parse(raw);
+  } catch (e) {
+    console.error(`Error reading "${sourcePath}": ${e.message}`);
+    return null;
+  }
+
+  const leaves = collectLeaves(sourceData);
+  if (leaves.length === 0) {
+    console.log(`[${fileName}] No translatable strings found.`);
+    writeOutput(sourceData, targetPath, args.bom);
+    return { total: 0, translated: 0, skipped: 0, skippedKeys: [] };
+  }
+
+  const { withPlaceholders, withoutPlaceholders } = classifyLeaves(leaves, args.customRegex);
+
+  if (args.dryRun && withPlaceholders.length > 0) {
+    await previewSkipped(withPlaceholders);
+    return {
+      total: leaves.length,
+      translated: withoutPlaceholders.length,
+      skipped: withPlaceholders.length,
+      skippedKeys: withPlaceholders,
+      dryRun: true,
+    };
+  }
+
+  if (args.dryRun) {
+    console.log(`[${fileName}] Dry-run: ${leaves.length} strings, all would be translated.`);
+    return {
+      total: leaves.length,
+      translated: leaves.length,
+      skipped: 0,
+      skippedKeys: [],
+      dryRun: true,
+    };
+  }
+
+  const { strategy, interactiveMode } = await resolvePlaceholderStrategy(args);
+  const decisions = await resolvePerKeyDecisions(withPlaceholders, interactiveMode);
+  const { toTranslate, toSkip } = buildTranslateList(withPlaceholders, withoutPlaceholders, strategy, decisions);
+
+  if (toSkip.length > 0) {
+    console.log(`[${fileName}] Skipping ${toSkip.length} keys with placeholders.`);
+  }
+
+  const maskedBatch = maskAllForTranslation(toTranslate, args.customRegex);
+
+  const translateOptions = {
+    sourceLang: args.sourceLang,
+    concurrency: args.concurrency,
+    retryCount: args.retryCount,
+    retryDelay: args.retryDelay,
+    timeout: args.timeout,
+    customFn: args.translateFn,
+    onProgress: (info) => {
+      if (info.completed % 10 === 0 || info.completed === info.total) {
+        process.stdout.write(`\r[${fileName}] Translating... ${info.completed}/${info.total}`);
+      }
+    },
+    onError: (err) => {
+      console.error(`\n[${fileName}] Warning: Failed to translate key "${err.item.keyPath}": ${err.message}`);
+    },
+  };
+
+  let translatedResults;
+  if (maskedBatch.length > 0) {
+    translatedResults = await runTranslation(maskedBatch, targetLang, translateOptions);
+    process.stdout.write('\n');
+  } else {
+    translatedResults = [];
+  }
+
+  const output = applyResults(sourceData, translatedResults, maskedBatch, toSkip, args.bom);
+  writeOutput(output, targetPath, args.bom);
+
+  console.log(`[${fileName}] Written: ${targetPath}`);
+
+  return {
+    total: leaves.length,
+    translated: translatedResults.length,
+    skipped: toSkip.length,
+    skippedKeys: toSkip,
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.help) {
+    printHelp();
+    process.exit(ExitCodes.SUCCESS);
+  }
+
+  if (args.unknown.length > 0) {
+    console.error(`Unknown options: ${args.unknown.join(', ')}`);
+    console.error('Use --help for usage information.');
+    process.exit(1);
+  }
+
+  if (!args.targetLang) {
+    console.error('Error: Target language code is required.');
+    console.error('Usage: i18ntk-translate <source-file> <target-lang> [options]');
+    process.exit(1);
+  }
+
+  if (args.translateFnPath) {
+    args.translateFn = loadCustomTranslateFn(args.translateFnPath);
+  }
+
+  const sourceFiles = resolveSourceFiles(args.sourceFile, args.sourceDir, args.filesPattern);
+
+  const allSkippedKeys = [];
+  let grandTotal = 0;
+  let grandTranslated = 0;
+  let grandSkipped = 0;
+
+  for (const srcPath of sourceFiles) {
+    const result = await processFile(srcPath, args.targetLang, args);
+    if (result) {
+      grandTotal += result.total;
+      grandTranslated += result.translated;
+      grandSkipped += result.skipped;
+      if (result.skippedKeys && result.skippedKeys.length > 0) {
+        allSkippedKeys.push(...result.skippedKeys);
+      }
+    }
+  }
+
+  console.log('');
+  console.log(formatSummaryLine(grandSkipped, grandTranslated, grandTotal));
+
+  if (allSkippedKeys.length > 0 || args.reportFile || args.reportStdout) {
+    const report = generateReport(allSkippedKeys, grandTranslated, grandTotal, {
+      sourceFile: sourceFiles.length === 1 ? sourceFiles[0] : `${sourceFiles.length} files`,
+      targetLang: args.targetLang,
+      dryRun: args.dryRun,
+    });
+
+    if (args.reportStdout || (!args.reportFile && allSkippedKeys.length > 0)) {
+      console.log('');
+      console.log(report);
+    }
+
+    if (args.reportFile) {
+      const reportPath = path.resolve(process.cwd(), args.reportFile);
+      writeReport(report, reportPath);
+      console.log(`Report written: ${reportPath}`);
+    }
+  }
+
+  process.exit(ExitCodes.SUCCESS);
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err.message);
+  process.exit(1);
+});