i18ntk 3.2.0 → 4.0.0

package/main/i18ntk-sizing.js

@@ -82,9 +82,11 @@ class I18nSizingAnalyzer {
     this.format = options.format || 'table';
     this.outputReport = options.outputReport || false;
     this.sourceLanguage = options.sourceLanguage || config.sourceLanguage || 'en';
-    this.detailed = options.detailed || false;
-    this.detailedKeys = options.detailedKeys || false;
-    this.rl = null;
+    this.detailed = options.detailed || false;
+    this.detailedKeys = options.detailedKeys || false;
+    this.predictExpansion = options.predictExpansion || false;
+    this.rl = null;
+    this.expansionPredictions = null;
     
     // Initialize i18n with UI language from config
     const uiLanguage = options.uiLanguage || config.uiLanguage || 'en';
@@ -490,8 +492,13 @@ class I18nSizingAnalyzer {
     });
     this.generateFileComparison();
 
-    // Generate recommendations
-    this.generateRecommendations();
+    // Generate recommendations
+    this.generateRecommendations();
+
+    // Generate expansion predictions if requested
+    if (this.predictExpansion) {
+      this.generateExpansionPredictions();
+    }
   }
 
   generateFileComparison() {
@@ -557,6 +564,145 @@ class I18nSizingAnalyzer {
     this.stats.summary.recommendations = recommendations;
   }
 
+  // Language pair expansion reference table (average % expansion from English)
+  // Values represent typical character count ratio (target/source) minus 1, as percentage
+  getExpansionReference() {
+    return {
+      de: 35, es: 25, fr: 20, it: 15, pt: 20, nl: 30, sv: 15,
+      ru: 50, uk: 45, pl: 30, cs: 25, sk: 25, bg: 40, sr: 40,
+      ja: -40, zh: -45, ko: -35, th: -30, vi: -20, km: -5,
+      ar: 15, he: 10, fa: 20, tr: 10, fi: 25, hu: 20, el: 15,
+      da: 10, nb: 10, ro: 15, id: 5, ms: 5, hi: 15, bn: 20,
+      ta: 10, te: 15, mr: 20, gu: 20, ml: 25, kn: 15
+    };
+  }
+
+  classifyExpansionRisk(ratio) {
+    const absRatio = Math.abs(ratio);
+    if (absRatio < 30) return { tier: 'safe', label: 'Safe', color: 'green' };
+    if (absRatio < 50) return { tier: 'warning', label: 'Warning', color: 'yellow' };
+    return { tier: 'critical', label: 'Critical', color: 'red' };
+  }
+
+  generateExpansionPredictions() {
+    const languages = Object.keys(this.stats.languages);
+    if (languages.length < 2) return;
+
+    const baseLanguage = this.stats.summary.baseLanguage || this.config.sourceLanguage || 'en';
+    const expansionRef = this.getExpansionReference();
+    const predictions = {
+      baseLanguage,
+      perLanguage: {},
+      perKey: {},
+      topExpandedKeys: [],
+      summary: { safe: 0, warning: 0, critical: 0, total: 0 }
+    };
+
+    for (const lang of languages) {
+      if (lang === baseLanguage) continue;
+
+      const baseStats = this.stats.languages[baseLanguage];
+      const langStats = this.stats.languages[lang];
+      if (!baseStats || !langStats) continue;
+
+      const actualRatio = baseStats.totalCharacters > 0
+        ? ((langStats.totalCharacters - baseStats.totalCharacters) / baseStats.totalCharacters) * 100
+        : 0;
+
+      const referenceRatio = expansionRef[lang] || 10;
+      const risk = this.classifyExpansionRisk(actualRatio);
+      predictions.perLanguage[lang] = {
+        actualExpansionPercent: Math.round(actualRatio * 100) / 100,
+        referenceExpansionPercent: referenceRatio,
+        riskTier: risk.tier,
+        riskLabel: risk.label,
+        totalKeys: langStats.totalKeys,
+        totalChars: langStats.totalCharacters
+      };
+    }
+
+    const keyEntries = [];
+    for (const [key, langData] of Object.entries(this.stats.keys)) {
+      const baseData = langData[baseLanguage];
+      if (!baseData || baseData.length === 0) continue;
+
+      const keyPredictions = {};
+      for (const [lang, data] of Object.entries(langData)) {
+        if (lang === baseLanguage) continue;
+        const ratio = ((data.length - baseData.length) / baseData.length) * 100;
+        const risk = this.classifyExpansionRisk(ratio);
+        keyPredictions[lang] = {
+          sourceLength: baseData.length,
+          targetLength: data.length,
+          expansionPercent: Math.round(ratio * 100) / 100,
+          riskTier: risk.tier
+        };
+        predictions.summary[risk.tier]++;
+        predictions.summary.total++;
+      }
+
+      const maxExpansion = Math.max(...Object.values(keyPredictions).map(p => Math.abs(p.expansionPercent)));
+      keyEntries.push({ key, maxExpansion, predictions: keyPredictions });
+    }
+
+    keyEntries.sort((a, b) => b.maxExpansion - a.maxExpansion);
+    predictions.topExpandedKeys = keyEntries.slice(0, 30);
+    predictions.perKey = Object.fromEntries(keyEntries.slice(0, 200).map(e => [e.key, e.predictions]));
+
+    this.expansionPredictions = predictions;
+    this.stats.expansionPredictions = predictions;
+  }
+
+  displayExpansionPredictions() {
+    if (!this.expansionPredictions) return;
+
+    const p = this.expansionPredictions;
+    console.log('\n' + '='.repeat(60));
+    console.log('  EXPANSION PREDICTION ANALYSIS');
+    console.log('='.repeat(60));
+    console.log(`  Base Language: ${p.baseLanguage}`);
+    console.log(`  Total Key-Language Pairs Analyzed: ${p.summary.total}`);
+    console.log(`  Safe (<30%): ${p.summary.safe} | Warning (30-50%): ${p.summary.warning} | Critical (>50%): ${p.summary.critical}`);
+
+    console.log('\n  PER-LANGUAGE EXPANSION RATIOS:');
+    const langRows = Object.entries(p.perLanguage).map(([lang, data]) => ({
+      language: lang,
+      actual: `${data.actualExpansionPercent > 0 ? '+' : ''}${data.actualExpansionPercent}%`,
+      reference: `${data.referenceExpansionPercent > 0 ? '+' : ''}${data.referenceExpansionPercent}%`,
+      risk: data.riskLabel
+    }));
+    console.log(this.createTable([
+      { key: 'language', label: 'Language' },
+      { key: 'actual', label: 'Actual', align: 'right' },
+      { key: 'reference', label: 'Reference', align: 'right' },
+      { key: 'risk', label: 'Risk Tier' }
+    ], langRows));
+
+    if (p.topExpandedKeys.length > 0) {
+      console.log('\n  TOP EXPANDED KEYS (highest risk of UI overflow):');
+      const keyRows = p.topExpandedKeys.slice(0, 15).map(entry => {
+        const langs = Object.entries(entry.predictions).map(([l, d]) =>
+          `${l}:${d.expansionPercent > 0 ? '+' : ''}${d.expansionPercent}%`
+        ).join(' ');
+        return { key: entry.key, maxExp: `${entry.maxExpansion > 0 ? '+' : ''}${Math.round(entry.maxExpansion)}%`, languages: langs };
+      });
+      console.log(this.createTable([
+        { key: 'key', label: 'Key' },
+        { key: 'maxExp', label: 'Max Exp', align: 'right' },
+        { key: 'languages', label: 'Per-Language' }
+      ], keyRows));
+    }
+
+    console.log('\n  RECOMMENDATIONS:');
+    if (p.summary.critical > 0) {
+      console.log(`  - ${p.summary.critical} key-language pairs have >50% expansion — review UI layouts for truncation risk`);
+    }
+    if (p.summary.warning > 0) {
+      console.log(`  - ${p.summary.warning} key-language pairs have 30-50% expansion — test on target languages`);
+    }
+    console.log('  - Use the reference expansion ratios to plan UI element sizing for unsupported languages');
+  }
+
   // Display concise folder-level results
   displayFolderResults() {
     console.log("\n" + t("sizing.sizing_analysis_results"));
@@ -616,9 +762,13 @@ class I18nSizingAnalyzer {
       reportPath: this.outputDir
     }));
     
