i18ntk 4.2.0 → 4.2.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## [4.2.1] - 2026-05-31
+
+### Changed
+- Auto Translate now treats uppercase target-language placeholders such as `[AR] What We Offer` as untranslated target values when the bracketed code matches the target language, so target-aware mode sends the source text for translation instead of keeping the placeholder copy.
+- Auto Translate now performs a final pre-write leftover check and retries values that still look like placeholder-prefixed untranslated text, untranslated markers, source-language copies, or broken output.
+- Auto Translate reports leftover values in the post-translation report and exits with validation failure when leftovers remain after the final retry, instead of reporting a clean completion.
+
+### Fixed
+- Usage analysis no longer writes its inferred app source fallback, such as `src`, back into the shared locale configuration when `sourceDir` and `i18nDir` are both the locale directory.
+- Manager sizing now reads the configured i18n directory unless `--source-dir` is explicitly provided, so running sizing after usage no longer silently analyzes the wrong directory.
+- Manager sizing now treats a failed sizing analysis as a command failure instead of printing a generic operation success.
+- Validation summary reports now include warning and error details, including content-risk warning payloads, instead of only totals.
+
 ## [4.2.0] - 2026-05-30
 
 ### Security

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v4.2.0
+# i18ntk v4.2.1
 
 A i18n toolkit - A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
 
