i18ntk 4.1.0 → 4.2.1

package/main/i18ntk-translate.js

@@ -24,9 +24,11 @@
  *   --protection-file <path>   JSON file with protected terms, keys, values, and patterns
  *   --create-protection-file   Create the protection JSON file if it does not exist
  *   --no-protection            Disable protected term/key/value handling for this run
- *   --concurrency <n>          Max concurrent API requests (default: 3)
+ *   --concurrency <n>          Max concurrent API requests (default: 12, Google max: 100)
  *   --batch-size <n>           Number of text segments per batch (default: 50)
  *   --dry-run                  Preview mode without API calls
+ *   --only-missing             Translate only missing, marker, source-copy, or likely English target values
+ *   --translate-all            Re-translate every source string even when a target value already exists
  *   --report-file <path>       Write report to file
  *   --report-stdout            Print report to stdout
  *   --bom                      Output UTF-8 with BOM
@@ -61,9 +63,10 @@ const {
   restoreText,
   shouldPreserveWholeValue,
 } = require('../utils/translate/protection');
-const { translateBatch } = require('../utils/translate/api');
-const { collectLeaves, setLeaf, deepClone } = require('../utils/translate/traverse');
+const { translateBatch, DEFAULT_CONCURRENCY, clampProviderConcurrency } = require('../utils/translate/api');
+const { collectLeaves, getLeaf, setLeaf, deepClone } = require('../utils/translate/traverse');
 const { generateReport, writeReport, formatSummaryLine } = require('../utils/translate/report');