-    if (this.detailedKeys) {
-      this.displayDetailedKeys();
-    }
+    if (this.detailedKeys) {
+      this.displayDetailedKeys();
+    }
+
+    if (this.predictExpansion && this.expansionPredictions) {
+      this.displayExpansionPredictions();
+    }
   }
 
   displayFileComparison() {
@@ -874,17 +1024,50 @@ Generated: ${new Date().toISOString()}
         report += `
 ### ${key}
 `;
-        Object.entries(data).forEach(([lang, keyData]) => {
-          const length = keyData.length;
-          const isEmpty = length === 0;
-          const isLong = length > this.threshold;
-          const status = isEmpty ? 'EMPTY' : isLong ? 'LONG' : 'OK';
-          report += `- ${lang}: ${length} chars [${status}]\n`;
-        });
+        Object.entries(data).forEach(([lang, keyData]) => {
+          const length = keyData.length;
+          const isEmpty = length === 0;
+          const isLong = length > this.threshold;
+          const status = isEmpty ? 'EMPTY' : isLong ? 'LONG' : 'OK';
+          report += `- ${lang}: ${length} chars [${status}]\n`;
+        });
+      });
+    }
+
+    // Expansion predictions
+    if (this.expansionPredictions) {
+      const ep = this.expansionPredictions;
+      report += `
+## Expansion Prediction Analysis
+
+### Summary
+- Base Language: ${ep.baseLanguage}
+- Safe (<30%): ${ep.summary.safe}
+- Warning (30-50%): ${ep.summary.warning}
+- Critical (>50%): ${ep.summary.critical}
+- Total Pairs: ${ep.summary.total}
+
+### Per-Language Ratios
+`;
+      Object.entries(ep.perLanguage).forEach(([lang, data]) => {
+        report += `- ${lang}: ${data.actualExpansionPercent > 0 ? '+' : ''}${data.actualExpansionPercent}% (ref: ${data.referenceExpansionPercent > 0 ? '+' : ''}${data.referenceExpansionPercent}%) [${data.riskLabel}]\n`;
       });
+
+      if (ep.topExpandedKeys.length > 0) {
+        report += `
+### Top Expanded Keys
+`;
+        ep.topExpandedKeys.slice(0, 30).forEach((entry, idx) => {
+          report += `${idx + 1}. ${entry.key} (max: ${entry.maxExpansion > 0 ? '+' : ''}${Math.round(entry.maxExpansion)}%)\n`;
+          Object.entries(entry.predictions).forEach(([l, d]) => {
+            report += `   ${l}: ${d.sourceLength} → ${d.targetLength} chars (${d.expansionPercent > 0 ? '+' : ''}${d.expansionPercent}%) [${d.riskTier}]\n`;
+          });
+          report += '\n';
+        });
+      }
     }
 