@@ -9,7 +9,7 @@ A i18n toolkit - A zero-dependency internationalization toolkit for setup, scann
 [![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/4.2.0)](https://socket.dev/npm/package/i18ntk/overview/4.2.0)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.2.1)](https://socket.dev/npm/package/i18ntk/overview/4.2.1)
 
 ## Install
 
@@ -30,20 +30,14 @@ Requirements:
 - npm `>=8.0.0`
 - No runtime dependencies
 
-## What's New in 4.2.0
-
-- **SECURITY**: Hardened path containment for restore and shared filesystem helpers, including artifact-like filenames, environment-added internal prefixes, and Windows cross-drive paths.
-- **SECURITY**: Runtime locale loading now rejects unsafe language identifiers before resolving locale files, preventing `../` language names from reading JSON outside the configured locale base.
-- **SECURITY**: Auto Translate provider URL checks now block IPv4-mapped IPv6 private/loopback hosts.
-- **REPORTS**: Init and analysis reports now default to readable Markdown. Set `reports.format` to `markdown`, `json`, or `text` in Settings or `.i18ntk-config`.
-- **USAGE**: Usage analysis no longer scans the project root when locales are also configured as the source directory, avoiding inflated missing-key counts.
-- **I18N UX**: Init backup prompts, completion summaries, report prompts, default target languages, and native yes/no confirmations are now localized.
-- **AUTO TRANSLATE**: Auto Translate is out of beta, keeps existing translated target values by default, and only sends missing/source-copy/likely-English strings unless `--translate-all` is used.
-- **AUTO TRANSLATE**: Google Auto Translate concurrency now defaults to 12 and can be raised up to 100 for larger locale sets.
-- **AUTO TRANSLATE**: Corrupt target strings such as `?????`, replacement characters, and common mojibake are now repaired from the English source, and progress output distinguishes key translation from placeholder-safe text-segment translation.
-- **CLI UX**: Manager menu spacing is grouped and aligned, and validation no longer prints duplicate source/i18n/output directory blocks.
-- **DOCS**: Versioned docs and migration guidance now reflect the current 4.2.0 command surface.
-- **CLEANUP**: Removed stale duplicate fixed artifacts from the development tree to reduce audit and supply-chain drift.
+## What's New in 4.2.1
+
+- **AUTO TRANSLATE**: Existing target values like `[AR] What We Offer` are now treated as untranslated placeholders for the matching target language and are translated from the source text.
+- **AUTO TRANSLATE**: Before writing each output file, Auto Translate now performs a final leftover check and retries any placeholder-prefixed or source-copy values once.
+- **AUTO TRANSLATE**: If leftovers remain after the final retry, the command warns, includes them in the report, recommends rerunning Auto Translate, and exits with validation failure instead of reporting a clean completion.
+- **SIZING/USAGE**: Usage analysis no longer writes its inferred app source fallback back into the shared locale config, so running usage before sizing no longer makes sizing analyze the wrong directory.
+- **VALIDATION REPORTS**: Validation summary files now include warning and error details, including English-content warning payloads, instead of only totals.
+- **DOCS**: Versioned docs and migration guidance now reflect the current 4.2.1 command surface.
 
 ## What's New in 4.1.0
 
@@ -509,7 +503,7 @@ Example:
 
 ```json
 {
-  "version": "4.2.0",
+  "version": "4.2.1",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -571,7 +565,7 @@ The public package manifest includes `readmeFilename: "README.md"`, and the rele
 - [Auto Translate Guide](./docs/auto-translate.md)
 - [Scanner Guide](./docs/scanner-guide.md)
 - [Environment Variables](./docs/environment-variables.md)
-- [Migration Guide v4.2.0](./docs/migration-guide-v4.2.0.md)
+- [Migration Guide v4.2.1](./docs/migration-guide-v4.2.1.md)
 
 ## Security
 

package/main/i18ntk-sizing.js

@@ -31,12 +31,13 @@
  *   i18ntk sizing --threshold=30 --output-report
  */
 
-const fs = require('fs');
-const path = require('path');
-const { loadTranslations, t } = require('../utils/i18n-helper');
-const configManager = require('../settings/settings-manager');
-const SecurityUtils = require('../utils/security');
-const { getUnifiedConfig } = require('../utils/config-helper');
+const fs = require('fs');
+const path = require('path');
+const { loadTranslations, t } = require('../utils/i18n-helper');
+const configManager = require('../settings/settings-manager');
+const projectConfigManager = require('../utils/config-manager');
+const SecurityUtils = require('../utils/security');
+const { getUnifiedConfig } = require('../utils/config-helper');
 const { logger } = require('../utils/logger');
 const { getGlobalReadline, closeGlobalReadline } = require('../utils/cli');
 const SetupEnforcer = require('../utils/setup-enforcer');
@@ -1120,8 +1121,10 @@ Generated: ${new Date().toISOString()}
       'l': '',
       'o': true,
       'f': 'table',
-      't': 50,
-      'd': false
+      't': 50,
+      'd': false,
+      sourceDirExplicit: false,
+      outputDirExplicit: false
     };
 
     for (let i = 0; i < args.length; i++) {
@@ -1138,9 +1141,10 @@ Generated: ${new Date().toISOString()}
         const key = keyValueMatch[1];
         const value = keyValueMatch[2];
         
-        if (key === 'source-dir' || key === 's') {
-          options['source-dir'] = value;
-          options.s = value;
+        if (key === 'source-dir' || key === 's') {
+          options['source-dir'] = value;
+          options.s = value;
+          options.sourceDirExplicit = true;
         } else if (key === 'languages' || key === 'l') {
           options.languages = value;
           options.l = value;
@@ -1167,9 +1171,10 @@ Generated: ${new Date().toISOString()}
           options['detailed-keys'] = value.toLowerCase() !== 'false';
         } else if (key === 'predict-expansion') {
           options['predict-expansion'] = value.toLowerCase() !== 'false';
-        } else if (key === 'output-dir') {
-          options['output-dir'] = value;
-        }
+        } else if (key === 'output-dir') {
+          options['output-dir'] = value;
+          options.outputDirExplicit = true;
+        }
         continue;
       }
       
@@ -1179,10 +1184,11 @@ Generated: ${new Date().toISOString()}
         const key = match[1];
         const nextArg = args[i + 1];
         
-        if (key === 'source-dir' || key === 's') {
-          options['source-dir'] = nextArg || options['source-dir'];
-          options.s = options['source-dir'];
-          if (nextArg && !nextArg.startsWith('-')) i++;
+        if (key === 'source-dir' || key === 's') {
+          options['source-dir'] = nextArg || options['source-dir'];
+          options.s = options['source-dir'];
+          options.sourceDirExplicit = true;
+          if (nextArg && !nextArg.startsWith('-')) i++;
         } else if (key === 'languages' || key === 'l') {
           options.languages = nextArg || options.languages;
           options.l = options.languages;
@@ -1238,6 +1244,7 @@ Generated: ${new Date().toISOString()}
           }
         } else if (key === 'output-dir') {
           options['output-dir'] = nextArg || options['output-dir'];
+          options.outputDirExplicit = true;
           if (nextArg && !nextArg.startsWith('-')) i++;
         }
       }
@@ -1268,15 +1275,25 @@ Options:
     return options;
   }
 
-  // Add run method for compatibility with manager
-  async run(options = {}) {
-    const { fromMenu = false } = options;
-    
-    const args = this.parseArgs();
-    const config = await getUnifiedConfig('sizing', args);
-
-    this.sourceDir = path.resolve(config.projectRoot || '.', config.sourceDir || './locales');
-    this.outputDir = path.resolve(config.projectRoot || '.', config.outputDir || './i18ntk-reports');
+  // Add run method for compatibility with manager
+  async run(options = {}) {
+    const { fromMenu = false } = options;
+
+    const args = this.parseArgs();
+    const commonArgs = {};
+    if (args.sourceDirExplicit) commonArgs.sourceDir = args['source-dir'];
+    if (args.outputDirExplicit) commonArgs.outputDir = args['output-dir'];
+    if (args['source-language']) commonArgs.sourceLanguage = args['source-language'];
+    const persistedConfig = projectConfigManager.getConfig();
+    const config = await getUnifiedConfig('sizing', commonArgs);
+    const projectRoot = config.projectRoot || persistedConfig.projectRoot || process.cwd();
+    const configuredSizingDir = persistedConfig.scriptDirectories?.sizing;
+    const translationDir = args.sourceDirExplicit
+      ? args['source-dir']
+      : (configuredSizingDir || persistedConfig.i18nDir || persistedConfig.sourceDir || config.i18nDir || config.sourceDir || './locales');
+
+    this.sourceDir = path.resolve(projectRoot, translationDir);
+    this.outputDir = path.resolve(config.projectRoot || '.', config.outputDir || './i18ntk-reports');
     this.threshold = args.threshold ?? config.processing?.sizingThreshold ?? 50;
     this.languages = args.languages ? args.languages.split(',').map(l => l.trim()) : [];
     this.outputReport = args['output-report'] !== undefined ? args['output-report'] : false;

package/main/i18ntk-translate.js

@@ -338,6 +338,36 @@ function isLikelyEnglish(value, args) {
   return analysis.englishPercentage > threshold && analysis.englishWordCount >= 2;
 }
 
+function normalizeLanguageCode(language) {
+  return String(language || '').trim().toLowerCase().replace(/_/g, '-').split('-')[0];
+}
+
+function parseLanguagePrefix(value) {
+  if (typeof value !== 'string') return null;
+  const match = value.match(/^\s*\[([A-Z]{2,3}(?:[-_][A-Z0-9]{2,4})?)\]\s*(.+)$/);
+  if (!match) return null;
+  return {
+    raw: match[1],
+    language: normalizeLanguageCode(match[1]),
+    text: match[2].trim(),
+  };
+}
+
+function hasLatinWordContent(value, minWords = 2) {
+  const words = String(value || '').match(/[A-Za-z][A-Za-z'-]*/g) || [];
+  return words.filter(word => word.length > 1).length >= minWords;
+}
+
+function isLanguagePrefixedEnglish(value, args = {}) {
+  const prefix = parseLanguagePrefix(value);
+  if (!prefix || !prefix.text) return false;
+
+  const targetLanguage = normalizeLanguageCode(args.targetLang);
+  if (targetLanguage && prefix.language !== targetLanguage) return false;
+
+  return hasLatinWordContent(prefix.text, 2) || isLikelyEnglish(prefix.text, args);
+}
+
 function isBrokenTranslationValue(value) {
   if (typeof value !== 'string') return false;
   const text = value.trim();
@@ -368,11 +398,22 @@ function shouldTranslateTargetValue(sourceValue, targetValue, args) {
   if (typeof targetValue !== 'string') return true;
   if (isUntranslatedMarker(targetValue)) return true;
   if (isBrokenTranslationValue(targetValue)) return true;
+  if (isLanguagePrefixedEnglish(targetValue, args)) return true;
   if (targetValue.trim() === String(sourceValue ?? '').trim()) return true;
   if (args.onlyMissingOrEnglish !== false && isLikelyEnglish(targetValue, args)) return true;
   return args.onlyMissingOrEnglish === false;
 }
 
+function getResidualUntranslatedReason(sourceValue, targetValue, args) {
+  if (targetValue === undefined || targetValue === null) return 'missing';
+  if (typeof targetValue !== 'string') return 'non_string';
+  if (isUntranslatedMarker(targetValue)) return 'marker';
+  if (isBrokenTranslationValue(targetValue)) return 'broken';
+  if (isLanguagePrefixedEnglish(targetValue, args)) return 'language_prefix';
+  if (targetValue.trim() === String(sourceValue ?? '').trim()) return 'source_copy';
+  return null;
+}
+
 function planTargetAwareLeaves(sourceLeaves, targetData, args) {
   if (!targetData || args.onlyMissingOrEnglish === false) {
     return {
@@ -712,6 +753,41 @@ function applyResults(sourceData, translatedResults, toTranslate, toSkip, target
   return output;
 }
 
+function findResidualUntranslatedLeaves(sourceLeaves, outputData, args, options = {}) {
+  const ignoredKeys = options.ignoredKeys || new Set();
+  const residual = [];
+
+  for (const leaf of sourceLeaves) {
+    if (ignoredKeys.has(leaf.keyPath)) continue;
+
+    const targetValue = getLeaf(outputData, leaf.keyPath);
+    const reason = getResidualUntranslatedReason(leaf.value, targetValue, args);
+    if (reason) {
+      residual.push({
+        keyPath: leaf.keyPath,
+        value: String(targetValue ?? ''),
+        sourceValue: leaf.value,
+        reason,
+        fileName: options.fileName,
+      });
+    }
+  }
+
+  return residual;
+}
+
+function buildResidualRetryItems(residualLeaves, customRegex) {
+  return residualLeaves.map((leaf) => {
+    const placeholders = detectPlaceholders(leaf.sourceValue, customRegex);
+    return {
+      keyPath: leaf.keyPath,
+      value: leaf.sourceValue,
+      placeholders,
+      placeholderMode: placeholders.length > 0 ? 'preserve' : 'none',
+    };
+  });
+}
+
 function formatProgressKey(keyPath) {
   if (!keyPath) return '';
   const value = String(keyPath);
@@ -735,6 +811,7 @@ 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);
+  const runArgs = { ...args, targetLang };
 
   let sourceData;
   try {
@@ -753,18 +830,18 @@ async function processFile(sourcePath, targetLang, args) {
   }
 
   const targetData = readExistingTargetData(targetPath);
-  const { translatableLeaves: candidateLeaves, existingLeaves } = planTargetAwareLeaves(leaves, targetData, args);
+  const { translatableLeaves: candidateLeaves, existingLeaves } = planTargetAwareLeaves(leaves, targetData, runArgs);
 
-  const protection = args.protection || loadProtectionConfig(args.protectionFile, {
-    enabled: args.protectionEnabled,
-    create: args.createProtectionFile,
+  const protection = runArgs.protection || loadProtectionConfig(runArgs.protectionFile, {
+    enabled: runArgs.protectionEnabled,
+    create: runArgs.createProtectionFile,
   });
   const protectedLeaves = candidateLeaves
     .filter((leaf) => shouldPreserveWholeValue(leaf.keyPath, leaf.value, protection))
     .map((leaf) => ({ ...leaf, skipReason: 'protected' }));
   const translatableLeaves = candidateLeaves.filter((leaf) => !shouldPreserveWholeValue(leaf.keyPath, leaf.value, protection));
-  const { withPlaceholders, withoutPlaceholders } = classifyLeaves(translatableLeaves, args.customRegex);
-  const { strategy, interactiveMode } = await resolvePlaceholderStrategy(args);
+  const { withPlaceholders, withoutPlaceholders } = classifyLeaves(translatableLeaves, runArgs.customRegex);
+  const { strategy, interactiveMode } = await resolvePlaceholderStrategy(runArgs);
 
   if (args.dryRun && strategy === 'skip' && withPlaceholders.length > 0) {
     await previewSkipped(withPlaceholders);
@@ -834,16 +911,16 @@ async function processFile(sourcePath, targetLang, args) {
   const manifestPath = createPlaceholderManifest(sourcePath, targetLang, toTranslate);
 
   const translateOptions = {
-    sourceLang: args.sourceLang,
-    provider: args.provider,
-    concurrency: args.concurrency,
-    batchSize: args.batchSize,
-    retryCount: args.retryCount,
-    retryDelay: args.retryDelay,
-    timeout: args.timeout,
-    customFn: args.translateFn,
+    sourceLang: runArgs.sourceLang,
+    provider: runArgs.provider,
+    concurrency: runArgs.concurrency,
+    batchSize: runArgs.batchSize,
+    retryCount: runArgs.retryCount,
+    retryDelay: runArgs.retryDelay,
+    timeout: runArgs.timeout,
+    customFn: runArgs.translateFn,
     onProgress: (info) => {
-      if (info.completed % args.progressInterval === 0 || info.completed === info.total) {
+      if (info.completed % runArgs.progressInterval === 0 || info.completed === info.total) {
         const stage = info.stage || 'Translating';
         const unit = info.unit || 'items';
         const keyPath = formatProgressKey(info.keyPath);
@@ -860,7 +937,7 @@ async function processFile(sourcePath, targetLang, args) {
   try {
     if (toTranslate.length > 0) {
       console.log(`[${fileName}] Preparing translation plan for ${toTranslate.length} keys.`);
-      translatedResults = await translateItems(toTranslate, targetLang, translateOptions, args.customRegex, protection);
+      translatedResults = await translateItems(toTranslate, targetLang, translateOptions, runArgs.customRegex, protection);
       process.stdout.write('\n');
       console.log(`[${fileName}] Applying translated values.`);
     } else {
@@ -871,8 +948,33 @@ async function processFile(sourcePath, targetLang, args) {
   }
 
   const output = applyResults(sourceData, translatedResults, toTranslate, toSkip, targetData);
+  const ignoredResidualKeys = new Set(protectedLeaves.map((leaf) => leaf.keyPath));
+  let residualUntranslated = findResidualUntranslatedLeaves(leaves, output, runArgs, {
+    ignoredKeys: ignoredResidualKeys,
+    fileName,
+  });
+  let finalCheckRetried = 0;
+
+  if (residualUntranslated.length > 0) {
+    console.warn(`[${fileName}] Warning: Final check found ${residualUntranslated.length} values that still look untranslated. Retrying once before writing.`);
+    const retryItems = buildResidualRetryItems(residualUntranslated, runArgs.customRegex);
+    const retryResults = await translateItems(retryItems, targetLang, translateOptions, runArgs.customRegex, protection);
+    retryItems.forEach((item, index) => {
+      setLeaf(output, item.keyPath, retryResults[index]);
+    });
+    finalCheckRetried = retryItems.length;
+    residualUntranslated = findResidualUntranslatedLeaves(leaves, output, runArgs, {
+      ignoredKeys: ignoredResidualKeys,
+      fileName,
+    });
+  }
+
+  if (residualUntranslated.length > 0) {
+    console.warn(`[${fileName}] Warning: ${residualUntranslated.length} values still look untranslated after retry. Rerun Auto Translate to capture leftovers.`);
+  }
+
   console.log(`[${fileName}] Writing output.`);
-  writeOutput(output, targetPath, args.bom);
+  writeOutput(output, targetPath, runArgs.bom);
 
   console.log(`[${fileName}] Written: ${targetPath}`);
 
@@ -884,6 +986,8 @@ async function processFile(sourcePath, targetLang, args) {
     placeholderProtected,
     protectedSkipped: protectedLeaves.length,
     skippedExisting: existingLeaves.length,
+    finalCheckRetried,
+    residualUntranslated,
   };
 }
 
@@ -932,6 +1036,8 @@ async function run(args) {
   let grandPlaceholderProtected = 0;
   let grandProtectedSkipped = 0;
   let grandSkippedExisting = 0;
+  let grandFinalCheckRetried = 0;
+  const allResidualUntranslated = [];
 
   for (const srcPath of sourceFiles) {
     const result = await processFile(srcPath, args.targetLang, args);
@@ -942,25 +1048,38 @@ async function run(args) {
       grandPlaceholderProtected += result.placeholderProtected || 0;
       grandProtectedSkipped += result.protectedSkipped || 0;
       grandSkippedExisting += result.skippedExisting || 0;
+      grandFinalCheckRetried += result.finalCheckRetried || 0;
       if (result.skippedKeys && result.skippedKeys.length > 0) {
         allSkippedKeys.push(...result.skippedKeys);
       }
+      if (result.residualUntranslated && result.residualUntranslated.length > 0) {
+        allResidualUntranslated.push(...result.residualUntranslated);
+      }
     }
   }
 
   console.log('');
   console.log(formatSummaryLine(grandSkipped, grandTranslated, grandTotal, grandPlaceholderProtected, grandProtectedSkipped, grandSkippedExisting));
+  if (grandFinalCheckRetried > 0) {
+    console.log(`[translate] final check retried ${grandFinalCheckRetried} leftover values`);
+  }
+
+  if (allResidualUntranslated.length > 0) {
+    console.warn(`WARNING: ${allResidualUntranslated.length} values still look untranslated after Auto Translate.`);
+    console.warn('Rerun Auto Translate to capture leftovers, or review the values listed in the report.');
+  }
 
-  if (allSkippedKeys.length > 0 || args.reportFile || args.reportStdout) {
+  if (allSkippedKeys.length > 0 || allResidualUntranslated.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,
       placeholderProtected: grandPlaceholderProtected,
       protectedSkipped: grandProtectedSkipped,
+      residualUntranslated: allResidualUntranslated,
     });
 
-    if (args.reportStdout || (!args.reportFile && allSkippedKeys.length > 0)) {
+    if (args.reportStdout || (!args.reportFile && (allSkippedKeys.length > 0 || allResidualUntranslated.length > 0))) {
       console.log('');
       console.log(report);
     }
@@ -973,14 +1092,17 @@ async function run(args) {
   }
 
   return {
-    success: true,
-    exitCode: ExitCodes.SUCCESS,
+    success: allResidualUntranslated.length === 0,
+    exitCode: allResidualUntranslated.length === 0 ? ExitCodes.SUCCESS : ExitCodes.VALIDATION_FAILED,
+    error: allResidualUntranslated.length === 0 ? undefined : 'Auto Translate left untranslated placeholder values',
     total: grandTotal,
     translated: grandTranslated,
     skipped: grandSkipped,
     placeholderProtected: grandPlaceholderProtected,
     protectedSkipped: grandProtectedSkipped,
     skippedExisting: grandSkippedExisting,
+    finalCheckRetried: grandFinalCheckRetried,
+    residualUntranslated: allResidualUntranslated.length,
   };
 }
 

package/main/manage/commands/SizingCommand.js

@@ -30,8 +30,11 @@ class SizingCommand {
         try {
             const I18nSizingAnalyzer = require('../../i18ntk-sizing');
             const sizingAnalyzer = new I18nSizingAnalyzer();
-            await sizingAnalyzer.run(options);
-            return { success: true, command: 'sizing' };
+            const result = await sizingAnalyzer.run(options);
+            if (result && result.success === false) {
+                throw new Error(result.error || 'Sizing analysis failed');
+            }
+            return { success: true, command: 'sizing', result };
         } catch (error) {
             console.error(`Sizing command failed: ${error.message}`);
             throw error;

package/main/manage/commands/TranslateCommand.js

@@ -254,6 +254,14 @@ class TranslateCommand {
         for (const r of results) {
             console.log(`    ${r.ok ? '\u{2705}' : '\u{274C}'} ${r.lang}${r.error ? ' (' + r.error + ')' : ''}`);
         }
+        const failed = results.filter(r => !r.ok);
+        if (failed.length > 0) {
+            const message = failed.length === 1
+                ? `Translation finished with warnings for ${failed[0].lang}. Rerun Auto Translate to capture leftovers.`
+                : `Translation finished with warnings for ${failed.length} languages. Rerun Auto Translate to capture leftovers.`;
+            console.log('\n  ' + this.tr('translate.summary.incomplete', { count: failed.length }, message));
+            return { success: false, results, error: message };
+        }
         console.log('\n  ' + this.tr('translate.summary.complete', {}, 'Translation complete!'));
         return { success: true, results };
     }

package/main/manage/commands/ValidateCommand.js

@@ -669,6 +669,30 @@ class ValidateCommand {
                 );
             });
 
+            if (this.errors.length > 0) {
+                lines.push('');
+                lines.push('Errors');
+                lines.push('------');
+                this.errors.forEach((error, index) => {
+                    lines.push(`${index + 1}. ${error.message}`);
+                    if (error.details && Object.keys(error.details).length > 0) {
+                        lines.push(`   Details: ${JSON.stringify(error.details, null, 2).replace(/\n/g, '\n   ')}`);
+                    }
+                });
+            }
+
+            if (this.warnings.length > 0) {
+                lines.push('');
+                lines.push('Warnings');
+                lines.push('--------');
+                this.warnings.forEach((warning, index) => {
+                    lines.push(`${index + 1}. ${warning.message}`);
+                    if (warning.details && Object.keys(warning.details).length > 0) {
+                        lines.push(`   Details: ${JSON.stringify(warning.details, null, 2).replace(/\n/g, '\n   ')}`);
+                    }
+                });
+            }
+
             SecurityUtils.safeWriteFileSync(reportPath, lines.join('\n') + '\n', process.cwd(), 'utf8');
             return reportPath;
         } catch (error) {

package/main/manage/services/UsageService.js

@@ -1476,12 +1476,12 @@ class UsageService {
         this.sourceLanguageDir = path.join(this.i18nDir, this.config.sourceLanguage);
       }
 
-      if (this.sourceDir || this.i18nDir) {
-        await configManager.updateConfig({
-          sourceDir: configManager.toRelative(this.sourceDir || this.config.sourceDir),
-          i18nDir: configManager.toRelative(this.i18nDir || this.config.i18nDir)
-        });
-      }
+      if (args.sourceDir || args.i18nDir) {
+        await configManager.updateConfig({
+          sourceDir: configManager.toRelative(this.sourceDir || this.config.sourceDir),
+          i18nDir: configManager.toRelative(this.i18nDir || this.config.i18nDir)
+        });
+      }
 
       const usageSource = resolveUsageSourceDir({
         sourceDir: this.sourceDir || this.config.sourceDir,
@@ -1494,11 +1494,6 @@ class UsageService {
       }
       this.sourceDir = usageSource.sourceDir;
       this.config.sourceDir = usageSource.sourceDir;
-      if (this.sourceDir) {
-        await configManager.updateConfig({
-          sourceDir: configManager.toRelative(this.sourceDir)
-        });
-      }
 
       // 🚧 prevent scanning locales as source
       if (this.sourceDir && !args.sourceDir && path.resolve(this.sourceDir) === path.resolve(this.i18nDir)) {
@@ -1511,11 +1506,8 @@ class UsageService {
           console.warn(`⚠️ Fallback directory ${fallback} does not exist. Using project root for source scanning.`);
           this.sourceDir = path.resolve(this.config.projectRoot || '.');
         }
-        this.config.sourceDir = this.sourceDir;
-        await configManager.updateConfig({
-          sourceDir: configManager.toRelative(this.sourceDir)
-        });
-      }
+        this.config.sourceDir = this.sourceDir;
+      }
 
       console.log(t('usage.detectedSourceDirectory', { sourceDir: this.sourceDir || t('usage.noSourceDirectoryConfigured') || '(none)' }));
       console.log(t('usage.detectedI18nDirectory', { i18nDir: this.i18nDir }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18ntk",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "i18n Tool Kit - Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, auto translation, fixing, reporting, and runtime translation loading.",
   "readmeFilename": "README.md",
   "keywords": [
@@ -168,27 +168,25 @@
   },
   "preferGlobal": true,
   "versionInfo": {
-    "version": "4.2.0",
-    "releaseDate": "30/05/2026",
-    "lastUpdated": "30/05/2026",
+    "version": "4.2.1",
+    "releaseDate": "31/05/2026",
+    "lastUpdated": "31/05/2026",
     "maintainer": "Vlad Noskov",
     "changelog": "./CHANGELOG.md",
     "documentation": "./README.md",
     "apiReference": "./docs/api/API_REFERENCE.md",
     "majorChanges": [
-      "SECURITY: Path containment, backup restore, runtime language loading, and Auto Translate provider URL validation are hardened.",
-      "AUTO TRANSLATE: The manager and docs no longer mark Auto Translate beta; existing translated target values are kept by default, and Google concurrency can now be raised up to 100.",
-      "RUNTIME: The lightweight runtime gains per-call language overrides, translateBatch(), cache helpers, and safer JSON parsing.",
-      "REPORTS: Init and analysis reports default to readable Markdown, with pretty JSON and text available through reports.format.",
-      "UX: Manager menu spacing is grouped and validation output no longer repeats source/i18n/output directory blocks.",
-      "USAGE: Usage analysis avoids scanning the project root when locale and source directories are the same.",
-      "USAGE: Usage reports now index known keys to source locations, resolve bounded dynamic key patterns, report unresolved dynamic expressions, recommend route-based namespaces, and flag hardcoded text candidates."
+      "AUTO TRANSLATE: Uppercase target-language placeholders such as [AR] What We Offer are detected, translated from source, and checked again before completion.",
+      "AUTO TRANSLATE: Runs now warn, report, and exit with validation failure if placeholder-prefixed or source-copy leftovers remain after the final retry.",
+      "SIZING: Manager sizing uses the configured i18n directory unless --source-dir is explicitly provided, so usage analysis no longer poisons the next sizing run.",
+      "VALIDATION: Validation summary reports now include warning and error details, not only totals.",
+      "USAGE: Usage fallback source detection no longer writes its inferred app source directory back into the shared locale configuration."
     ],
     "breakingChanges": [
       "i18ntk/runtime module-level helpers keep the first initialized runtime configuration for compatibility instead of being overwritten by later initRuntime() calls.",
       "utils/watch-locales.js returns a callable watcher object with EventEmitter methods and stop(); existing bare stop-function usage remains supported."
     ],
-    "nextVersion": "4.2.1",
+    "nextVersion": "4.2.2",
     "supportedNodeVersions": ">=16.0.0",
     "supportedFrameworks": {
       "react-i18next": ">=11.0.0",
@@ -210,7 +208,7 @@
       "spring-boot": ">=2.5.0",
       "laravel": ">=8.0.0"
     },
-    "supportPolicy": "Versions earlier than 4.2.0 may be unstable or insecure. Upgrade to 4.2.0 or newer."
+    "supportPolicy": "Versions earlier than 4.2.1 may be unstable or insecure. Upgrade to 4.2.1 or newer."
   },
-  "readme": "# i18ntk v4.2.0\n\nA i18n toolkit - A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.\n\n![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)\n\n[![npm version](https://img.shields.io/npm/v/i18ntk.svg?color=brightgreen)](https://www.npmjs.com/package/i18ntk)\n[![npm downloads](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)\n[![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)\n[![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)\n[![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.2.0)](https://socket.dev/npm/package/i18ntk/overview/4.2.0)\n\n## Install\n\n```bash\n# global CLI use\nnpm install -g i18ntk\n\n# local project use\nnpm install --save-dev i18ntk\n\n# one-off execution\nnpx i18ntk --help\n```\n\nRequirements:\n\n- Node.js `>=16.0.0`\n- npm `>=8.0.0`\n- No runtime dependencies\n\n## What's New in 4.2.0\n\n- **SECURITY**: Hardened path containment for restore and shared filesystem helpers, including artifact-like filenames, environment-added internal prefixes, and Windows cross-drive paths.\n- **SECURITY**: Runtime locale loading now rejects unsafe language identifiers before resolving locale files, preventing `../` language names from reading JSON outside the configured locale base.\n- **SECURITY**: Auto Translate provider URL checks now block IPv4-mapped IPv6 private/loopback hosts.\n- **REPORTS**: Init and analysis reports now default to readable Markdown. Set `reports.format` to `markdown`, `json`, or `text` in Settings or `.i18ntk-config`.\n- **USAGE**: Usage analysis no longer scans the project root when locales are also configured as the source directory, avoiding inflated missing-key counts.\n- **I18N UX**: Init backup prompts, completion summaries, report prompts, default target languages, and native yes/no confirmations are now localized.\n- **AUTO TRANSLATE**: Auto Translate is out of beta, keeps existing translated target values by default, and only sends missing/source-copy/likely-English strings unless `--translate-all` is used.\n- **AUTO TRANSLATE**: Google Auto Translate concurrency now defaults to 12 and can be raised up to 100 for larger locale sets.\n- **AUTO TRANSLATE**: Corrupt target strings such as `?????`, replacement characters, and common mojibake are now repaired from the English source, and progress output distinguishes key translation from placeholder-safe text-segment translation.\n- **CLI UX**: Manager menu spacing is grouped and aligned, and validation no longer prints duplicate source/i18n/output directory blocks.\n- **DOCS**: Versioned docs and migration guidance now reflect the current 4.2.0 command surface.\n- **CLEANUP**: Removed stale duplicate fixed artifacts from the development tree to reduce audit and supply-chain drift.\n\n## What's New in 4.1.0\n\n- **FIX**: Critical and high-impact bugs resolved across the v4.0.0 feature set — runtime staleness crashes, backup hash-chain verification, sizing adminAuth crash, scanner `--source-language` propagation, watch callback subscriptions, dead key detection performance, validator key style enforcement, and protection Unicode boundary handling. See [CHANGELOG.md](./CHANGELOG.md) for complete details.\n\n## What's New in 4.0.0\n\n- **SIZING**: `--predict-expansion` flag computes per-key expansion ratios across languages with Safe/Warning/Critical risk tiers for UI layout planning.\n- **WATCH**: `watchLocales()` now returns an EventEmitter-compatible watcher with debounced `change`/`add`/`unlink`/`error` events and SHA-256 hash tracking.\n- **USAGE**: `--cleanup` and `--dry-run-delete` flags identify dead translation keys with confidence scores.\n- **VALIDATOR**: `--enforce-key-style` enforces dot.notation, snake_case, camelCase, kebab-case, or flat naming conventions.\n- **SCANNER**: `--source-language` supports multi-language hardcoded text detection with 12+ language profiles.\n- **BACKUP**: `--incremental` flag creates differential backups with SHA-256 hashing and chained restores.\n- **RUNTIME**: `lazy: true` option defers locale file loading until first key access for lower memory usage.\n- **PROTECTION**: Context-aware rules (`after:word`, `before:word`, `standalone`, `surrounded:left,right`) for precise term masking.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for more release details.\n\n## Quick Start\n\nInitialize a project:\n\n```bash\ni18ntk\n# or with explicit command\ni18ntk --command=init\n```\n\nRun common checks:\n\n```bash\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk --command=sizing\ni18ntk --command=summary\n```\n\nComplete or fix translation files:\n\n```bash\ni18ntk --command=complete\ni18ntk-fixer --help\n```\n\nAuto-translate locale JSON:\n\n```bash\ni18ntk --command=translate\n# or\ni18ntk-translate locales/en/common.json de --report-stdout\n```\n\nThe full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).\n\n## Main Commands\n\nPrimary CLI:\n\n```bash\ni18ntk\ni18ntk --help\ni18ntk --command=init\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk --command=scanner\ni18ntk --command=sizing\ni18ntk --command=complete\ni18ntk --command=translate\ni18ntk --command=summary\n```\n\nStandalone executables:\n\n```bash\ni18ntk-init\ni18ntk-analyze\ni18ntk-validate\ni18ntk-usage\ni18ntk-scanner\ni18ntk-sizing\ni18ntk-complete\ni18ntk-summary\ni18ntk-doctor\ni18ntk-fixer\ni18ntk-backup\ni18ntk-translate\n```\n\nNote: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` directly for backup operations.\n\n## Command Reference\n\n| Command | What it does | Looks for | Writes or changes |\n| --- | --- | --- | --- |\n| `i18ntk` | Opens the interactive management menu. | Project config, setup state, available commands. | Only changes files after you choose a command that writes. |\n| `i18ntk --command=init` / `i18ntk-init` | Sets up locale folders and missing target-language files. | Source language files and selected target languages. | Locale JSON files, `.i18ntk-config`, optional reports/backups. |\n| `i18ntk --command=analyze` / `i18ntk-analyze` | Compares source and target translation coverage. | Missing keys, extra keys, untranslated markers, completion by language. | Markdown/JSON/text reports when report output is enabled. |\n| `i18ntk --command=validate` / `i18ntk-validate` | Validates structure and translation quality risks. | Placeholder mismatches, missing keys, risky URLs/emails/secrets, likely English target text. | Validation summary report. Does not edit locale files. |\n| `i18ntk --command=usage` / `i18ntk-usage` | Maps translation keys to source files and finds unused/missing keys. | Direct i18n calls, literal known-key references, bounded dynamic templates/object maps, unresolved dynamic expressions, hardcoded text candidates, namespace/file naming mismatches. | Usage report with key locations, namespace recommendations, unresolved dynamic expressions, hardcoded text suggestions, and optional dead-key report. Does not delete unless cleanup deletion is explicitly enabled. |\n| `i18ntk --command=scanner` / `i18ntk-scanner` | Scans source for i18n issues and hardcoded user-facing text. | JSX/template text, common text attributes, i18n usage patterns, source-language text profiles. | Scanner report. Does not edit files. |\n| `i18ntk --command=complete` / `i18ntk-complete` | Adds missing keys to target language files for 100% key coverage. | Source-language keys missing from targets. | Target locale JSON files, using missing translation markers/prefixes. |\n| `i18ntk --command=translate` / `i18ntk-translate` | Auto-translates locale JSON using configured provider behavior. | Missing, empty, untranslated-marker, source-copy, likely-English, or visibly corrupt target values by default. | Target locale JSON files and translation reports. Existing translated values are kept unless `--translate-all` is used. |\n| `i18ntk --command=sizing` / `i18ntk-sizing` | Estimates translated string length expansion and layout risk. | Text length, expansion ratios, placeholder-bearing strings. | Sizing report. Does not edit locale files. |\n| `i18ntk --command=summary` / `i18ntk-summary` | Shows project translation status. | Configured locales, reports, completeness status. | Console/report output only. |\n| `i18ntk-fixer` | Fixes placeholder and missing-marker issues. | Placeholder corruption, missing translation markers, configured language files. | Locale JSON files when fixes are applied. Use dry-run options where available before bulk edits. |\n| `i18ntk-backup` | Creates, verifies, restores, and cleans locale backups. | Locale JSON files and backup manifests. | Backup archives/manifests, or restored locale files when using restore. |\n\n## Common Options\n\nMany commands support:\n\n- `--source-dir <path>`\n- `--i18n-dir <path>`\n- `--output-dir <path>`\n- `--source-language <code>`\n- `--ui-language <code>`\n- `--no-prompt`\n- `--help`\n\nCommand-specific tools add their own flags such as `--dry-run`, `--output-report`, `--cleanup`, `--predict-expansion`, or Auto Translate provider options.\n\nExample:\n\n```bash\ni18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports\n```\n\n## Auto Translate\n\nInteractive manager flow:\n\n```bash\ni18ntk\n# choose \"Auto Translate\"\n```\n\nDirect CLI examples:\n\n```bash\ni18ntk-translate locales/en/common.json de\ni18ntk-translate locales/en/common.json fr --dry-run --report-stdout\ni18ntk-translate locales/en es --source-dir locales/en --files \"*.json\" --no-confirm --preserve-placeholders\n```\n\nProvider examples:\n\n```bash\nexport DEEPL_API_KEY=\"your-deepl-api-key\"\ni18ntk-translate locales/en/common.json de --provider deepl --no-confirm --preserve-placeholders\n\nexport LIBRETRANSLATE_URL=\"https://libretranslate.com/translate\"\nexport LIBRETRANSLATE_API_KEY=\"optional-api-key\"\ni18ntk-translate locales/en/common.json es --provider libretranslate --no-confirm --preserve-placeholders\n```\n\n`google` remains the default provider. You can also set `I18NTK_TRANSLATE_PROVIDER=deepl` or `I18NTK_TRANSLATE_PROVIDER=libretranslate`.\n\nProvider requests are HTTPS-only and response-size limited, and security logs redact provider query strings and response bodies. DeepL is pinned to official DeepL hosts by default; set `I18NTK_ALLOW_CUSTOM_TRANSLATE_HOSTS=1` only for a trusted DeepL-compatible proxy. Custom LibreTranslate URLs are blocked for localhost/private IP ranges unless `I18NTK_ALLOW_PRIVATE_TRANSLATE_URLS=1` is set for trusted local testing. Keep provider API keys in environment variables or a secret manager.\n\nThe manager flow asks for:\n\n- source locale directory, either the folder with JSON files or a locale root such as `./locales`\n- source language code\n- one or more target languages, or `all`\n- one JSON file or all JSON files in the source directory\n\nIf you select a locale root such as `./locales` and choose source language `en`, the manager automatically uses `./locales/en` when that folder contains the source JSON files.\n\nBefore writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:\n\n```text\nlocales/en/common.json\nlocales/de/common.json\nlocales/fr/common.json\n```\n\nAuto Translate is target-aware by default. When a target file already exists, it keeps translated target values and only sends values that are missing, empty, marked as untranslated, still identical to the source, likely still English, or visibly corrupt from encoding damage such as `?????`, replacement characters, or common mojibake. Use `--translate-all` when you intentionally want to re-translate every source string.\n\n### Placeholder Handling\n\nAuto Translate detects common placeholders such as:\n\n- `{name}`\n- `{{count}}`\n- `%s`\n- `%d`\n- `:id`\n- `%{name}`\n- `${value}`\n- `{count, plural, one {# item} other {# items}}`\n- `$t(common.save)`\n- `%(total).2f`\n\nUseful flags:\n\n- `--preserve-placeholders`: translate text around placeholders and reinsert original tokens\n- `--skip-placeholders`: copy placeholder-bearing strings unchanged\n- `--send-placeholders`: send placeholder-bearing strings through translation after masking\n- `--custom-regex <regex>`: add project-specific placeholder detection\n- `--only-missing`: keep existing translated target values and translate only missing/source-copy/likely English values (default)\n- `--translate-all`: re-translate every source string\n\nProgress output is stage-aware for large files. Normal keys are reported as `Translating strings`, while preserve-mode placeholder work is reported as `Translating placeholder-safe text segments`; each progress update includes the current key path when available.\n\n### Protected Terms and Keys\n\nAuto Translate can create and use a project-local protection file:\n\n```bash\ni18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json\n```\n\nExample `i18ntk-auto-translate.json`:\n\n```json\n{\n  \"version\": 1,\n  \"terms\": [\n    \"BrandName\",\n    \"PRODUCT_CODE\",\n    { \"value\": \"OK\", \"context\": \"after:Click|Press|Tap\" },\n    { \"value\": \"API\", \"context\": \"standalone\" }\n  ],\n  \"keys\": [\"app.brandName\", \"legal.companyName\", \"product.*.symbol\"],\n  \"values\": [\"BrandName Ltd\", \"support@example.com\"],\n  \"patterns\": [\"[A-Z]{2,}-\\\\d+\"]\n}\n```\n\n- `terms` are masked before translation and restored exactly afterward.\n  - **Plain strings**: masked everywhere (backward compatible).\n  - **Context objects**: masked only in specific contexts (`after:word`, `before:word`, `standalone`, `surrounded:left,right`).\n- `keys` are exact key paths or `*` wildcard paths copied unchanged.\n- `values` are exact source values copied unchanged.\n- `patterns` are JavaScript regex strings for advanced protected substrings.\n\nUseful flags:\n\n- `--protection-file <path>`\n- `--create-protection-file`\n- `--no-protection`\n\nOpen Settings and choose `Auto Translate` to edit defaults for placeholder mode, translate-only-needed mode, concurrency, batch size, retry settings, report output, BOM output, protection file path, first-run setup prompt, and update prompt.\n\nSee [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.\n\n## Validation\n\nValidation checks locale structure, completeness, placeholders, and content risks.\n\nValidation warning types are specific:\n\n- `Potential risky content`: URL, email address, or secret-like value\n- `Possible untranslated English content`: target-language value appears to contain too much English\n\nEnglish-content warnings include:\n\n- detected English percentage\n- configured threshold\n- matched word count\n- sample matched words\n\nTune warnings in `.i18ntk-config`:\n\n```json\n{\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"]\n}\n```\n\n## Sizing Analysis\n\n`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.\n\n```bash\ni18ntk-sizing --source-dir ./locales --format table\ni18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports\n```\n\nUse `--detailed` to print per-file rows in the terminal.\n\n### Expansion Prediction (New in 4.0.0)\n\nPredict UI layout overflow risk by analyzing per-key character-count expansion across languages:\n\n```bash\ni18ntk-sizing --source-dir ./locales --predict-expansion --output-report\n```\n\nExpansion ratios are classified into risk tiers:\n\n- **Safe** (<30% expansion): no UI impact expected\n- **Warning** (30–50%): may overflow in tight layouts — test on target languages\n- **Critical** (>50%): high risk of truncation — review UI element sizing\n\nThe report includes a built-in language-pair expansion reference table (EN→DE +35%, EN→RU +50%, EN→JA −40%, etc.) and lists the top-30 most-expanded keys.\n\n## Scanner: Multi-Language Detection (New in 4.0.0)\n\n`i18ntk-scanner` now supports detecting hardcoded text in multiple source languages beyond English:\n\n```bash\ni18ntk-scanner --source-dir ./src --source-language de\ni18ntk-scanner --source-dir ./src --source-language ja --output-report\n```\n\nSupported language profiles (12+): English, German, French, Spanish, Japanese, Chinese, Russian, Korean, Arabic, Hindi, and more. Each profile includes language-specific character ranges, stopword lists for false-positive filtering, and transliteration rules for key generation.\n\n## Usage: Dead Key Detection (New in 4.0.0)\n\n`i18ntk-usage` can identify translation keys that are defined but never referenced in source code:\n\n```bash\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup --dry-run-delete\n```\n\nEach dead key receives a confidence score (0.0–1.0) factoring:\n- Unresolved dynamic key patterns (e.g., `` t(`prefix.${dynamic}`) ``) — lower score and listed in the usage report; simple consts, bounded arrays, object maps, and ternaries are expanded to exact keys where possible\n- Key appears in source code comments or JSDoc — medium score\n- Parent file recently modified (<30 days) — medium score\n- No references found anywhere — high score (>0.8)\n\nThe `--dry-run-delete` flag writes a `.dead-keys.json` report for review before any destructive action.\n\n## Validator: Key Naming Conventions (New in 4.0.0)\n\nEnforce consistent translation key naming across your project:\n\n```bash\ni18ntk-validate --enforce-key-style\n```\n\nConfigure the expected style in `.i18ntk-config`:\n\n```json\n{\n  \"keyStyle\": \"dot.notation\"\n}\n```\n\nSupported styles: `dot.notation`, `snake_case`, `camelCase`, `kebab-case`, `flat`. Violations are reported as warnings with suggested canonical forms.\n\n## Watch: Hot Reload (New in 4.0.0)\n\n`utils/watch-locales.js` now provides debounced file watching with EventEmitter support:\n\n```js\nconst watchLocales = require('i18ntk/utils/watch-locales');\nconst watcher = watchLocales('./locales');\n\nwatcher.on('change', (filePath) => {\n  console.log('Locale changed:', filePath);\n});\n\nwatcher.on('add', (filePath) => {\n  console.log('Locale added:', filePath);\n});\n\n// Later:\nwatcher.stop();\n```\n\nFeatures: 300ms debounce (configurable), SHA-256 hash tracking to skip no-change saves, and a maximum of 50 watched directories.\n\n### Migration\n\nThe `watchLocales` return value gained EventEmitter methods in v4.0.0. Existing stop-function usage still works:\n\n```js\nconst stop = watchLocales('./locales', onChange);\n```\n\nCan be updated to:\n\n```js\nconst watcher = watchLocales('./locales');\nwatcher.on('change', onChange);\nwatcher.stop();\n```\n\nPassing a callback as the second argument is still supported — it auto-subscribes to `change` and `add` events.\n\n## Backup: Incremental Mode (New in 4.0.0)\n\nCreate differential backups that only include changed files:\n\n```bash\ni18ntk-backup create ./locales --incremental\n```\n\nIncremental backups store SHA-256 hashes per file and a parent-chain reference. Restoring an incremental backup automatically chains from the oldest full backup through each incremental diff in order. Chain depth is capped at 10 increments. Use `verify` to validate the hash chain.\n\n## Runtime: Lazy Loading (New in 4.0.0)\n\nReduce memory usage by deferring locale file loads until first key access:\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  lazy: true\n});\n\nconsole.log(i18n.t('common.hello')); // loads common.json on first access\n```\n\nWhen `lazy: true`, the runtime builds a key-to-file manifest on first access and loads individual files on demand. Files are loaded once and cached. If the manifest is missing or incomplete, the runtime falls back to full eager loading for that language. Manifest size is capped at 100KB with path containment validation.\n\nProduction guidance:\n\n- Prefer the object returned from `initRuntime()` instead of module-level `runtime.t()` in apps with multiple tenants, projects, or locale roots.\n- Use `lazy: true` for large modular locale folders where lower steady-state memory matters more than a small first-key lookup cost.\n- Use `preload: true` without `lazy` for small locale sets or latency-sensitive startup paths.\n- Call `refresh(language)` after deploying or writing changed locale files so cached data and lazy manifests are rebuilt.\n- Use per-call language overrides when rendering one-off alternate-language strings: `i18n.t('common.hello', {}, { language: 'de' })`.\n- Use `translateBatch()` for small groups of labels and `clearCache()` / `getCacheInfo()` for cache maintenance and diagnostics.\n- `i18ntk/runtime/enhanced` remains available for compatibility with existing async/encryption users, but new production integrations should start with `i18ntk/runtime`.\n\n## Runtime API\n\nUse `i18ntk/runtime` when an application needs to read locale JSON files at runtime.\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  fallbackLanguage: 'en',\n  keySeparator: '.',\n  preload: true\n});\n\nconsole.log(i18n.t('common.hello'));\ni18n.setLanguage('fr');\nconsole.log(i18n.getLanguage());\nconsole.log(i18n.getAvailableLanguages());\ni18n.refresh('fr');\n```\n\nUseful production helpers:\n\n```js\ni18n.t('common.hello', {}, { language: 'de' }); // per-call language override\ni18n.translateBatch(['menu.home', 'menu.settings']);\ni18n.clearCache('fr');\nconsole.log(i18n.getCacheInfo());\n```\n\nSee [docs/runtime.md](./docs/runtime.md) for runtime details.\n\n## Configuration\n\ni18ntk uses a project-local `.i18ntk-config` file.\n\nExample:\n\n```json\n{\n  \"version\": \"4.2.0\",\n  \"sourceDir\": \"./locales\",\n  \"i18nDir\": \"./locales\",\n  \"outputDir\": \"./i18ntk-reports\",\n  \"sourceLanguage\": \"en\",\n  \"defaultLanguages\": [\"en\", \"de\", \"es\", \"fr\", \"ru\"],\n  \"reports\": {\n    \"format\": \"markdown\"\n  },\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"],\n  \"autoTranslate\": {\n    \"placeholderMode\": \"preserve\",\n    \"concurrency\": 12,\n    \"batchSize\": 100,\n    \"progressInterval\": 25,\n    \"retryCount\": 3,\n    \"retryDelay\": 1000,\n    \"timeout\": 15000,\n    \"dryRunFirst\": true,\n    \"onlyMissingOrEnglish\": true,\n    \"reportStdout\": true,\n    \"bom\": false,\n    \"protectionEnabled\": true,\n    \"protectionFile\": \"./i18ntk-auto-translate.json\",\n    \"promptProtectionSetup\": true,\n    \"promptProtectionUpdate\": true\n  },\n  \"setup\": {\n    \"completed\": true\n  }\n}\n```\n\nSee [docs/api/CONFIGURATION.md](./docs/api/CONFIGURATION.md) for the full configuration model.\n\n## Public Package Contents\n\nThe public package intentionally ships runtime and CLI files only. The publish staging script excludes development-only content such as tests, scripts, docs, release staging folders, local config files, and generated protection files.\n\nThe package includes:\n\n- CLI entry points under `main/`\n- manager commands and services\n- runtime API files under `runtime/`\n- settings UI files required at runtime\n- bundled internal UI locales\n- shared utilities required by the shipped commands\n- `README.md`, `CHANGELOG.md`, `LICENSE`, and policy files\n\nThe public package manifest includes `readmeFilename: \"README.md\"`, and the release staging script fails if `README.md` is missing or empty.\n\n## Documentation\n\n- [Documentation Index](./docs/README.md)\n- [Getting Started](./docs/getting-started.md)\n- [API Reference](./docs/api/API_REFERENCE.md)\n- [Configuration Guide](./docs/api/CONFIGURATION.md)\n- [Runtime API Guide](./docs/runtime.md)\n- [Auto Translate Guide](./docs/auto-translate.md)\n- [Scanner Guide](./docs/scanner-guide.md)\n- [Environment Variables](./docs/environment-variables.md)\n- [Migration Guide v4.2.0](./docs/migration-guide-v4.2.0.md)\n\n## Security\n\n- No API key is required for the default Auto Translate flow.\n- Do not store secrets in locale files, `.i18ntk-config`, or protection files.\n- Project-specific brand/product terms should be configured by the user, not hardcoded into the package.\n- Report security issues using [SECURITY.md](./SECURITY.md).\n\n## Community\n\n- [Contributing](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Funding](./FUNDING.md)\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n"
+  "readme": "# i18ntk v4.2.1\n\nA i18n toolkit - A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.\n\n![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)\n\n[![npm version](https://img.shields.io/npm/v/i18ntk.svg?color=brightgreen)](https://www.npmjs.com/package/i18ntk)\n[![npm downloads](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)\n[![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)\n[![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)\n[![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.2.1)](https://socket.dev/npm/package/i18ntk/overview/4.2.1)\n\n## Install\n\n```bash\n# global CLI use\nnpm install -g i18ntk\n\n# local project use\nnpm install --save-dev i18ntk\n\n# one-off execution\nnpx i18ntk --help\n```\n\nRequirements:\n\n- Node.js `>=16.0.0`\n- npm `>=8.0.0`\n- No runtime dependencies\n\n## What's New in 4.2.1\n\n- **AUTO TRANSLATE**: Existing target values like `[AR] What We Offer` are now treated as untranslated placeholders for the matching target language and are translated from the source text.\n- **AUTO TRANSLATE**: Before writing each output file, Auto Translate now performs a final leftover check and retries any placeholder-prefixed or source-copy values once.\n- **AUTO TRANSLATE**: If leftovers remain after the final retry, the command warns, includes them in the report, recommends rerunning Auto Translate, and exits with validation failure instead of reporting a clean completion.\n- **SIZING/USAGE**: Usage analysis no longer writes its inferred app source fallback back into the shared locale config, so running usage before sizing no longer makes sizing analyze the wrong directory.\n- **VALIDATION REPORTS**: Validation summary files now include warning and error details, including English-content warning payloads, instead of only totals.\n- **DOCS**: Versioned docs and migration guidance now reflect the current 4.2.1 command surface.\n\n## What's New in 4.1.0\n\n- **FIX**: Critical and high-impact bugs resolved across the v4.0.0 feature set — runtime staleness crashes, backup hash-chain verification, sizing adminAuth crash, scanner `--source-language` propagation, watch callback subscriptions, dead key detection performance, validator key style enforcement, and protection Unicode boundary handling. See [CHANGELOG.md](./CHANGELOG.md) for complete details.\n\n## What's New in 4.0.0\n\n- **SIZING**: `--predict-expansion` flag computes per-key expansion ratios across languages with Safe/Warning/Critical risk tiers for UI layout planning.\n- **WATCH**: `watchLocales()` now returns an EventEmitter-compatible watcher with debounced `change`/`add`/`unlink`/`error` events and SHA-256 hash tracking.\n- **USAGE**: `--cleanup` and `--dry-run-delete` flags identify dead translation keys with confidence scores.\n- **VALIDATOR**: `--enforce-key-style` enforces dot.notation, snake_case, camelCase, kebab-case, or flat naming conventions.\n- **SCANNER**: `--source-language` supports multi-language hardcoded text detection with 12+ language profiles.\n- **BACKUP**: `--incremental` flag creates differential backups with SHA-256 hashing and chained restores.\n- **RUNTIME**: `lazy: true` option defers locale file loading until first key access for lower memory usage.\n- **PROTECTION**: Context-aware rules (`after:word`, `before:word`, `standalone`, `surrounded:left,right`) for precise term masking.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for more release details.\n\n## Quick Start\n\nInitialize a project:\n\n```bash\ni18ntk\n# or with explicit command\ni18ntk --command=init\n```\n\nRun common checks:\n\n```bash\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk --command=sizing\ni18ntk --command=summary\n```\n\nComplete or fix translation files:\n\n```bash\ni18ntk --command=complete\ni18ntk-fixer --help\n```\n\nAuto-translate locale JSON:\n\n```bash\ni18ntk --command=translate\n# or\ni18ntk-translate locales/en/common.json de --report-stdout\n```\n\nThe full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).\n\n## Main Commands\n\nPrimary CLI:\n\n```bash\ni18ntk\ni18ntk --help\ni18ntk --command=init\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk --command=scanner\ni18ntk --command=sizing\ni18ntk --command=complete\ni18ntk --command=translate\ni18ntk --command=summary\n```\n\nStandalone executables:\n\n```bash\ni18ntk-init\ni18ntk-analyze\ni18ntk-validate\ni18ntk-usage\ni18ntk-scanner\ni18ntk-sizing\ni18ntk-complete\ni18ntk-summary\ni18ntk-doctor\ni18ntk-fixer\ni18ntk-backup\ni18ntk-translate\n```\n\nNote: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` directly for backup operations.\n\n## Command Reference\n\n| Command | What it does | Looks for | Writes or changes |\n| --- | --- | --- | --- |\n| `i18ntk` | Opens the interactive management menu. | Project config, setup state, available commands. | Only changes files after you choose a command that writes. |\n| `i18ntk --command=init` / `i18ntk-init` | Sets up locale folders and missing target-language files. | Source language files and selected target languages. | Locale JSON files, `.i18ntk-config`, optional reports/backups. |\n| `i18ntk --command=analyze` / `i18ntk-analyze` | Compares source and target translation coverage. | Missing keys, extra keys, untranslated markers, completion by language. | Markdown/JSON/text reports when report output is enabled. |\n| `i18ntk --command=validate` / `i18ntk-validate` | Validates structure and translation quality risks. | Placeholder mismatches, missing keys, risky URLs/emails/secrets, likely English target text. | Validation summary report. Does not edit locale files. |\n| `i18ntk --command=usage` / `i18ntk-usage` | Maps translation keys to source files and finds unused/missing keys. | Direct i18n calls, literal known-key references, bounded dynamic templates/object maps, unresolved dynamic expressions, hardcoded text candidates, namespace/file naming mismatches. | Usage report with key locations, namespace recommendations, unresolved dynamic expressions, hardcoded text suggestions, and optional dead-key report. Does not delete unless cleanup deletion is explicitly enabled. |\n| `i18ntk --command=scanner` / `i18ntk-scanner` | Scans source for i18n issues and hardcoded user-facing text. | JSX/template text, common text attributes, i18n usage patterns, source-language text profiles. | Scanner report. Does not edit files. |\n| `i18ntk --command=complete` / `i18ntk-complete` | Adds missing keys to target language files for 100% key coverage. | Source-language keys missing from targets. | Target locale JSON files, using missing translation markers/prefixes. |\n| `i18ntk --command=translate` / `i18ntk-translate` | Auto-translates locale JSON using configured provider behavior. | Missing, empty, untranslated-marker, source-copy, likely-English, or visibly corrupt target values by default. | Target locale JSON files and translation reports. Existing translated values are kept unless `--translate-all` is used. |\n| `i18ntk --command=sizing` / `i18ntk-sizing` | Estimates translated string length expansion and layout risk. | Text length, expansion ratios, placeholder-bearing strings. | Sizing report. Does not edit locale files. |\n| `i18ntk --command=summary` / `i18ntk-summary` | Shows project translation status. | Configured locales, reports, completeness status. | Console/report output only. |\n| `i18ntk-fixer` | Fixes placeholder and missing-marker issues. | Placeholder corruption, missing translation markers, configured language files. | Locale JSON files when fixes are applied. Use dry-run options where available before bulk edits. |\n| `i18ntk-backup` | Creates, verifies, restores, and cleans locale backups. | Locale JSON files and backup manifests. | Backup archives/manifests, or restored locale files when using restore. |\n\n## Common Options\n\nMany commands support:\n\n- `--source-dir <path>`\n- `--i18n-dir <path>`\n- `--output-dir <path>`\n- `--source-language <code>`\n- `--ui-language <code>`\n- `--no-prompt`\n- `--help`\n\nCommand-specific tools add their own flags such as `--dry-run`, `--output-report`, `--cleanup`, `--predict-expansion`, or Auto Translate provider options.\n\nExample:\n\n```bash\ni18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports\n```\n\n## Auto Translate\n\nInteractive manager flow:\n\n```bash\ni18ntk\n# choose \"Auto Translate\"\n```\n\nDirect CLI examples:\n\n```bash\ni18ntk-translate locales/en/common.json de\ni18ntk-translate locales/en/common.json fr --dry-run --report-stdout\ni18ntk-translate locales/en es --source-dir locales/en --files \"*.json\" --no-confirm --preserve-placeholders\n```\n\nProvider examples:\n\n```bash\nexport DEEPL_API_KEY=\"your-deepl-api-key\"\ni18ntk-translate locales/en/common.json de --provider deepl --no-confirm --preserve-placeholders\n\nexport LIBRETRANSLATE_URL=\"https://libretranslate.com/translate\"\nexport LIBRETRANSLATE_API_KEY=\"optional-api-key\"\ni18ntk-translate locales/en/common.json es --provider libretranslate --no-confirm --preserve-placeholders\n```\n\n`google` remains the default provider. You can also set `I18NTK_TRANSLATE_PROVIDER=deepl` or `I18NTK_TRANSLATE_PROVIDER=libretranslate`.\n\nProvider requests are HTTPS-only and response-size limited, and security logs redact provider query strings and response bodies. DeepL is pinned to official DeepL hosts by default; set `I18NTK_ALLOW_CUSTOM_TRANSLATE_HOSTS=1` only for a trusted DeepL-compatible proxy. Custom LibreTranslate URLs are blocked for localhost/private IP ranges unless `I18NTK_ALLOW_PRIVATE_TRANSLATE_URLS=1` is set for trusted local testing. Keep provider API keys in environment variables or a secret manager.\n\nThe manager flow asks for:\n\n- source locale directory, either the folder with JSON files or a locale root such as `./locales`\n- source language code\n- one or more target languages, or `all`\n- one JSON file or all JSON files in the source directory\n\nIf you select a locale root such as `./locales` and choose source language `en`, the manager automatically uses `./locales/en` when that folder contains the source JSON files.\n\nBefore writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:\n\n```text\nlocales/en/common.json\nlocales/de/common.json\nlocales/fr/common.json\n```\n\nAuto Translate is target-aware by default. When a target file already exists, it keeps translated target values and only sends values that are missing, empty, marked as untranslated, still identical to the source, likely still English, or visibly corrupt from encoding damage such as `?????`, replacement characters, or common mojibake. Use `--translate-all` when you intentionally want to re-translate every source string.\n\n### Placeholder Handling\n\nAuto Translate detects common placeholders such as:\n\n- `{name}`\n- `{{count}}`\n- `%s`\n- `%d`\n- `:id`\n- `%{name}`\n- `${value}`\n- `{count, plural, one {# item} other {# items}}`\n- `$t(common.save)`\n- `%(total).2f`\n\nUseful flags:\n\n- `--preserve-placeholders`: translate text around placeholders and reinsert original tokens\n- `--skip-placeholders`: copy placeholder-bearing strings unchanged\n- `--send-placeholders`: send placeholder-bearing strings through translation after masking\n- `--custom-regex <regex>`: add project-specific placeholder detection\n- `--only-missing`: keep existing translated target values and translate only missing/source-copy/likely English values (default)\n- `--translate-all`: re-translate every source string\n\nProgress output is stage-aware for large files. Normal keys are reported as `Translating strings`, while preserve-mode placeholder work is reported as `Translating placeholder-safe text segments`; each progress update includes the current key path when available.\n\n### Protected Terms and Keys\n\nAuto Translate can create and use a project-local protection file:\n\n```bash\ni18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json\n```\n\nExample `i18ntk-auto-translate.json`:\n\n```json\n{\n  \"version\": 1,\n  \"terms\": [\n    \"BrandName\",\n    \"PRODUCT_CODE\",\n    { \"value\": \"OK\", \"context\": \"after:Click|Press|Tap\" },\n    { \"value\": \"API\", \"context\": \"standalone\" }\n  ],\n  \"keys\": [\"app.brandName\", \"legal.companyName\", \"product.*.symbol\"],\n  \"values\": [\"BrandName Ltd\", \"support@example.com\"],\n  \"patterns\": [\"[A-Z]{2,}-\\\\d+\"]\n}\n```\n\n- `terms` are masked before translation and restored exactly afterward.\n  - **Plain strings**: masked everywhere (backward compatible).\n  - **Context objects**: masked only in specific contexts (`after:word`, `before:word`, `standalone`, `surrounded:left,right`).\n- `keys` are exact key paths or `*` wildcard paths copied unchanged.\n- `values` are exact source values copied unchanged.\n- `patterns` are JavaScript regex strings for advanced protected substrings.\n\nUseful flags:\n\n- `--protection-file <path>`\n- `--create-protection-file`\n- `--no-protection`\n\nOpen Settings and choose `Auto Translate` to edit defaults for placeholder mode, translate-only-needed mode, concurrency, batch size, retry settings, report output, BOM output, protection file path, first-run setup prompt, and update prompt.\n\nSee [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.\n\n## Validation\n\nValidation checks locale structure, completeness, placeholders, and content risks.\n\nValidation warning types are specific:\n\n- `Potential risky content`: URL, email address, or secret-like value\n- `Possible untranslated English content`: target-language value appears to contain too much English\n\nEnglish-content warnings include:\n\n- detected English percentage\n- configured threshold\n- matched word count\n- sample matched words\n\nTune warnings in `.i18ntk-config`:\n\n```json\n{\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"]\n}\n```\n\n## Sizing Analysis\n\n`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.\n\n```bash\ni18ntk-sizing --source-dir ./locales --format table\ni18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports\n```\n\nUse `--detailed` to print per-file rows in the terminal.\n\n### Expansion Prediction (New in 4.0.0)\n\nPredict UI layout overflow risk by analyzing per-key character-count expansion across languages:\n\n```bash\ni18ntk-sizing --source-dir ./locales --predict-expansion --output-report\n```\n\nExpansion ratios are classified into risk tiers:\n\n- **Safe** (<30% expansion): no UI impact expected\n- **Warning** (30–50%): may overflow in tight layouts — test on target languages\n- **Critical** (>50%): high risk of truncation — review UI element sizing\n\nThe report includes a built-in language-pair expansion reference table (EN→DE +35%, EN→RU +50%, EN→JA −40%, etc.) and lists the top-30 most-expanded keys.\n\n## Scanner: Multi-Language Detection (New in 4.0.0)\n\n`i18ntk-scanner` now supports detecting hardcoded text in multiple source languages beyond English:\n\n```bash\ni18ntk-scanner --source-dir ./src --source-language de\ni18ntk-scanner --source-dir ./src --source-language ja --output-report\n```\n\nSupported language profiles (12+): English, German, French, Spanish, Japanese, Chinese, Russian, Korean, Arabic, Hindi, and more. Each profile includes language-specific character ranges, stopword lists for false-positive filtering, and transliteration rules for key generation.\n\n## Usage: Dead Key Detection (New in 4.0.0)\n\n`i18ntk-usage` can identify translation keys that are defined but never referenced in source code:\n\n```bash\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup --dry-run-delete\n```\n\nEach dead key receives a confidence score (0.0–1.0) factoring:\n- Unresolved dynamic key patterns (e.g., `` t(`prefix.${dynamic}`) ``) — lower score and listed in the usage report; simple consts, bounded arrays, object maps, and ternaries are expanded to exact keys where possible\n- Key appears in source code comments or JSDoc — medium score\n- Parent file recently modified (<30 days) — medium score\n- No references found anywhere — high score (>0.8)\n\nThe `--dry-run-delete` flag writes a `.dead-keys.json` report for review before any destructive action.\n\n## Validator: Key Naming Conventions (New in 4.0.0)\n\nEnforce consistent translation key naming across your project:\n\n```bash\ni18ntk-validate --enforce-key-style\n```\n\nConfigure the expected style in `.i18ntk-config`:\n\n```json\n{\n  \"keyStyle\": \"dot.notation\"\n}\n```\n\nSupported styles: `dot.notation`, `snake_case`, `camelCase`, `kebab-case`, `flat`. Violations are reported as warnings with suggested canonical forms.\n\n## Watch: Hot Reload (New in 4.0.0)\n\n`utils/watch-locales.js` now provides debounced file watching with EventEmitter support:\n\n```js\nconst watchLocales = require('i18ntk/utils/watch-locales');\nconst watcher = watchLocales('./locales');\n\nwatcher.on('change', (filePath) => {\n  console.log('Locale changed:', filePath);\n});\n\nwatcher.on('add', (filePath) => {\n  console.log('Locale added:', filePath);\n});\n\n// Later:\nwatcher.stop();\n```\n\nFeatures: 300ms debounce (configurable), SHA-256 hash tracking to skip no-change saves, and a maximum of 50 watched directories.\n\n### Migration\n\nThe `watchLocales` return value gained EventEmitter methods in v4.0.0. Existing stop-function usage still works:\n\n```js\nconst stop = watchLocales('./locales', onChange);\n```\n\nCan be updated to:\n\n```js\nconst watcher = watchLocales('./locales');\nwatcher.on('change', onChange);\nwatcher.stop();\n```\n\nPassing a callback as the second argument is still supported — it auto-subscribes to `change` and `add` events.\n\n## Backup: Incremental Mode (New in 4.0.0)\n\nCreate differential backups that only include changed files:\n\n```bash\ni18ntk-backup create ./locales --incremental\n```\n\nIncremental backups store SHA-256 hashes per file and a parent-chain reference. Restoring an incremental backup automatically chains from the oldest full backup through each incremental diff in order. Chain depth is capped at 10 increments. Use `verify` to validate the hash chain.\n\n## Runtime: Lazy Loading (New in 4.0.0)\n\nReduce memory usage by deferring locale file loads until first key access:\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  lazy: true\n});\n\nconsole.log(i18n.t('common.hello')); // loads common.json on first access\n```\n\nWhen `lazy: true`, the runtime builds a key-to-file manifest on first access and loads individual files on demand. Files are loaded once and cached. If the manifest is missing or incomplete, the runtime falls back to full eager loading for that language. Manifest size is capped at 100KB with path containment validation.\n\nProduction guidance:\n\n- Prefer the object returned from `initRuntime()` instead of module-level `runtime.t()` in apps with multiple tenants, projects, or locale roots.\n- Use `lazy: true` for large modular locale folders where lower steady-state memory matters more than a small first-key lookup cost.\n- Use `preload: true` without `lazy` for small locale sets or latency-sensitive startup paths.\n- Call `refresh(language)` after deploying or writing changed locale files so cached data and lazy manifests are rebuilt.\n- Use per-call language overrides when rendering one-off alternate-language strings: `i18n.t('common.hello', {}, { language: 'de' })`.\n- Use `translateBatch()` for small groups of labels and `clearCache()` / `getCacheInfo()` for cache maintenance and diagnostics.\n- `i18ntk/runtime/enhanced` remains available for compatibility with existing async/encryption users, but new production integrations should start with `i18ntk/runtime`.\n\n## Runtime API\n\nUse `i18ntk/runtime` when an application needs to read locale JSON files at runtime.\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  fallbackLanguage: 'en',\n  keySeparator: '.',\n  preload: true\n});\n\nconsole.log(i18n.t('common.hello'));\ni18n.setLanguage('fr');\nconsole.log(i18n.getLanguage());\nconsole.log(i18n.getAvailableLanguages());\ni18n.refresh('fr');\n```\n\nUseful production helpers:\n\n```js\ni18n.t('common.hello', {}, { language: 'de' }); // per-call language override\ni18n.translateBatch(['menu.home', 'menu.settings']);\ni18n.clearCache('fr');\nconsole.log(i18n.getCacheInfo());\n```\n\nSee [docs/runtime.md](./docs/runtime.md) for runtime details.\n\n## Configuration\n\ni18ntk uses a project-local `.i18ntk-config` file.\n\nExample:\n\n```json\n{\n  \"version\": \"4.2.1\",\n  \"sourceDir\": \"./locales\",\n  \"i18nDir\": \"./locales\",\n  \"outputDir\": \"./i18ntk-reports\",\n  \"sourceLanguage\": \"en\",\n  \"defaultLanguages\": [\"en\", \"de\", \"es\", \"fr\", \"ru\"],\n  \"reports\": {\n    \"format\": \"markdown\"\n  },\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"],\n  \"autoTranslate\": {\n    \"placeholderMode\": \"preserve\",\n    \"concurrency\": 12,\n    \"batchSize\": 100,\n    \"progressInterval\": 25,\n    \"retryCount\": 3,\n    \"retryDelay\": 1000,\n    \"timeout\": 15000,\n    \"dryRunFirst\": true,\n    \"onlyMissingOrEnglish\": true,\n    \"reportStdout\": true,\n    \"bom\": false,\n    \"protectionEnabled\": true,\n    \"protectionFile\": \"./i18ntk-auto-translate.json\",\n    \"promptProtectionSetup\": true,\n    \"promptProtectionUpdate\": true\n  },\n  \"setup\": {\n    \"completed\": true\n  }\n}\n```\n\nSee [docs/api/CONFIGURATION.md](./docs/api/CONFIGURATION.md) for the full configuration model.\n\n## Public Package Contents\n\nThe public package intentionally ships runtime and CLI files only. The publish staging script excludes development-only content such as tests, scripts, docs, release staging folders, local config files, and generated protection files.\n\nThe package includes:\n\n- CLI entry points under `main/`\n- manager commands and services\n- runtime API files under `runtime/`\n- settings UI files required at runtime\n- bundled internal UI locales\n- shared utilities required by the shipped commands\n- `README.md`, `CHANGELOG.md`, `LICENSE`, and policy files\n\nThe public package manifest includes `readmeFilename: \"README.md\"`, and the release staging script fails if `README.md` is missing or empty.\n\n## Documentation\n\n- [Documentation Index](./docs/README.md)\n- [Getting Started](./docs/getting-started.md)\n- [API Reference](./docs/api/API_REFERENCE.md)\n- [Configuration Guide](./docs/api/CONFIGURATION.md)\n- [Runtime API Guide](./docs/runtime.md)\n- [Auto Translate Guide](./docs/auto-translate.md)\n- [Scanner Guide](./docs/scanner-guide.md)\n- [Environment Variables](./docs/environment-variables.md)\n- [Migration Guide v4.2.1](./docs/migration-guide-v4.2.1.md)\n\n## Security\n\n- No API key is required for the default Auto Translate flow.\n- Do not store secrets in locale files, `.i18ntk-config`, or protection files.\n- Project-specific brand/product terms should be configured by the user, not hardcoded into the package.\n- Report security issues using [SECURITY.md](./SECURITY.md).\n\n## Community\n\n- [Contributing](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Funding](./FUNDING.md)\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n"
 }

