i18ntk 3.0.0 → 3.1.0

package/main/i18ntk-translate.js

@@ -9,7 +9,7 @@
  * Usage:
  *   i18ntk-translate <source-file> <target-lang> [options]
  *   i18ntk-translate locales/en/common.json de
- *   i18ntk-translate locales/en/common.json fr --no-confirm --skip-placeholders
+ *   i18ntk-translate locales/en/common.json fr --no-confirm --preserve-placeholders
  *   i18ntk-translate locales/en/common.json es --dry-run
  *
  * Options:
@@ -17,9 +17,14 @@
  *   --output-dir <dir>         Output directory (default: ./locales/<lang>)
  *   --custom-regex <regex>     Additional placeholder regex pattern
  *   --no-confirm               Skip all confirmation dialogs
+ *   --preserve-placeholders    Translate text around placeholders and reinsert tokens
  *   --skip-placeholders        Skip all strings containing placeholders
- *   --send-placeholders        Translate all strings including placeholders
+ *   --send-placeholders        Translate all strings including masked placeholders
+ *   --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)
+ *   --batch-size <n>           Number of text segments per batch (default: 50)
  *   --dry-run                  Preview mode without API calls
  *   --report-file <path>       Write report to file
  *   --report-stdout            Print report to stdout
@@ -34,11 +39,27 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const packageJson = require('../package.json');
 const ExitCodes = require('../utils/exit-codes');
+const SecurityUtils = require('../utils/security');
 const { isInteractive } = require('../utils/prompt-helper');
-const { detectPlaceholders, maskPlaceholders, unmaskPlaceholders } = require('../utils/translate/placeholder');
+const {
+  detectPlaceholders,
+  maskPlaceholders,
+  splitByPlaceholders,
+  unmaskPlaceholders,
+} = require('../utils/translate/placeholder');
+const {
+  DEFAULT_PROTECTION_FILE,
+  createProtectionFile,
+  hasProtectionRules,
+  loadProtectionConfig,
+  protectText,
+  restoreText,
+  shouldPreserveWholeValue,
+} = require('../utils/translate/protection');
 const { translateBatch } = require('../utils/translate/api');
 const { collectLeaves, setLeaf, deepClone } = require('../utils/translate/traverse');
 const { generateReport, writeReport, formatSummaryLine } = require('../utils/translate/report');