-    return report;
+    return report;
   }
 
   // Generate CSV report
@@ -1018,6 +1201,8 @@ Generated: ${new Date().toISOString()}
           options.d = options.detailed;
         } else if (key === 'detailed-keys') {
           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;
         }
@@ -1073,17 +1258,24 @@ Generated: ${new Date().toISOString()}
             options.detailed = true;
             options.d = true;
           }
-        } else if (key === 'detailed-keys') {
-          if (nextArg && !nextArg.startsWith('-') && ['true', 'false'].includes(nextArg.toLowerCase())) {
-            options['detailed-keys'] = nextArg.toLowerCase() !== 'false';
-            i++;
-          } else {
-            options['detailed-keys'] = true;
-          }
-        } else if (key === 'output-dir') {
-          options['output-dir'] = nextArg || options['output-dir'];
-          if (nextArg && !nextArg.startsWith('-')) i++;
-        }
+        } else if (key === 'detailed-keys') {
+          if (nextArg && !nextArg.startsWith('-') && ['true', 'false'].includes(nextArg.toLowerCase())) {
+            options['detailed-keys'] = nextArg.toLowerCase() !== 'false';
+            i++;
+          } else {
+            options['detailed-keys'] = true;
+          }
+        } else if (key === 'predict-expansion') {
+          if (nextArg && !nextArg.startsWith('-') && ['true', 'false'].includes(nextArg.toLowerCase())) {
+            options['predict-expansion'] = nextArg.toLowerCase() !== 'false';
+            i++;
+          } else {
+            options['predict-expansion'] = true;
+          }
+        } else if (key === 'output-dir') {
+          options['output-dir'] = nextArg || options['output-dir'];
+          if (nextArg && !nextArg.startsWith('-')) i++;
+        }
       }
     }
     
