i18ntk 1.8.0 → 1.8.1

package/README.md

@@ -2,17 +2,25 @@
 
 ![i18ntk Logo](docs/screenshots/i18ntk-logo-public.PNG)
 
-**Version:** 1.8.0
+**Version:** 1.8.1
 **Last Updated:** 2025-08-11  
 **GitHub Repository:** [vladnoskv/i18ntk](https://github.com/vladnoskv/i18ntk)
 
-[![npm](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk) [![npm version](https://badge.fury.io/js/i18ntk.svg)](https://badge.fury.io/js/i18ntk) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/) [![Downloads](https://img.shields.io/npm/dm/i18ntk.svg)](https://www.npmjs.com/package/i18ntk) [![Socket Badge](https://socket.dev/api/badge/npm/package/i18ntk/1.8.0)](https://socket.dev/npm/package/i18ntk/overview/1.8.0) [![GitHub stars](https://img.shields.io/github/stars/vladnoskv/i18ntk?style=social)](https://github.com/vladnoskv/i18ntk)
+[![npm](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk) [![npm version](https://badge.fury.io/js/i18ntk.svg)](https://badge.fury.io/js/i18ntk) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/) [![Downloads](https://img.shields.io/npm/dm/i18ntk.svg)](https://www.npmjs.com/package/i18ntk) [![GitHub stars](https://img.shields.io/github/stars/vladnoskv/i18ntk?style=social)](https://github.com/vladnoskv/i18ntk) [![Socket Badge](https://socket.dev/api/badge/npm/package/i18ntk/1.8.1)](https://socket.dev/npm/package/i18ntk/overview/1.8.1)
 
 **🚀 The fastest way to manage translations across any framework or vanilla JavaScript projects**
 
 **Framework Support:** Auto-detects popular libraries (React i18next, Vue i18n, i18next, Nuxt i18n, Svelte i18n) or works without a framework. i18ntk manages translation files and validation—it does NOT implement translation logic like i18next or Vue i18n.
 
-> **v1.8.0** – **SAFER WORKFLOW** - Autorun workflow removed for enhanced safety. Enhanced Interactive Translation Fixer Tool with improved automatic detection, selective language/file fixing, mass fix capabilities, and 7-language UI support; enhanced security logging, flexible 4-6 digit PIN authentication, configuration stability improvements, and CI/CD silent mode support; maintains 97% speed improvement.
+
+With over **2,000 downloads**, we thank you for your patience. I am proud to release version **1.8.1** with **1.8.0** marking our first fully stable release. Expect fewer updates as the core toolkit has matured. Future efforts may explore optional translation runtime features and a companion web UI for AI-assisted translations while keeping this package dependency-free.
+
+> **v1.8.1** – A major release delivering:
+> - 🔍 **Smarter Framework Detection**: Automatically identifies and configures for popular i18n frameworks
+> - 🔌 **Extensible Plugin System**: Powerful architecture for custom extractors and formats
+> - 🔒 **Enhanced Security**: Advanced protection with PIN authentication and AES encryption
+> - ⚡  **Performance Boost**: Up to 97% faster processing with optimized algorithms
+> - 🌐 **Multi-Framework Support**: Seamless integration with React, Vue, Svelte, and more
 
 ## 🚀 Quick Start
 
@@ -27,6 +35,12 @@ npx i18ntk
 i18ntk analyze --source ./src
 i18ntk complete --source ./src
 i18ntk validate --source ./locales
+
+# Framework detection
+i18ntk analyze --detect-framework
+
+# JSON output for CI/CD
+i18ntk validate --format json
 ```
 
 ---
@@ -56,6 +70,58 @@ i18ntk validate --source ./locales
 - **Framework‑agnostic:** Works with React, Vue, Svelte, Nuxt, i18next, or plain JSON.
 - **Scale:** Linear scaling up to 5M keys/second with ultra‑extreme settings.
 - **Script-by-Script Safety:** Manual execution ensures proper setup before each operation.
+- **Framework fingerprints:** Auto-detects i18next, Lingui, and FormatJS projects to apply sensible defaults.
+- **Plugin architecture:** Optional extractor and format adapters enable AST parsing or YAML/ICU support without extra deps.
+
+## 🎯 Features
+
+### 🔍 **Smart Analysis**
+- **Multi-format Support**: JSON, YAML, and JavaScript translation files
+- **Key Usage Tracking**: Identify unused and missing translation keys
+- **Placeholder Validation**: Ensure consistent placeholder usage
+- **Cross-reference Checking**: Verify translation completeness across languages
+
+### 🎯 **Enhanced Framework Detection (NEW in 1.8.1)**
+- **Smart Framework Detection**: Automatically detects i18next, Lingui, and FormatJS
+- **Package.json Analysis**: Quick detection via dependency analysis
+- **Framework-specific Rules**: Tailored validation for each framework
+- **Enhanced Doctor Tool**: Framework-aware analysis and recommendations
+
+### 🔌 **Plugin System (NEW in 1.8.1)**
+- **Plugin Loader Architecture**: Extensible plugin system with PluginLoader and FormatManager
+- **Custom Extractors**: Support for custom translation extractors
+- **Format Managers**: Unified handling of different translation formats
+- **Easy Extension**: Simple API for adding new plugins and formats
+
+### ⚡ **Performance Optimized**
+- **Ultra-fast Processing**: Handle 200,000+ translation keys in milliseconds
+- **87% Performance Boost**: Extreme mode achieves 38.90ms for 200k keys
+- **Memory Efficient**: <1MB memory usage for any operation
+- **Caching System**: Intelligent caching for repeated operations
+- **Streaming Processing**: Handle large files without memory issues
+- **No Child Processes**: Removed child_process usage for better performance
+
+### 🔒 **Security First (Enhanced in 1.8.1)**
+- **Admin PIN Protection**: Secure sensitive operations with PIN authentication
+- **Command-line PIN**: Support for `--admin-pin` argument in non-interactive mode
+- **Standardized Exit Codes**: Consistent exit codes across all CLI commands
+- **Path Validation**: Prevent directory traversal attacks
+- **Input Sanitization**: Enhanced input validation and sanitization
+- **Security Feature Tests**: Comprehensive security testing suite
+
+### 🌍 **Multi-language Support**
+- **7 Languages**: English, Spanish, French, German, Japanese, Russian, Chinese
+- **UI Localization**: Full interface localization
+- **Context-aware**: Smart language detection and switching
+- **RTL Support**: Right-to-left language support
+
+### 🛠️ **Developer Tools**
+- **Interactive CLI**: Beautiful, user-friendly command-line interface
+- **Auto-completion**: Smart suggestions for commands and keys
+- **Progress Tracking**: Real-time progress bars for long operations
+- **Export Tools**: Generate reports in multiple formats
+- **JSON Output**: Machine-readable JSON output for CI/CD integration
+- **Config Directory**: Support for `--config-dir` standalone configurations
 
 ---
 
@@ -116,6 +182,17 @@ i18ntk validate --source ./locales
 
 ---
 
+## Exit Codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | Success |
+| 1 | Handled configuration error |
+| 2 | Validation failed |
+| 3 | Security violation |
+
+---
+
 ## 🔒 Safer Workflow (NEW in v1.8.0)
 
 **Enhanced security through manual script execution:**
@@ -166,6 +243,16 @@ Create `settings/i18ntk-config.json` (auto‑generated by `init`):
 }
 ```
 
+Define per-language placeholder patterns with `placeholderStyles` to ensure placeholder parity across translations:
+
+```json
+"placeholderStyles": {
+  "en": ["\\{\\{[^}]+\\}\\}"],
+  "de": ["%s"],
+  "fr": ["{\\d+}"]
+}
+```
+
 ### Environment Variables
 
 You can override paths with environment variables:
@@ -294,7 +381,16 @@ your-project/
 - Locale files are **auto‑backed up** before optimization.
 - Prefer the **interactive optimizer** for safe locale management.
 - Versions **prior to 1.7.1** are deprecated.
-- Upgrades apply improvements automatically; no migration steps required for 1.7.5.
+- Upgrades apply improvements automatically; no migration steps required for 1.8.1.
+
+---
+
+## 🧭 Future Plans
+
+- Investigate adding optional translation runtime logic to make i18ntk an all-in-one solution for any framework.
+- Explore a lightweight web-based companion for AI-assisted translations with a clean UI.
+- Maintain a zero-dependency core package while keeping future extensions optional.
+- Fewer, stability-focused releases as we refine long-term direction.
 
 ---
 

package/main/i18ntk-analyze.js

@@ -16,6 +16,7 @@ const { getUnifiedConfig, parseCommonArgs, displayHelp } = require('../utils/con
 const SecurityUtils = require('../utils/security');
 const AdminCLI = require('../utils/admin-cli');
 const watchLocales = require('../utils/watch-locales');
+const JsonOutput = require('../utils/json-output');
 
 const PROJECT_ROOT = process.cwd();
 
@@ -100,6 +101,14 @@ class I18nAnalyzer {
             parsed.disableAdmin = true;
           } else if (sanitizedKey === 'admin-status') {
             parsed.adminStatus = true;
+          } else if (sanitizedKey === 'json') {
+            parsed.json = true;
+          } else if (sanitizedKey === 'sort-keys') {
+            parsed.sortKeys = true;
+          } else if (sanitizedKey === 'indent') {
+            parsed.indent = parseInt(value) || 2;
+          } else if (sanitizedKey === 'newline') {
+            parsed.newline = value || 'lf';
           }
         }
       });
@@ -500,12 +509,16 @@ try {
   // Main analyze method
   async analyze() {
     try {
-      const results = []; // Add this line to declare the results array
-      
-      console.log(t('analyze.starting') || '🔍 Starting translation analysis...');
-      console.log(t('analyze.sourceDirectoryLabel', { sourceDir: path.resolve(this.sourceDir) }));
-      console.log(t('analyze.sourceLanguageLabel', { sourceLanguage: this.config.sourceLanguage }));
-      console.log(t('analyze.strictModeLabel', { mode: this.config.processing?.strictMode || this.config.strictMode ? 'ON' : 'OFF' }));
+      const results = [];
+      const args = this.parseArgs();
+      const jsonOutput = new JsonOutput('analyze');
+
+      if (!args.json) {
+        console.log(t('analyze.starting') || '🔍 Starting translation analysis...');
+        console.log(t('analyze.sourceDirectoryLabel', { sourceDir: path.resolve(this.sourceDir) }));
+        console.log(t('analyze.sourceLanguageLabel', { sourceLanguage: this.config.sourceLanguage }));
+        console.log(t('analyze.strictModeLabel', { mode: this.config.processing?.strictMode || this.config.strictMode ? 'ON' : 'OFF' }));
+      }
       
       // Ensure output directory exists
       if (!fs.existsSync(this.outputDir)) {
@@ -515,14 +528,28 @@ try {
       const languages = this.getAvailableLanguages();
       
       if (languages.length === 0) {
-        console.log(t('analyze.noLanguages') || '⚠️  No target languages found.');
+        const error = t('analyze.noLanguages') || '⚠️  No target languages found.';
+        if (args.json) {
+          jsonOutput.setStatus('error', error);
+          console.log(JSON.stringify(jsonOutput.getOutput(), null, args.indent || 2));
+          return;
+        }
+        console.log(error);
         return;
       }
       
-      console.log(t('analyze.foundLanguages', { count: languages.length, languages: languages.join(', ') }) || `📋 Found ${languages.length} languages to analyze: ${languages.join(', ')}`);
+      if (!args.json) {
+        console.log(t('analyze.foundLanguages', { count: languages.length, languages: languages.join(', ') }) || `📋 Found ${languages.length} languages to analyze: ${languages.join(', ')}`);
+      }
+      
+      let totalMissing = 0;
+      let totalExtra = 0;
+      let totalFiles = 0;
       
       for (const language of languages) {
-        console.log(t('analyze.analyzing', { language }) || `\n🔄 Analyzing ${language}...`);
+        if (!args.json) {
+          console.log(t('analyze.analyzing', { language }) || `\n🔄 Analyzing ${language}...`);
+        }
         
         const analysis = this.analyzeLanguage(language);
         const report = this.generateLanguageReport(analysis);
@@ -530,18 +557,54 @@ try {
         // Save report
         const reportPath = await this.saveReport(language, report);
         
-        console.log(t('analyze.completed', { language }) || `✅ Analysis completed for ${language}`);
-        console.log(t('analyze.progress', { 
-          translated: results.length, 
-          total: languages.length 
-        }) || `   Progress: ${results.length}/${languages.length} languages processed`);
-        console.log(t('analyze.reportSaved', { reportPath }) || `   Report saved: ${reportPath}`);
+        if (!args.json) {
+          console.log(t('analyze.completed', { language }) || `✅ Analysis completed for ${language}`);
+          console.log(t('analyze.progress', { 
+            translated: results.length, 
+            total: languages.length 
+          }) || `   Progress: ${results.length}/${languages.length} languages processed`);
+          console.log(t('analyze.reportSaved', { reportPath }) || `   Report saved: ${reportPath}`);
+        }
         
         results.push({
           language,
           analysis,
           reportPath
         });
+        
+        // Add issues to JSON output
+        Object.values(analysis.files).forEach(fileData => {
+          if (fileData.structural) {
+            fileData.structural.missingKeys?.forEach(key => {
+              jsonOutput.addIssue('missing', key, language);
+              totalMissing++;
+            });
+            fileData.structural.extraKeys?.forEach(key => {
+              jsonOutput.addIssue('extra', key, language);
+              totalExtra++;
+            });
+          }
+        });
+        totalFiles += analysis.summary.analyzedFiles;
+      }
+      
+      // Set JSON output
+      jsonOutput.setStats({
+        missing: totalMissing,
+        extra: totalExtra,
+        files: totalFiles,
+        languages: languages.length
+      });
+      
+      if (totalMissing > 0 || totalExtra > 0) {
+        jsonOutput.setStatus('warn');
+      } else {
+        jsonOutput.setStatus('ok');
+      }
+      
+      if (args.json) {
+        console.log(JSON.stringify(jsonOutput.getOutput(), null, args.indent || 2));
+        return results;
       }
       
       // Summary

package/main/i18ntk-complete.js

@@ -13,7 +13,6 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
 const SecurityUtils = require('../utils/security');
 const { getUnifiedConfig, parseCommonArgs, displayHelp } = require('../utils/config-helper');
 const { loadTranslations, t } = require('../utils/i18n-helper');

package/main/i18ntk-doctor.js

@@ -1,19 +1,153 @@
 #!/usr/bin/env node
 const fs = require('fs');
-const { getUnifiedConfig } = require('../utils/config-helper');
+const path = require('path');
+const { getUnifiedConfig, parseCommonArgs, displayHelp } = require('../utils/config-helper');
+
+const ExitCodes = require('../utils/exit-codes');
+
+function hasBOM(content) {
+  return content.charCodeAt(0) === 0xFEFF;
+}
+
+function collectPluralKeys(obj, prefix = '', set = new Set()) {
+  for (const [key, value] of Object.entries(obj || {})) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const pluralForms = ['zero', 'one', 'two', 'few', 'many', 'other'];
+      const keys = Object.keys(value);
+      if (keys.some(k => pluralForms.includes(k))) {
+        set.add(fullKey);
+      }
+      collectPluralKeys(value, fullKey, set);
+    }
+  }
+  return set;
+}
+
+function compareTypes(src, tgt, prefix = '', issues = []) {
+  for (const key of Object.keys(src)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (!(key in tgt)) continue;
+    const sVal = src[key];
+    const tVal = tgt[key];
+    if (sVal && typeof sVal === 'object' && !Array.isArray(sVal) && tVal && typeof tVal === 'object' && !Array.isArray(tVal)) {
+      compareTypes(sVal, tVal, fullKey, issues);
+    } else if (typeof sVal !== typeof tVal) {
+      issues.push(fullKey);
+    }
+  }
+  return issues;
+}
 
 (async () => {
-  const config = await getUnifiedConfig('doctor');
+  const args = parseCommonArgs(process.argv.slice(2));
+  if (args.help) {
+    displayHelp('i18ntk-doctor');
+    process.exit(0);
+  }
+  const config = await getUnifiedConfig('doctor', args);
   const dirs = {
     projectRoot: config.projectRoot,
     sourceDir: config.sourceDir,
     i18nDir: config.i18nDir,
     outputDir: config.outputDir,
   };
+  
+  let exitCode = ExitCodes.SUCCESS;
+  const issues = [];
 
   console.log('i18ntk doctor');
   for (const [name, dir] of Object.entries(dirs)) {
+    const rel = path.relative(config.projectRoot, dir);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      issues.push(`path traversal detected: ${dir}`);
+      exitCode = Math.max(exitCode, ExitCodes.SECURITY_VIOLATION);
+      continue;
+    }
     const exists = fs.existsSync(dir);
     console.log(`${name}: ${dir} ${exists ? '✅' : '❌'}`);
+    if (!exists) {
+      if (name !== 'outputDir') {
+        issues.push(`Missing directory: ${dir}`);
+        exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+      }
+      continue;
+    }
+    try {
+      fs.accessSync(dir, fs.constants.R_OK | fs.constants.W_OK);
+    } catch (e) {
+      issues.push(`Permission issue: ${dir}`);
+      exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+    }
+  }
+
+  const pkgVersion = require('../package.json').version;
+  if (config.version && config.version !== pkgVersion) {
+    issues.push(`Config version mismatch: ${config.version} != ${pkgVersion}`);
+    exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+  }
+
+  const sourceLang = config.sourceLanguage || 'en';
+  const languages = config.defaultLanguages || [];
+  const srcDir = path.join(config.i18nDir, sourceLang);
+  const srcFiles = fs.existsSync(srcDir) ? fs.readdirSync(srcDir).filter(f => f.endsWith('.json')) : [];
+
+  for (const lang of languages) {
+    const langDir = path.join(config.i18nDir, lang);
+    if (!fs.existsSync(langDir)) {
+      issues.push(`Missing locale directory: ${lang}`);
+      exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+      continue;
+    }
+    const files = fs.readdirSync(langDir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+      if (!srcFiles.includes(file)) {
+        issues.push(`Dangling namespace file: ${lang}/${file}`);
+        exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+      }
+      const srcPath = path.join(srcDir, file);
+      const tgtPath = path.join(langDir, file);
+      if (!fs.existsSync(srcPath) || !fs.existsSync(tgtPath)) continue;
+      const srcContent = fs.readFileSync(srcPath, 'utf8');
+      const tgtContent = fs.readFileSync(tgtPath, 'utf8');
+      if (hasBOM(srcContent) || hasBOM(tgtContent)) {
+        issues.push(`BOM detected in ${lang}/${file}`);
+        exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+      }
+      let srcJson, tgtJson;
+      try {
+        srcJson = JSON.parse(srcContent.replace(/^\uFEFF/, ''));
+      } catch (e) {
+        issues.push(`Invalid JSON in source ${file}: ${e.message}`);
+        exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+        continue;
+      }
+      try {
+        tgtJson = JSON.parse(tgtContent.replace(/^\uFEFF/, ''));
+      } catch (e) {
+        issues.push(`Invalid JSON in ${lang}/${file}: ${e.message}`);
+        exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+        continue;
+      }
+      const srcPlurals = collectPluralKeys(srcJson);
+      const tgtPlurals = collectPluralKeys(tgtJson);
+      for (const key of srcPlurals) {
+        if (!tgtPlurals.has(key)) {
+          issues.push(`Inconsistent plural forms in ${lang}/${file}: missing ${key}`);
+          exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+        }
+      }
+      const typeMismatches = compareTypes(srcJson, tgtJson);
+      typeMismatches.forEach(k => {
+        issues.push(`Type mismatch for key ${k} in ${lang}/${file}`);
+        exitCode = Math.max(exitCode, ExitCodes.CONFIG_ERROR);
+      });
+    }
+  }
+
+  if (issues.length > 0) {
+    console.log('\nIssues found:');
+    issues.forEach(i => console.log(` - ${i}`));
   }
-})();
+  process.exit(exitCode);
+})();

package/main/i18ntk-fixer.js

@@ -631,6 +631,10 @@ class I18nFixer {
     } finally {
       // Ensure readline is properly closed to prevent hanging
       closeGlobalReadline();
+      // Ensure process exits cleanly
+      if (require.main === module) {
+        process.exit(0);
+      }
     }
   }
 }