package/utils/translate/report.js

@@ -9,6 +9,7 @@ function generateReport(skippedKeys, translatedCount, totalCount, options = {})
     timestamp = new Date().toISOString(),
     placeholderProtected = 0,
     protectedSkipped = 0,
+    residualUntranslated = [],
   } = options;
   const placeholderSkipped = skippedKeys.filter(key => key.skipReason !== 'protected');
   const protectedKeys = skippedKeys.filter(key => key.skipReason === 'protected');
@@ -28,13 +29,36 @@ function generateReport(skippedKeys, translatedCount, totalCount, options = {})
   lines.push(`  Placeholder-safe: ${String(placeholderProtected).padStart(6)}`);
   lines.push(`  Protected:       ${String(protectedSkipped).padStart(6)}`);
   lines.push(`  Skipped:         ${skippedKeys.length}`);
+  lines.push(`  Leftover warnings: ${String(residualUntranslated.length).padStart(3)}`);
   lines.push('='.repeat(72));
 
-  if (skippedKeys.length === 0) {
+  if (skippedKeys.length === 0 && residualUntranslated.length === 0) {
     lines.push('');
     lines.push('  All strings were processed. No keys were skipped.');
     lines.push('');
   } else {
+    if (residualUntranslated.length > 0) {
+      lines.push('');
+      lines.push('  WARNING: The following values still look untranslated after');
+      lines.push('  Auto Translate and one final retry.');
+      lines.push('');
+      lines.push('  Rerun Auto Translate to capture leftovers, then review this');
+      lines.push('  report if any warnings remain.');
+      lines.push('');
+      lines.push(`  ${'-'.repeat(72)}`);
+      lines.push('  File                 Key Path                                 Current Value');
+      lines.push(`  ${'-'.repeat(72)}`);
+      for (const item of residualUntranslated) {
+        const fileDisplay = String(item.fileName || path.basename(sourceFile || '') || 'N/A').padEnd(20).slice(0, 20);
+        const keyDisplay = String(item.keyPath || '').padEnd(40).slice(0, 40);
+        const valDisplay = String(item.value || '').length > 90
+          ? String(item.value).slice(0, 87) + '...'
+          : String(item.value || '');
+        lines.push(`  ${fileDisplay} ${keyDisplay} ${valDisplay}`);
+      }
+      lines.push(`  ${'-'.repeat(72)}`);
+    }
+
     if (placeholderSkipped.length > 0) {
       lines.push('');
       lines.push('  WARNING: The following keys were SKIPPED because they contain');
@@ -78,7 +102,10 @@ function generateReport(skippedKeys, translatedCount, totalCount, options = {})
   }
 
   lines.push('');
-  if (skippedKeys.length === 0) {
+  if (residualUntranslated.length > 0) {
+    lines.push('  Auto Translate did not fully complete because leftover');
+    lines.push('  placeholder-prefixed or English-looking values remain.');
+  } else if (skippedKeys.length === 0) {
     lines.push('  The generated file can be used immediately after review.');
     lines.push('  Placeholder tokens were preserved automatically where found.');
   } else if (placeholderSkipped.length > 0) {