@@ -1102,6 +1294,7 @@ Options:
   --source-language <code>    Source language baseline for comparisons (default: en)
   -d, --detailed              Generate detailed report with more information
   --detailed-keys             Show detailed key-level analysis
+  --predict-expansion         Predict UI layout expansion risk per language
   --output-dir <dir>          Output directory for reports (default: ./i18ntk-reports)
   --help                  Show this help message
 `);
@@ -1124,8 +1317,9 @@ Options:
     this.languages = args.languages ? args.languages.split(',').map(l => l.trim()) : [];
     this.outputReport = args['output-report'] !== undefined ? args['output-report'] : false;
     this.format = args.format || 'table';
-    this.detailed = args.detailed;
-    this.detailedKeys = args['detailed-keys'];
+    this.detailed = args.detailed;
+    this.detailedKeys = args['detailed-keys'];
+    this.predictExpansion = args['predict-expansion'] || false;
     this.sourceLanguage = args['source-language'] || config.sourceLanguage || this.sourceLanguage || 'en';
 
     if (!fromMenu) {

package/main/i18ntk-translate.js

@@ -15,6 +15,7 @@
  * Options:
  *   --source-dir <dir>         Source directory (default: ./locales/en)
  *   --output-dir <dir>         Output directory (default: ./locales/<lang>)
+ *   --provider <name>          Translation provider: google, deepl, libretranslate
  *   --custom-regex <regex>     Additional placeholder regex pattern
  *   --no-confirm               Skip all confirmation dialogs
  *   --preserve-placeholders    Translate text around placeholders and reinsert tokens
@@ -90,6 +91,7 @@ function printHelp() {
     'Options:',
     '  --source-dir <dir>         Source directory containing locale files',
     '  --output-dir <dir>         Output directory for translated files',
+    '  --provider <name>          Provider: google (default), deepl, libretranslate',
     '  --source-lang <code>       Source language code (default: en)',
     '  --custom-regex <regex>     Additional placeholder regex pattern',
     '  --no-confirm               Automate: skip confirmation dialogs',
@@ -110,6 +112,15 @@ function printHelp() {
     '  --retry-count <n>          Max retries per failed request (default: 3)',
     '  --retry-delay <ms>         Base backoff delay in ms (default: 1000)',
     '  --timeout <ms>             HTTP request timeout in ms (default: 15000)',
+    '',
+    'Environment:',
+    '  I18NTK_TRANSLATE_PROVIDER  Default provider when --provider is omitted',
+    '  DEEPL_API_KEY              Required for --provider deepl',
+    '  DEEPL_API_URL              Optional, defaults to https://api-free.deepl.com/v2/translate',
+    '  I18NTK_ALLOW_CUSTOM_TRANSLATE_HOSTS=1  Allow custom DeepL-compatible HTTPS hosts',
+    '  LIBRETRANSLATE_URL         Optional, defaults to https://libretranslate.com/translate',
+    '  LIBRETRANSLATE_API_KEY     Optional API key for LibreTranslate servers that require one',
+    '  I18NTK_ALLOW_PRIVATE_TRANSLATE_URLS=1  Allow localhost/private provider URLs for trusted testing',
     '  -h, --help                 Show this help',
   ].join('\n'));
 }
@@ -121,6 +132,7 @@ function parseArgs(argv) {
     sourceDir: null,
     outputDir: null,
     sourceLang: 'en',
+    provider: process.env.I18NTK_TRANSLATE_PROVIDER || 'google',
     customRegex: [],
     noConfirm: false,
     preservePlaceholders: false,
@@ -161,6 +173,7 @@ function parseArgs(argv) {
     else if (arg === '--source-dir' && i + 1 < argv.length) { args.sourceDir = argv[++i]; }
     else if (arg === '--output-dir' && i + 1 < argv.length) { args.outputDir = argv[++i]; }
     else if (arg === '--source-lang' && i + 1 < argv.length) { args.sourceLang = argv[++i]; }
+    else if (arg === '--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; }
@@ -206,7 +219,17 @@ function loadCustomTranslateFn(modulePath) {
   if (!modulePath) return null;
   try {
     const resolved = path.isAbsolute(modulePath) ? modulePath : path.resolve(process.cwd(), modulePath);
-    const mod = require(resolved);
+    const validated = SecurityUtils.validatePath(resolved);
+    if (!validated) {
+      SecurityUtils.logSecurityEvent('Blocked unsafe custom translate module path', 'warn', {
+        modulePath,
+        resolved,
+        source: 'user'
+      });
+      console.error(`Error: Custom translate module path "${modulePath}" failed security validation.`);
+      process.exit(1);
+    }
+    const mod = require(validated);
     if (typeof mod === 'function') return mod;
     if (mod && typeof mod.translate === 'function') return mod.translate;
     if (mod && typeof mod.default === 'function') return mod.default;
@@ -676,6 +699,7 @@ async function processFile(sourcePath, targetLang, args) {
 
   const translateOptions = {
     sourceLang: args.sourceLang,
+    provider: args.provider,
     concurrency: args.concurrency,
     batchSize: args.batchSize,
     retryCount: args.retryCount,

package/main/i18ntk-usage.js

@@ -84,6 +84,11 @@ class I18nUsageAnalyzer {
     this.startTime = Date.now(); // Track performance metrics
     this.version = '1.10.1'; // Version tracking
     
+    // Dead key detection properties
+    this.deadKeys = new Map();
+    this.cleanupMode = false;
+    this.dryRunDelete = false;
+    
     // Use global translation function
     this.rl = null;
   }
@@ -187,7 +192,9 @@ class I18nUsageAnalyzer {
       help: a.help || a.h,
       noPrompt: a.noPrompt ?? a['no-prompt'],
       strict: a.strict,
-      debug: a.debug
+      debug: a.debug,
+      cleanup: a.cleanup ?? a['cleanup'],
+      dryRunDelete: a.dryRunDelete ?? a['dry-run-delete']
     };
   }
 
@@ -376,6 +383,13 @@ class I18nUsageAnalyzer {
       console.log('🔍 Debug mode enabled');
     }
     
+    if (args.cleanup) {
+      this.cleanupMode = true;
+    }
+    if (args.dryRunDelete) {
+      this.dryRunDelete = true;
+    }
+    
     try {
       // Ensure config is always initialized
       if (!this.config) {
@@ -599,6 +613,33 @@ class I18nUsageAnalyzer {
         }));
       }
       
+      if (this.cleanupMode) {
+        const deadKeys = this.findDeadKeys();
+        console.log('\n' + t('usage.deadKeysDetectionTitle'));
+        console.log(t('usage.deadKeysCount', { count: deadKeys.length }));
+        
+        const highConfidence = deadKeys.filter(dk => dk.confidence >= 0.8).length;
+        const mediumConfidence = deadKeys.filter(dk => dk.confidence >= 0.4 && dk.confidence < 0.8).length;
+        const lowConfidence = deadKeys.filter(dk => dk.confidence < 0.4).length;
+        
+        console.log(t('usage.deadKeysConfidenceBreakdown', { high: highConfidence, medium: mediumConfidence, low: lowConfidence }));
+        
+        if (deadKeys.length > 0) {
+          console.log('\n' + t('usage.deadKeysSample'));
+          deadKeys.slice(0, 10).forEach(dk => {
+            console.log(`  ${dk.key} [${(dk.confidence * 100).toFixed(0)}%] - ${dk.reason}`);
+          });
+          if (deadKeys.length > 10) {
+            console.log(t('usage.deadKeysMore', { count: deadKeys.length - 10 }));
+          }
+        }
+        
+        if (this.dryRunDelete) {
+          const reportPath = this.saveDeadKeysReport(deadKeys, args.outputDir || this.config.outputDir || './i18ntk-reports/usage');
+          console.log(t('usage.deadKeysReportSaved', { path: reportPath }));
+        }
+      }
+      
       if (args.outputReport) {
         const report = this.generateUsageReport();
         await this.saveReport(report, args.outputDir);
@@ -625,7 +666,7 @@ class I18nUsageAnalyzer {
   // Show help message
   showHelp() {
     console.log(`