+const { analyzeEnglishContent } = require('../utils/validation-risk');
 const {
   confirmGlobalChoice,
   confirmPerKey,
@@ -101,10 +104,12 @@ function printHelp() {
     '  --protection-file <path>   Protected terms/keys JSON file (default: i18ntk-auto-translate.json)',
     '  --create-protection-file   Create the protection JSON file if missing',
     '  --no-protection            Disable protected term/key/value handling',
-    '  --concurrency <n>          Max concurrent API requests (default: 3)',
+    '  --concurrency <n>          Max concurrent API requests (default: 12, Google max: 100)',
     '  --batch-size <n>           Number of text segments per batch (default: 50)',
     '  --progress-interval <n>    Progress update interval (default: 10)',
     '  --dry-run                  Preview: show what would be skipped',
+    '  --only-missing             Translate only missing, marker, source-copy, or likely English target values (default)',
+    '  --translate-all            Re-translate every source string even when target values already exist',
     '  --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',
@@ -141,10 +146,11 @@ function parseArgs(argv) {
     protectionFile: DEFAULT_PROTECTION_FILE,
     protectionEnabled: true,
     createProtectionFile: false,
-    concurrency: 3,
+    concurrency: DEFAULT_CONCURRENCY,
     batchSize: 50,
     progressInterval: 10,
     dryRun: false,
+    onlyMissingOrEnglish: true,
     reportFile: null,
     reportStdout: false,
     bom: false,
@@ -168,6 +174,8 @@ function parseArgs(argv) {
     else if (arg === '--no-protection') { args.protectionEnabled = false; }
     else if (arg === '--create-protection-file') { args.createProtectionFile = true; }
     else if (arg === '--dry-run') { args.dryRun = true; }
+    else if (arg === '--translate-all' || arg === '--force-translate') { args.onlyMissingOrEnglish = false; }
+    else if (arg === '--only-missing' || arg === '--only-missing-or-english') { args.onlyMissingOrEnglish = 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]; }
@@ -176,7 +184,7 @@ function parseArgs(argv) {
     else if (arg === '--provider' && i + 1 < argv.length) { args.provider = argv[++i]; }
     else if (arg === '--custom-regex' && i + 1 < argv.length) { args.customRegex.push(argv[++i]); }
     else if (arg === '--protection-file' && i + 1 < argv.length) { args.protectionFile = argv[++i]; }
-    else if (arg === '--concurrency' && i + 1 < argv.length) { args.concurrency = parseInt(argv[++i], 10) || 3; }
+    else if (arg === '--concurrency' && i + 1 < argv.length) { args.concurrency = parseInt(argv[++i], 10) || DEFAULT_CONCURRENCY; }
     else if (arg === '--batch-size' && i + 1 < argv.length) { args.batchSize = parseInt(argv[++i], 10) || 50; }
     else if (arg === '--progress-interval' && i + 1 < argv.length) { args.progressInterval = parseInt(argv[++i], 10) || 10; }
     else if (arg === '--report-file' && i + 1 < argv.length) { args.reportFile = argv[++i]; }
@@ -202,13 +210,23 @@ function parseArgs(argv) {
     process.exit(1);
   }
 
-  args.concurrency = clampInt(args.concurrency, 1, 25, 3);
+  args.concurrency = clampProviderConcurrency(args.concurrency, args.provider, DEFAULT_CONCURRENCY);
   args.batchSize = clampInt(args.batchSize, 1, 10000, 50);
   args.progressInterval = clampInt(args.progressInterval, 1, 10000, 10);
 
   return args;
 }
 
+const UNTRANSLATED_MARKERS = new Set([
+  '',
+  '__not_translated__',
+  'not_translated',
+  '[translate]',
+  '[not translated]',
+  'todo',
+  'tbd',
+]);
+
 function clampInt(value, min, max, fallback) {
   const num = parseInt(value, 10);
   if (!Number.isInteger(num)) return fallback;
@@ -289,6 +307,136 @@ function classifyLeaves(leaves, customRegex) {
   return { withPlaceholders, withoutPlaceholders };
 }
 
+function readExistingTargetData(targetPath) {
+  if (!SecurityUtils.safeExistsSync(targetPath, path.dirname(targetPath))) {
+    return null;
+  }
+
+  try {
+    const raw = SecurityUtils.safeReadFileSync(targetPath, path.dirname(targetPath), 'utf-8').replace(/^\uFEFF/, '');
+    return JSON.parse(raw);
+  } catch (error) {
+    console.warn(`Warning: Could not read existing target file "${targetPath}": ${error.message}`);
+    return null;
+  }
+}
+
+function isUntranslatedMarker(value) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  return UNTRANSLATED_MARKERS.has(normalized);
+}
+
+function isLikelyEnglish(value, args) {
+  const text = String(value || '').trim();
+  if (!text) return false;
+  const analysis = analyzeEnglishContent(text, {
+    allowedEnglishTerms: args.allowedEnglishTerms,
+  });
+  const threshold = Number.isFinite(Number(args.englishThresholdPercent))
+    ? Number(args.englishThresholdPercent)
+    : 10;
+  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();
+  if (!text) return false;
+  if (text.includes('\uFFFD')) return true;
+
+  const compact = text.replace(/[\s.,!;:()[\]{}'"`~_\-]/g, '');
+  if (compact.length >= 1 && /^\?+$/.test(compact)) return true;
+  if (/\?{3,}/.test(text)) return true;
+
+  const questionCount = (text.match(/\?/g) || []).length;
+  const visibleLength = Math.max(text.replace(/\s/g, '').length, 1);
+  if (questionCount >= 3 && questionCount / visibleLength >= 0.5) return true;
+
+  if (/[\u0080-\u009F]/.test(text) && /[ÃÂÐÑ]/.test(text)) return true;
+
+  const mojibakePatterns = [
+    /[ÃÂ][\u0080-\u00BF]/,
+    /Ð[\u0080-\u00BF]/,
+    /Ñ[\u0080-\u00BF]/,
+    /ã[‚ƒ€]/,
+  ];
+  return mojibakePatterns.some((pattern) => pattern.test(text));
+}
+
+function shouldTranslateTargetValue(sourceValue, targetValue, args) {
+  if (targetValue === undefined || targetValue === null) return true;
+  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 {
+      translatableLeaves: sourceLeaves,
+      existingLeaves: [],
+    };
+  }
+
+  const translatableLeaves = [];
+  const existingLeaves = [];
+
+  for (const leaf of sourceLeaves) {
+    const targetValue = getLeaf(targetData, leaf.keyPath);
+    if (shouldTranslateTargetValue(leaf.value, targetValue, args)) {
+      translatableLeaves.push(leaf);
+    } else {
+      existingLeaves.push({ ...leaf, value: targetValue, skipReason: 'existing' });
+    }
+  }
+
+  return { translatableLeaves, existingLeaves };
+}
+
 async function resolvePlaceholderStrategy(args) {
   const interactive = isInteractive({ noPrompt: args.noConfirm });
 
@@ -403,7 +551,11 @@ function prepareDirectBatch(toTranslate, customRegex, protection) {
 
 async function runTranslation(maskedBatch, targetLang, options) {
   const batchItems = maskedBatch.map((item) => ({ value: item.masked, keyPath: item.keyPath }));
-  const results = await translateBatchInChunks(batchItems, targetLang, options);
+  const results = await translateBatchInChunks(batchItems, targetLang, {
+    ...options,
+    stageLabel: 'Translating strings',
+    progressUnit: 'strings',
+  });
   return results;
 }
 
@@ -428,6 +580,9 @@ async function translateBatchInChunks(batch, targetLang, options) {
             total: batch.length,
             chunkCompleted: info.completed,
             chunkTotal: info.total,
+            keyPath: info.keyPath,
+            stage: options.stageLabel || 'Translating',
+            unit: options.progressUnit || 'items',
           });
         }
       },
@@ -522,7 +677,11 @@ async function translatePreservedItems(items, targetLang, options, customRegex,
     return plan;
   });
 
-  const translatedSegments = await translateBatchInChunks(segmentJobs, targetLang, options);
+  const translatedSegments = await translateBatchInChunks(segmentJobs, targetLang, {
+    ...options,
+    stageLabel: 'Translating placeholder-safe text segments',
+    progressUnit: 'segments',
+  });
 
   return plans.map((plan) => {
     const value = plan.segments.map((segment) => {
@@ -580,8 +739,8 @@ async function translateItems(toTranslate, targetLang, options, customRegex, pro
   return finalResults;
 }
 
-function applyResults(sourceData, translatedResults, toTranslate, toSkip) {
-  const output = deepClone(sourceData);
+function applyResults(sourceData, translatedResults, toTranslate, toSkip, targetData = null) {
+  const output = deepClone(targetData || sourceData);
 
   for (let i = 0; i < toTranslate.length; i++) {
     setLeaf(output, toTranslate[i].keyPath, translatedResults[i]);
@@ -594,6 +753,47 @@ function applyResults(sourceData, translatedResults, toTranslate, toSkip) {
   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);
+  return value.length > 72 ? `${value.slice(0, 69)}...` : value;
+}
+
 function writeOutput(outputData, outputPath, bom) {
   const resolvedOutputPath = path.resolve(process.cwd(), outputPath);
   const dir = path.dirname(resolvedOutputPath);
@@ -611,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 {
@@ -628,16 +829,19 @@ async function processFile(sourcePath, targetLang, args) {
     return { total: 0, translated: 0, skipped: 0, skippedKeys: [] };
   }
 
-  const protection = args.protection || loadProtectionConfig(args.protectionFile, {
-    enabled: args.protectionEnabled,
-    create: args.createProtectionFile,
+  const targetData = readExistingTargetData(targetPath);
+  const { translatableLeaves: candidateLeaves, existingLeaves } = planTargetAwareLeaves(leaves, targetData, runArgs);
+
+  const protection = runArgs.protection || loadProtectionConfig(runArgs.protectionFile, {
+    enabled: runArgs.protectionEnabled,
+    create: runArgs.createProtectionFile,
   });
-  const protectedLeaves = leaves
+  const protectedLeaves = candidateLeaves
     .filter((leaf) => shouldPreserveWholeValue(leaf.keyPath, leaf.value, protection))
     .map((leaf) => ({ ...leaf, skipReason: 'protected' }));
-  const translatableLeaves = leaves.filter((leaf) => !shouldPreserveWholeValue(leaf.keyPath, leaf.value, protection));
-  const { withPlaceholders, withoutPlaceholders } = classifyLeaves(translatableLeaves, args.customRegex);
-  const { strategy, interactiveMode } = await resolvePlaceholderStrategy(args);
+  const translatableLeaves = candidateLeaves.filter((leaf) => !shouldPreserveWholeValue(leaf.keyPath, leaf.value, protection));
+  const { withPlaceholders, withoutPlaceholders } = classifyLeaves(translatableLeaves, runArgs.customRegex);
+  const { strategy, interactiveMode } = await resolvePlaceholderStrategy(runArgs);
 
   if (args.dryRun && strategy === 'skip' && withPlaceholders.length > 0) {
     await previewSkipped(withPlaceholders);
@@ -649,13 +853,17 @@ async function processFile(sourcePath, targetLang, args) {
       skippedKeys,
       placeholderProtected: 0,
       protectedSkipped: protectedLeaves.length,
+      skippedExisting: existingLeaves.length,
       dryRun: true,
     };
   }
 
   if (args.dryRun) {
     const protectedCount = strategy === 'send' ? 0 : withPlaceholders.length;
-    console.log(`[${fileName}] Dry-run: ${leaves.length} strings would be translated.`);
+    console.log(`[${fileName}] Dry-run: ${candidateLeaves.length} of ${leaves.length} strings would be translated.`);
+    if (existingLeaves.length > 0) {
+      console.log(`[${fileName}] Dry-run: ${existingLeaves.length} existing translated strings would be kept.`);
+    }
     if (protectedLeaves.length > 0) {
       console.log(`[${fileName}] Dry-run: ${protectedLeaves.length} protected keys/values would be copied unchanged.`);
     }
@@ -667,11 +875,12 @@ async function processFile(sourcePath, targetLang, args) {
     }
     return {
       total: leaves.length,
-      translated: leaves.length - protectedLeaves.length,
+      translated: candidateLeaves.length - protectedLeaves.length,
       skipped: protectedLeaves.length,
       skippedKeys: protectedLeaves,
       placeholderProtected: protectedCount,
       termProtected: hasProtectionRules(protection),
+      skippedExisting: existingLeaves.length,
       dryRun: true,
     };
   }
@@ -679,8 +888,9 @@ async function processFile(sourcePath, targetLang, args) {
   const decisions = await resolvePerKeyDecisions(withPlaceholders, interactiveMode);
   const { toTranslate, toSkip } = buildTranslateList(withPlaceholders, withoutPlaceholders, strategy, decisions);
   toSkip.push(...protectedLeaves);
+  toSkip.push(...existingLeaves);
   const placeholderProtected = toTranslate.filter((leaf) => leaf.placeholderMode === 'preserve').length;
-  const placeholderSkipped = toSkip.filter((leaf) => leaf.skipReason !== 'protected').length;
+  const placeholderSkipped = toSkip.filter((leaf) => leaf.skipReason !== 'protected' && leaf.skipReason !== 'existing').length;
 
   if (placeholderSkipped > 0) {
     console.log(`[${fileName}] Skipping ${placeholderSkipped} keys with placeholders.`);
@@ -691,6 +901,9 @@ async function processFile(sourcePath, targetLang, args) {
   if (protectedLeaves.length > 0) {
     console.log(`[${fileName}] Copying ${protectedLeaves.length} protected keys/values unchanged.`);
   }
+  if (existingLeaves.length > 0) {
+    console.log(`[${fileName}] Keeping ${existingLeaves.length} existing translated keys.`);
+  }
   if (hasProtectionRules(protection)) {
     console.log(`[${fileName}] Protecting terms from: ${protection.filePath}`);
   }
@@ -698,17 +911,21 @@ 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) {
-        process.stdout.write(`\r[${fileName}] Translating... ${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);
+        const keySuffix = keyPath ? ` | ${keyPath}` : '';
+        process.stdout.write(`\r[${fileName}] ${stage}: ${info.completed}/${info.total} ${unit}${keySuffix}`);
       }
     },
     onError: (err) => {
@@ -719,8 +936,10 @@ async function processFile(sourcePath, targetLang, args) {
   let translatedResults;
   try {
     if (toTranslate.length > 0) {
-      translatedResults = await translateItems(toTranslate, targetLang, translateOptions, args.customRegex, protection);
+      console.log(`[${fileName}] Preparing translation plan for ${toTranslate.length} keys.`);
+      translatedResults = await translateItems(toTranslate, targetLang, translateOptions, runArgs.customRegex, protection);
       process.stdout.write('\n');
+      console.log(`[${fileName}] Applying translated values.`);
     } else {
       translatedResults = [];
     }
@@ -728,18 +947,47 @@ async function processFile(sourcePath, targetLang, args) {
     cleanupPlaceholderManifest(manifestPath);
   }
 
-  const output = applyResults(sourceData, translatedResults, toTranslate, toSkip);
-  writeOutput(output, targetPath, args.bom);
+  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, runArgs.bom);
 
   console.log(`[${fileName}] Written: ${targetPath}`);
 
   return {
     total: leaves.length,
     translated: translatedResults.length,
-    skipped: toSkip.length,
-    skippedKeys: toSkip,
+    skipped: toSkip.filter((leaf) => leaf.skipReason !== 'existing').length,
+    skippedKeys: toSkip.filter((leaf) => leaf.skipReason !== 'existing'),
     placeholderProtected,
     protectedSkipped: protectedLeaves.length,
+    skippedExisting: existingLeaves.length,
+    finalCheckRetried,
+    residualUntranslated,
   };
 }
 
@@ -787,6 +1035,9 @@ async function run(args) {
   let grandSkipped = 0;
   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);
@@ -796,25 +1047,39 @@ async function run(args) {
       grandSkipped += result.skipped;
       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));
+  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);
     }
@@ -827,13 +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,
   };
 }
 
@@ -852,6 +1121,7 @@ if (require.main === module) {
 module.exports = {
   parseArgs,
   resolveSourceFiles,
+  isBrokenTranslationValue,
   processFile,
   run,
 };