@@ -63,7 +84,7 @@ function printHelp() {
     '  i18ntk-translate locales/en/common.json de',
     '  i18ntk-translate locales/en/common.json fr --dry-run',
     '  i18ntk-translate locales/en/ es --files "*.json"',
-    '  i18ntk-translate locales/en/common.json ja --no-confirm --skip-placeholders',
+    '  i18ntk-translate locales/en/common.json ja --no-confirm --preserve-placeholders',
     '  i18ntk-translate locales/en/common.json ko --report-file report.txt',
     '',
     'Options:',
@@ -72,9 +93,15 @@ function printHelp() {
     '  --source-lang <code>       Source language code (default: en)',
     '  --custom-regex <regex>     Additional placeholder regex pattern',
     '  --no-confirm               Automate: skip confirmation dialogs',
+    '  --preserve-placeholders    Translate text around placeholders and reinsert tokens',
     '  --skip-placeholders        Skip all strings with placeholder tokens',
-    '  --send-placeholders        Translate all strings including placeholders',
+    '  --send-placeholders        Translate all strings including masked placeholders',
+    '  --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)',
+    '  --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',
     '  --report-file <path>       Write post-translation report to file',
     '  --report-stdout            Print post-translation report to stdout',
@@ -96,9 +123,15 @@ function parseArgs(argv) {
     sourceLang: 'en',
     customRegex: [],
     noConfirm: false,
+    preservePlaceholders: false,
     skipPlaceholders: false,
     sendPlaceholders: false,
+    protectionFile: DEFAULT_PROTECTION_FILE,
+    protectionEnabled: true,
+    createProtectionFile: false,
     concurrency: 3,
+    batchSize: 50,
+    progressInterval: 10,
     dryRun: false,
     reportFile: null,
     reportStdout: false,
@@ -117,8 +150,11 @@ function parseArgs(argv) {
     const arg = argv[i];
     if (arg === '-h' || arg === '--help') { args.help = true; }
     else if (arg === '--no-confirm') { args.noConfirm = true; }
+    else if (arg === '--preserve-placeholders') { args.preservePlaceholders = true; }
     else if (arg === '--skip-placeholders') { args.skipPlaceholders = true; }
     else if (arg === '--send-placeholders') { args.sendPlaceholders = true; }
+    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 === '--report-stdout') { args.reportStdout = true; }
     else if (arg === '--bom') { args.bom = true; }
@@ -126,7 +162,10 @@ function parseArgs(argv) {
     else if (arg === '--output-dir' && i + 1 < argv.length) { args.outputDir = argv[++i]; }
     else if (arg === '--source-lang' && i + 1 < argv.length) { args.sourceLang = argv[++i]; }
     else if (arg === '--custom-regex' && i + 1 < argv.length) { args.customRegex.push(argv[++i]); }
+    else if (arg === '--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 === '--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]; }
     else if (arg === '--translate-fn' && i + 1 < argv.length) { args.translateFnPath = argv[++i]; }
     else if (arg === '--retry-count' && i + 1 < argv.length) { args.retryCount = parseInt(argv[++i], 10) || 3; }
@@ -140,14 +179,29 @@ function parseArgs(argv) {
   if (positional.length >= 1) args.sourceFile = positional[0];
   if (positional.length >= 2) args.targetLang = positional[1];
 
-  if (args.sendPlaceholders && args.skipPlaceholders) {
-    console.error('Error: --skip-placeholders and --send-placeholders are mutually exclusive.');
+  const placeholderModeCount = [
+    args.preservePlaceholders,
+    args.skipPlaceholders,
+    args.sendPlaceholders,
+  ].filter(Boolean).length;
+  if (placeholderModeCount > 1) {
+    console.error('Error: --preserve-placeholders, --skip-placeholders, and --send-placeholders are mutually exclusive.');
     process.exit(1);
   }
 
+  args.concurrency = clampInt(args.concurrency, 1, 25, 3);
+  args.batchSize = clampInt(args.batchSize, 1, 10000, 50);
+  args.progressInterval = clampInt(args.progressInterval, 1, 10000, 10);
+
   return args;
 }
 
+function clampInt(value, min, max, fallback) {
+  const num = parseInt(value, 10);
+  if (!Number.isInteger(num)) return fallback;
+  return Math.min(Math.max(num, min), max);
+}
+
 function loadCustomTranslateFn(modulePath) {
   if (!modulePath) return null;
   try {
@@ -167,11 +221,12 @@ function loadCustomTranslateFn(modulePath) {
 function resolveSourceFiles(sourceFile, sourceDir, filesPattern) {
   if (sourceDir) {
     const resolvedDir = path.resolve(process.cwd(), sourceDir);
-    if (!fs.existsSync(resolvedDir)) {
+    const sourceDirBase = path.dirname(resolvedDir);
+    if (!SecurityUtils.safeExistsSync(resolvedDir, sourceDirBase)) {
       console.error(`Error: Source directory "${resolvedDir}" does not exist.`);
       process.exit(1);
     }
-    const entries = fs.readdirSync(resolvedDir);
+    const entries = SecurityUtils.safeReaddirSync(resolvedDir, sourceDirBase);
     const pattern = filesPattern || '*.json';
     const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
     const files = entries.filter((f) => regex.test(f) && f.endsWith('.json')).sort();
@@ -184,7 +239,7 @@ function resolveSourceFiles(sourceFile, sourceDir, filesPattern) {
 
   if (sourceFile) {
     const resolved = path.resolve(process.cwd(), sourceFile);
-    if (!fs.existsSync(resolved)) {
+    if (!SecurityUtils.safeExistsSync(resolved, path.dirname(resolved))) {
       console.error(`Error: Source file "${resolved}" does not exist.`);
       process.exit(1);
     }
@@ -214,6 +269,9 @@ function classifyLeaves(leaves, customRegex) {
 async function resolvePlaceholderStrategy(args) {
   const interactive = isInteractive({ noPrompt: args.noConfirm });
 
+  if (args.preservePlaceholders) {
+    return { strategy: 'preserve', interactiveMode: false };
+  }
   if (args.sendPlaceholders) {
     return { strategy: 'send', interactiveMode: false };
   }
@@ -221,10 +279,10 @@ async function resolvePlaceholderStrategy(args) {
     return { strategy: 'skip', interactiveMode: false };
   }
   if (args.noConfirm) {
-    return { strategy: 'skip', interactiveMode: false };
+    return { strategy: 'preserve', interactiveMode: false };
   }
   if (!interactive) {
-    return { strategy: 'skip', interactiveMode: false };
+    return { strategy: 'preserve', interactiveMode: false };
   }
 
   const choice = await confirmGlobalChoice();
@@ -236,7 +294,7 @@ async function resolvePerKeyDecisions(withPlaceholders, interactive) {
 
   if (!interactive) {
     for (const leaf of withPlaceholders) {
-      decisions[leaf.keyPath] = 'skip';
+      decisions[leaf.keyPath] = 'preserve';
     }
     return decisions;
   }
@@ -251,6 +309,9 @@ async function resolvePerKeyDecisions(withPlaceholders, interactive) {
     if (choice === 'skip-all') {
       bulkDecision = 'skip';
       decisions[leaf.keyPath] = 'skip';
+    } else if (choice === 'preserve-all') {
+      bulkDecision = 'preserve';
+      decisions[leaf.keyPath] = 'preserve';
     } else if (choice === 'send-all') {
       bulkDecision = 'send';
       decisions[leaf.keyPath] = 'send';
@@ -267,18 +328,24 @@ function buildTranslateList(withPlaceholders, withoutPlaceholders, strategy, dec
   const toSkip = [];
 
   for (const leaf of withoutPlaceholders) {
-    toTranslate.push(leaf);
+    toTranslate.push({ ...leaf, placeholderMode: 'none' });
   }
 
-  if (strategy === 'send') {
+  if (strategy === 'preserve') {
     for (const leaf of withPlaceholders) {
-      toTranslate.push(leaf);
+      toTranslate.push({ ...leaf, placeholderMode: 'preserve' });
+    }
+  } else if (strategy === 'send') {
+    for (const leaf of withPlaceholders) {
+      toTranslate.push({ ...leaf, placeholderMode: 'mask' });
     }
   } else {
     for (const leaf of withPlaceholders) {
       const decision = decisions[leaf.keyPath] || 'skip';
-      if (decision === 'send') {
-        toTranslate.push(leaf);
+      if (decision === 'preserve') {
+        toTranslate.push({ ...leaf, placeholderMode: 'preserve' });
+      } else if (decision === 'send') {
+        toTranslate.push({ ...leaf, placeholderMode: 'mask' });
       } else {
         toSkip.push(leaf);
       }
@@ -288,32 +355,213 @@ function buildTranslateList(withPlaceholders, withoutPlaceholders, strategy, dec
   return { toTranslate, toSkip };
 }
 
-function maskAllForTranslation(toTranslate, customRegex) {
+function prepareDirectBatch(toTranslate, customRegex, protection) {
   return toTranslate.map((leaf) => {
-    const { masked, map } = maskPlaceholders(leaf.value, customRegex);
-    return { ...leaf, masked, placeholderMap: map, needsUnmask: map.size > 0 };
+    const protectedText = protectText(leaf.value, protection);
+    if (leaf.placeholderMode !== 'mask') {
+      return {
+        ...leaf,
+        masked: protectedText.value,
+        placeholderMap: new Map(),
+        protectionMap: protectedText.map,
+        needsUnmask: false,
+      };
+    }
+    const { masked, map } = maskPlaceholders(protectedText.value, customRegex);
+    return {
+      ...leaf,
+      masked,
+      placeholderMap: map,
+      protectionMap: protectedText.map,
+      needsUnmask: map.size > 0,
+    };
   });
 }
 
 async function runTranslation(maskedBatch, targetLang, options) {
   const batchItems = maskedBatch.map((item) => ({ value: item.masked, keyPath: item.keyPath }));
-  const results = await translateBatch(batchItems, targetLang, options);
+  const results = await translateBatchInChunks(batchItems, targetLang, options);
   return results;
 }
 
-function applyResults(sourceData, translatedResults, maskedBatch, toSkip, bom) {
-  const output = deepClone(sourceData);
+async function translateBatchInChunks(batch, targetLang, options) {
+  if (batch.length === 0) return [];
+
+  const batchSize = clampInt(options.batchSize, 1, 10000, 50);
+  const results = [];
+  const onProgress = options.onProgress;
+  let completed = 0;
+
+  for (let start = 0; start < batch.length; start += batchSize) {
+    const chunk = batch.slice(start, start + batchSize);
+    const chunkResults = await translateBatch(chunk, targetLang, {
+      ...options,
+      onProgress: (info) => {
+        completed++;
+        if (typeof onProgress === 'function') {
+          onProgress({
+            ...info,
+            completed,
+            total: batch.length,
+            chunkCompleted: info.completed,
+            chunkTotal: info.total,
+          });
+        }
+      },
+    });
+    results.push(...chunkResults);
+  }
+
+  return results;
+}
+
+function containsAllPlaceholders(value, placeholders) {
+  if (typeof value !== 'string') return false;
+  return (placeholders || []).every((placeholder) => value.includes(placeholder));
+}
+
+function createPlaceholderManifest(sourcePath, targetLang, leaves) {
+  const records = leaves
+    .filter((leaf) => Array.isArray(leaf.placeholders) && leaf.placeholders.length > 0)
+    .map((leaf) => ({
+      keyPath: leaf.keyPath,
+      placeholders: leaf.placeholders,
+    }));
+
+  if (records.length === 0) return null;
+
+  const safeName = path.basename(sourcePath).replace(/[^a-z0-9_.-]/gi, '_');
+  const manifestPath = path.join(os.tmpdir(), `i18ntk-placeholders-${process.pid}-${Date.now()}-${targetLang}-${safeName}.json`);
+  SecurityUtils.safeWriteFileSync(manifestPath, JSON.stringify({
+    version: 1,
+    sourceFile: sourcePath,
+    targetLang,
+    createdAt: new Date().toISOString(),
+    records,
+  }, null, 2), os.tmpdir(), 'utf8');
+  return manifestPath;
+}
+
+function cleanupPlaceholderManifest(manifestPath) {
+  if (!manifestPath) return;
+  try {
+    fs.unlinkSync(manifestPath);
+  } catch (_) {
+    // Best-effort cleanup only.
+  }
+}
+
+function makeTextJob(item, segment, segmentIndex, protection) {
+  const leading = segment.value.match(/^\s*/)[0];
+  const trailing = segment.value.match(/\s*$/)[0];
+  const core = segment.value.slice(leading.length, segment.value.length - trailing.length);
+  const protectedText = protectText(core, protection);
 
-  for (let i = 0; i < maskedBatch.length; i++) {
-    const item = maskedBatch[i];
-    const translated = translatedResults[i];
-    let finalValue;
-    if (item.needsUnmask) {
-      finalValue = unmaskPlaceholders(translated, item.placeholderMap);
+  return {
+    value: protectedText.value,
+    leading,
+    trailing,
+    protectionMap: protectedText.map,
+    keyPath: `${item.keyPath}#segment${segmentIndex}`,
+  };
+}
+
+async function translatePreservedItems(items, targetLang, options, customRegex, protection) {
+  const segmentJobs = [];
+  const plans = items.map((item) => {
+    const segments = splitByPlaceholders(item.value, customRegex);
+    const plan = { item, segments: [] };
+
+    segments.forEach((segment, index) => {
+      if (segment.type !== 'text' || !/[A-Za-z0-9]/.test(segment.value)) {
+        plan.segments.push({ type: segment.type, value: segment.value });
+        return;
+      }
+
+      const job = makeTextJob(item, segment, index, protection);
+      if (!job.value || !/[A-Za-z0-9]/.test(job.value)) {
+        plan.segments.push({ type: 'text', value: segment.value });
+        return;
+      }
+
+      const jobIndex = segmentJobs.length;
+      segmentJobs.push(job);
+      plan.segments.push({
+        type: 'translated-text',
+        jobIndex,
+        leading: job.leading,
+        trailing: job.trailing,
+        protectionMap: job.protectionMap,
+        fallback: segment.value,
+      });
+    });
+
+    return plan;
+  });
+
+  const translatedSegments = await translateBatchInChunks(segmentJobs, targetLang, options);
+
+  return plans.map((plan) => {
+    const value = plan.segments.map((segment) => {
+      if (segment.type === 'translated-text') {
+        const translated = translatedSegments[segment.jobIndex];
+        const restored = restoreText(translated || segment.fallback.trim(), segment.protectionMap);
+        return `${segment.leading}${restored}${segment.trailing}`;
+      }
+      return segment.value;
+    }).join('');
+
+    return containsAllPlaceholders(value, plan.item.placeholders) ? value : plan.item.value;
+  });
+}
+
+async function translateItems(toTranslate, targetLang, options, customRegex, protection) {
+  const finalResults = new Array(toTranslate.length);
+  const directItems = [];
+  const directIndexes = [];
+  const preserveItems = [];
+  const preserveIndexes = [];
+
+  toTranslate.forEach((item, index) => {
+    if (item.placeholderMode === 'preserve') {
+      preserveItems.push(item);
+      preserveIndexes.push(index);
     } else {
-      finalValue = translated;
+      directItems.push(item);
+      directIndexes.push(index);
+    }
+  });
+
+  const preparedDirect = prepareDirectBatch(directItems, customRegex, protection);
+  const directResults = await runTranslation(preparedDirect, targetLang, options);
+  for (let i = 0; i < preparedDirect.length; i++) {
+    const item = preparedDirect[i];
+    let finalValue = item.needsUnmask
+      ? unmaskPlaceholders(directResults[i], item.placeholderMap)
+      : directResults[i];
+    finalValue = restoreText(finalValue, item.protectionMap);
+
+    if (item.placeholderMode === 'mask' && !containsAllPlaceholders(finalValue, item.placeholders)) {
+      const fallback = await translatePreservedItems([item], targetLang, options, customRegex, protection);
+      finalValue = fallback[0];
     }
-    setLeaf(output, item.keyPath, finalValue);
+
+    finalResults[directIndexes[i]] = finalValue;
+  }
+
+  const preservedResults = await translatePreservedItems(preserveItems, targetLang, options, customRegex, protection);
+  for (let i = 0; i < preserveItems.length; i++) {
+    finalResults[preserveIndexes[i]] = preservedResults[i];
+  }
+
+  return finalResults;
+}
+
+function applyResults(sourceData, translatedResults, toTranslate, toSkip) {
+  const output = deepClone(sourceData);
+
+  for (let i = 0; i < toTranslate.length; i++) {
+    setLeaf(output, toTranslate[i].keyPath, translatedResults[i]);
   }
 
   for (const leaf of toSkip) {
@@ -324,15 +572,16 @@ function applyResults(sourceData, translatedResults, maskedBatch, toSkip, bom) {
 }
 
 function writeOutput(outputData, outputPath, bom) {
-  const dir = path.dirname(outputPath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+  const resolvedOutputPath = path.resolve(process.cwd(), outputPath);
+  const dir = path.dirname(resolvedOutputPath);
+  if (!SecurityUtils.safeExistsSync(dir, path.dirname(dir))) {
+    SecurityUtils.safeMkdirSync(dir, path.dirname(dir), { recursive: true });
   }
   let content = JSON.stringify(outputData, null, 2) + '\n';
   if (bom) {
     content = BOM + content;
   }
-  fs.writeFileSync(outputPath, content, 'utf-8');
+  SecurityUtils.safeWriteFileSync(resolvedOutputPath, content, dir, 'utf-8');
 }
 
 async function processFile(sourcePath, targetLang, args) {
@@ -342,7 +591,7 @@ async function processFile(sourcePath, targetLang, args) {
 
   let sourceData;
   try {
-    const raw = fs.readFileSync(sourcePath, 'utf-8');
+    const raw = SecurityUtils.safeReadFileSync(sourcePath, path.dirname(sourcePath), 'utf-8').replace(/^\uFEFF/, '');
     sourceData = JSON.parse(raw);
   } catch (e) {
     console.error(`Error reading "${sourcePath}": ${e.message}`);
@@ -356,49 +605,85 @@ async function processFile(sourcePath, targetLang, args) {
     return { total: 0, translated: 0, skipped: 0, skippedKeys: [] };
   }
 
-  const { withPlaceholders, withoutPlaceholders } = classifyLeaves(leaves, args.customRegex);
+  const protection = args.protection || loadProtectionConfig(args.protectionFile, {
+    enabled: args.protectionEnabled,
+    create: args.createProtectionFile,
+  });
+  const protectedLeaves = leaves
+    .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);
 
-  if (args.dryRun && withPlaceholders.length > 0) {
+  if (args.dryRun && strategy === 'skip' && withPlaceholders.length > 0) {
     await previewSkipped(withPlaceholders);
+    const skippedKeys = withPlaceholders.concat(protectedLeaves);
     return {
       total: leaves.length,
       translated: withoutPlaceholders.length,
-      skipped: withPlaceholders.length,
-      skippedKeys: withPlaceholders,
+      skipped: skippedKeys.length,
+      skippedKeys,
+      placeholderProtected: 0,
+      protectedSkipped: protectedLeaves.length,
       dryRun: true,
     };
   }
 
   if (args.dryRun) {
-    console.log(`[${fileName}] Dry-run: ${leaves.length} strings, all would be translated.`);
+    const protectedCount = strategy === 'send' ? 0 : withPlaceholders.length;
+    console.log(`[${fileName}] Dry-run: ${leaves.length} strings would be translated.`);
+    if (protectedLeaves.length > 0) {
+      console.log(`[${fileName}] Dry-run: ${protectedLeaves.length} protected keys/values would be copied unchanged.`);
+    }
+    if (hasProtectionRules(protection)) {
+      console.log(`[${fileName}] Dry-run: protected terms would be masked from ${protection.filePath}.`);
+    }
+    if (protectedCount > 0) {
+      console.log(`[${fileName}] Dry-run: ${protectedCount} placeholder strings would use preserve mode.`);
+    }
     return {
       total: leaves.length,
-      translated: leaves.length,
-      skipped: 0,
-      skippedKeys: [],
+      translated: leaves.length - protectedLeaves.length,
+      skipped: protectedLeaves.length,
+      skippedKeys: protectedLeaves,
+      placeholderProtected: protectedCount,
+      termProtected: hasProtectionRules(protection),
       dryRun: true,
     };
   }
 
-  const { strategy, interactiveMode } = await resolvePlaceholderStrategy(args);
   const decisions = await resolvePerKeyDecisions(withPlaceholders, interactiveMode);
   const { toTranslate, toSkip } = buildTranslateList(withPlaceholders, withoutPlaceholders, strategy, decisions);
+  toSkip.push(...protectedLeaves);
+  const placeholderProtected = toTranslate.filter((leaf) => leaf.placeholderMode === 'preserve').length;
+  const placeholderSkipped = toSkip.filter((leaf) => leaf.skipReason !== 'protected').length;
 
-  if (toSkip.length > 0) {
-    console.log(`[${fileName}] Skipping ${toSkip.length} keys with placeholders.`);
+  if (placeholderSkipped > 0) {
+    console.log(`[${fileName}] Skipping ${placeholderSkipped} keys with placeholders.`);
+  }
+  if (placeholderProtected > 0) {
+    console.log(`[${fileName}] Preserving placeholders for ${placeholderProtected} keys.`);
+  }
+  if (protectedLeaves.length > 0) {
+    console.log(`[${fileName}] Copying ${protectedLeaves.length} protected keys/values unchanged.`);
+  }
+  if (hasProtectionRules(protection)) {
+    console.log(`[${fileName}] Protecting terms from: ${protection.filePath}`);
   }
 
-  const maskedBatch = maskAllForTranslation(toTranslate, args.customRegex);
+  const manifestPath = createPlaceholderManifest(sourcePath, targetLang, toTranslate);
 
   const translateOptions = {
     sourceLang: args.sourceLang,
     concurrency: args.concurrency,
+    batchSize: args.batchSize,
     retryCount: args.retryCount,
     retryDelay: args.retryDelay,
     timeout: args.timeout,
     customFn: args.translateFn,
     onProgress: (info) => {
-      if (info.completed % 10 === 0 || info.completed === info.total) {
+      if (info.completed % args.progressInterval === 0 || info.completed === info.total) {
         process.stdout.write(`\r[${fileName}] Translating... ${info.completed}/${info.total}`);
       }
     },
@@ -408,14 +693,18 @@ async function processFile(sourcePath, targetLang, args) {
   };
 
   let translatedResults;
-  if (maskedBatch.length > 0) {
-    translatedResults = await runTranslation(maskedBatch, targetLang, translateOptions);
-    process.stdout.write('\n');
-  } else {
-    translatedResults = [];
+  try {
+    if (toTranslate.length > 0) {
+      translatedResults = await translateItems(toTranslate, targetLang, translateOptions, args.customRegex, protection);
+      process.stdout.write('\n');
+    } else {
+      translatedResults = [];
+    }
+  } finally {
+    cleanupPlaceholderManifest(manifestPath);
   }
 
-  const output = applyResults(sourceData, translatedResults, maskedBatch, toSkip, args.bom);
+  const output = applyResults(sourceData, translatedResults, toTranslate, toSkip);
   writeOutput(output, targetPath, args.bom);
 
   console.log(`[${fileName}] Written: ${targetPath}`);
@@ -425,39 +714,55 @@ async function processFile(sourcePath, targetLang, args) {
     translated: translatedResults.length,
     skipped: toSkip.length,
     skippedKeys: toSkip,
+    placeholderProtected,
+    protectedSkipped: protectedLeaves.length,
   };
 }
 
-async function main() {
-  const args = parseArgs(process.argv);
-
+async function run(args) {
   if (args.help) {
     printHelp();
-    process.exit(ExitCodes.SUCCESS);
+    return { success: true, exitCode: ExitCodes.SUCCESS };
   }
 
   if (args.unknown.length > 0) {
     console.error(`Unknown options: ${args.unknown.join(', ')}`);
     console.error('Use --help for usage information.');
-    process.exit(1);
+    return { success: false, exitCode: 1, error: 'Unknown options' };
   }
 
   if (!args.targetLang) {
     console.error('Error: Target language code is required.');
     console.error('Usage: i18ntk-translate <source-file> <target-lang> [options]');
-    process.exit(1);
+    return { success: false, exitCode: 1, error: 'Target language code is required' };
   }
 
   if (args.translateFnPath) {
     args.translateFn = loadCustomTranslateFn(args.translateFnPath);
   }
 
+  if (args.protectionEnabled !== false) {
+    if (args.createProtectionFile) {
+      const protectionPath = createProtectionFile(args.protectionFile);
+      console.log(`Protection file ready: ${protectionPath}`);
+    }
+    try {
+      args.protection = loadProtectionConfig(args.protectionFile, {
+        enabled: args.protectionEnabled,
+      });
+    } catch (error) {
+      return { success: false, exitCode: 1, error: error.message };
+    }
+  }
+
   const sourceFiles = resolveSourceFiles(args.sourceFile, args.sourceDir, args.filesPattern);
 
   const allSkippedKeys = [];
   let grandTotal = 0;
   let grandTranslated = 0;
   let grandSkipped = 0;
+  let grandPlaceholderProtected = 0;
+  let grandProtectedSkipped = 0;
 
   for (const srcPath of sourceFiles) {
     const result = await processFile(srcPath, args.targetLang, args);
@@ -465,6 +770,8 @@ async function main() {
       grandTotal += result.total;
       grandTranslated += result.translated;
       grandSkipped += result.skipped;
+      grandPlaceholderProtected += result.placeholderProtected || 0;
+      grandProtectedSkipped += result.protectedSkipped || 0;
       if (result.skippedKeys && result.skippedKeys.length > 0) {
         allSkippedKeys.push(...result.skippedKeys);
       }
@@ -472,13 +779,15 @@ async function main() {
   }
 
   console.log('');
-  console.log(formatSummaryLine(grandSkipped, grandTranslated, grandTotal));
+  console.log(formatSummaryLine(grandSkipped, grandTranslated, grandTotal, grandPlaceholderProtected, grandProtectedSkipped));
 
   if (allSkippedKeys.length > 0 || args.reportFile || args.reportStdout) {
     const report = generateReport(allSkippedKeys, grandTranslated, grandTotal, {
       sourceFile: sourceFiles.length === 1 ? sourceFiles[0] : `${sourceFiles.length} files`,
       targetLang: args.targetLang,
       dryRun: args.dryRun,
+      placeholderProtected: grandPlaceholderProtected,
+      protectedSkipped: grandProtectedSkipped,
     });
 
     if (args.reportStdout || (!args.reportFile && allSkippedKeys.length > 0)) {
@@ -493,10 +802,32 @@ async function main() {
     }
   }
 
-  process.exit(ExitCodes.SUCCESS);
+  return {
+    success: true,
+    exitCode: ExitCodes.SUCCESS,
+    total: grandTotal,
+    translated: grandTranslated,
+    skipped: grandSkipped,
+    placeholderProtected: grandPlaceholderProtected,
+    protectedSkipped: grandProtectedSkipped,
+  };
 }
 
-main().catch((err) => {
-  console.error('Fatal error:', err.message);
-  process.exit(1);
-});
+async function main() {
+  const result = await run(parseArgs(process.argv));
+  process.exit(result.exitCode || (result.success ? ExitCodes.SUCCESS : 1));
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('Fatal error:', err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  parseArgs,
+  resolveSourceFiles,
+  processFile,
+  run,
+};