-📊 i18ntk usage - Translation key usage analysis (v1.8.3)
+📊 i18ntk usage - Translation key usage analysis (v1.10.1)
 
 Usage:
   node i18ntk-usage.js [options]
@@ -642,14 +683,17 @@ Options:
   --validate-placeholders Enable placeholder key validation
   --framework-detect     Enable framework-specific pattern detection
   --performance-mode     Enable performance metrics tracking
+  --cleanup              Enable dead key detection for cleanup mode
+  --dry-run-delete       Save dead keys report without deleting (requires --cleanup)
   --help, -h             Show this help message
 
 Examples:
   node i18ntk-usage.js --source-dir=./src --i18n-dir=./translations --output-report
   npm run i18ntk:usage -- --strict --debug --validate-placeholders
   node i18ntk-usage.js --no-prompt --performance-mode --output-dir=./reports
+  node i18ntk-usage.js --cleanup --dry-run-delete
 
-Analysis Features (v1.8.3):
+Analysis Features (v1.10.1):
   • Detects unused translation keys
   • Identifies missing translation keys
   • Shows translation completeness by language
@@ -662,6 +706,7 @@ Analysis Features (v1.8.3):
   • Key complexity analysis
   • Security-enhanced path validation
   • Detailed reporting with validation errors
+  • Dead key detection with confidence scoring
 `);
   }
 
@@ -1133,6 +1178,161 @@ Analysis Features (v1.8.3):
     return missing;
   }
 
+  findDeadKeys() {
+    const unusedKeys = this.findUnusedKeys();
+    const deadKeys = [];
+
+    for (const key of unusedKeys) {
+      let confidence = 0.9;
+      let reason = 'Key not found in any source file';
+
+      if (this._matchesDynamicPattern(key)) {
+        confidence = 0.3;
+        reason = 'Key matches dynamic template pattern (likely used)';
+      } else if (this._keyInSourceComments(key)) {
+        confidence = 0.5;
+        reason = 'Key referenced in comments/JSDoc';
+      } else if (this._parentFileRecentlyModified(key)) {
+        confidence = 0.4;
+        reason = 'Translation file modified within last 30 days';
+      }
+
+      deadKeys.push({ key, confidence, reason });
+    }
+
+    deadKeys.sort((a, b) => b.confidence - a.confidence);
+    return deadKeys;
+  }
+
+  _matchesDynamicPattern(key) {
+    const keyParts = key.split('.');
+    if (keyParts.length < 2) return false;
+
+    const dynamicPatterns = [
+      /t\(`[^`]*\$\{[^}]*\}[^`]*`\)/g,
+      /i18n\.t\(`[^`]*\$\{[^}]*\}[^`]*`\)/g,
+      /useTranslation\(\)\.t\(`[^`]*\$\{[^}]*\}[^`]*`\)/g
+    ];
+
+    try {
+      const sourceFiles = Array.from(this.fileUsage.keys());
+      for (const filePath of sourceFiles) {
+        const fullPath = path.join(this.sourceDir, filePath);
+        if (!SecurityUtils.safeExistsSync(fullPath, this.sourceDir)) continue;
+
+        const content = SecurityUtils.safeReadFileSync(fullPath, this.sourceDir, 'utf8');
+        if (!content) continue;
+
+        for (const pattern of dynamicPatterns) {
+          const matches = content.match(pattern);
+          if (matches) {
+            for (const match of matches) {
+              const matchLower = match.toLowerCase();
+              if (keyParts.some(part => matchLower.includes(part.toLowerCase()))) {
+                return true;
+              }
+            }
+          }
+        }
+      }
+    } catch (e) {
+      // Silently fail - dynamic pattern detection is best-effort
+    }
+
+    return false;
+  }
+
+  _keyInSourceComments(key) {
+    const commentPatterns = [
+      /\/\/[^\n]*/g,
+      /\/\*[\s\S]*?\*\//g,
+      /\/\*\*[\s\S]*?\*\//g
+    ];
+
+    try {
+      const sourceFiles = Array.from(this.fileUsage.keys());
+      for (const filePath of sourceFiles) {
+        const fullPath = path.join(this.sourceDir, filePath);
+        if (!SecurityUtils.safeExistsSync(fullPath, this.sourceDir)) continue;
+
+        const content = SecurityUtils.safeReadFileSync(fullPath, this.sourceDir, 'utf8');
+        if (!content) continue;
+
+        for (const pattern of commentPatterns) {
+          const comments = content.match(pattern);
+          if (comments) {
+            for (const comment of comments) {
+              if (comment.includes(key)) {
+                return true;
+              }
+            }
+          }
+        }
+      }
+    } catch (e) {
+      // Silently fail - comment detection is best-effort
+    }
+
+    return false;
+  }
+
+  _parentFileRecentlyModified(key) {
+    const thirtyDaysMs = 30 * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+
+    try {
+      for (const [filePath] of this.translationFiles) {
+        if (!SecurityUtils.safeExistsSync(filePath, this.i18nDir)) continue;
+
+        const content = SecurityUtils.safeReadFileSync(filePath, this.i18nDir, 'utf8');
+        if (!content) continue;
+
+        if (content.includes(key)) {
+          const stats = SecurityUtils.safeStatSync(filePath, this.i18nDir);
+          if (stats && stats.mtime) {
+            const mtimeMs = new Date(stats.mtime).getTime();
+            if ((now - mtimeMs) <= thirtyDaysMs) {
+              return true;
+            }
+          }
+        }
+      }
+    } catch (e) {
+      // Silently fail - file stat is best-effort
+    }
+
+    return false;
+  }
+
+  generateDeadKeysReport(deadKeys) {
+    const allCleanupReady = deadKeys.length === 0 || deadKeys.every(dk => dk.confidence >= 0.8);
+
+    return {
+      deadKeys,
+      totalAvailableKeys: this.availableKeys.size,
+      totalUsedKeys: this.usedKeys.size,
+      deadKeyCount: deadKeys.length,
+      cleanupReady: allCleanupReady,
+      generatedAt: new Date().toISOString(),
+      version: this.version
+    };
+  }
+
+  saveDeadKeysReport(deadKeys, outputDir) {
+    const report = this.generateDeadKeysReport(deadKeys);
+    const resolvedDir = path.resolve(outputDir || './i18ntk-reports/usage');
+
+    if (!SecurityUtils.safeExistsSync(resolvedDir, process.cwd())) {
+      SecurityUtils.safeMkdirSync(resolvedDir, process.cwd(), { recursive: true });
+    }
+
+    const filename = '.dead-keys.json';
+    const filepath = path.join(resolvedDir, filename);
+
+    SecurityUtils.safeWriteFileSync(filepath, JSON.stringify(report, null, 2), resolvedDir, 'utf8');
+    return filepath;
+  }
+
   // Find files that use specific keys
   findKeyUsage(searchKey) {
     const usage = [];