i18ntk 2.0.3 → 2.1.0

package/README.md

@@ -1,44 +1,59 @@
-# i18ntk v2.0.3
+# i18ntk v2.1.0
 
-<div align="center">
+Zero-dependency i18n toolkit for initialization, scanning, analysis, validation, usage tracking, and translation completion.
 
 ![i18ntk Logo](docs/screenshots/i18ntk-logo-public.PNG)
 
-[![npm version](https://img.shields.io/npm/v/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)
+[![npm version](https://img.shields.io/npm/v/i18ntk.svg?color=brightgreen)](https://www.npmjs.com/package/i18ntk)
 [![npm downloads](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)
 [![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)
 [![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)
 [![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
-[![socket](https://socket.dev/api/badge/npm/package/i18ntk/2.0.3)](https://socket.dev/npm/package/i18ntk/overview/2.0.0)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/2.1.0)](https://socket.dev/npm/package/i18ntk/overview/2.1.0)
 
-Zero-dependency i18n toolkit for initialization, scanning, analysis, validation, and completion workflows.
+## Why i18ntk
 
-</div>
+- Zero runtime dependencies
+- Works across JS/TS, React, Vue, Angular, and generic projects
+- Supports non-interactive CI runs (`--no-prompt`)
+- Includes usage/coverage validation and missing-key completion
+- Ships with runtime translation helpers via `i18ntk/runtime`
 
 ## Install
 
 ```bash
+# global (recommended for CLI use)
 npm install -g i18ntk
+
+# local
+npm install --save-dev i18ntk
+
+# one-off
+npx i18ntk --help
 ```
 
 ## Quick Start
 
 ```bash
-# interactive menu
-i18ntk
-
-# direct workflow
+# initialize locales/project settings
 i18ntk --command=init
-i18ntk --command=analyze --no-prompt
-i18ntk --command=validate --no-prompt
-i18ntk --command=complete --no-prompt
+
+# analyze translation completeness
+i18ntk --command=analyze
+
+# validate translation structure/content
+i18ntk --command=validate
+
+# complete missing keys
+i18ntk --command=complete
 ```
 
-## v2 Command Model
+## Command Model (v2)
 
-Primary CLI commands:
+Primary CLI:
 
 ```bash
+i18ntk
 i18ntk --command=init
 i18ntk --command=analyze
 i18ntk --command=validate
@@ -50,7 +65,7 @@ i18ntk --command=summary
 i18ntk --command=debug
 ```
 
-Standalone binaries:
+Standalone executables:
 
 ```bash
 i18ntk-init
@@ -66,19 +81,8 @@ i18ntk-fixer
 i18ntk-backup
 ```
 
-Backup helper:
-
-```bash
-i18ntk-backup --help
-i18ntk-backup create ./locales
-i18ntk-backup list
-i18ntk-backup restore <backup-file>
-```
-
 ## Common Flags
 
-Most commands support:
-
 - `--source-dir <path>`
 - `--i18n-dir <path>`
 - `--output-dir <path>`
@@ -90,13 +94,13 @@ Most commands support:
 
 ## Configuration
 
-i18ntk reads project settings from `.i18ntk-config` in the project root.
+i18ntk reads project settings from `.i18ntk-config` in your project root.
 
 Example:
 
 ```json
 {
-  "version": "2.0.0",
+  "version": "2.1.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -125,7 +129,7 @@ setLanguage('fr');
 console.log(getLanguage());
 ```
 
-## Docs
+## Documentation
 
 - [Documentation Index](docs/README.md)
 - [API Reference](docs/api/API_REFERENCE.md)
@@ -133,9 +137,9 @@ console.log(getLanguage());
 - [Runtime API Guide](docs/runtime.md)
 - [Scanner Guide](docs/scanner-guide.md)
 - [Environment Variables](docs/environment-variables.md)
-- [Migration Guide v2.0.0](docs/migration-guide-v2.0.0.md)
+- [Migration Guide v2.1.0](docs/migration-guide-v2.1.0.md)
 - [Release Runbook](DEVUPDATE.md)
 
 ## License
 
-MIT
+MIT

package/main/i18ntk-analyze.js

@@ -142,22 +142,44 @@ class I18nAnalyzer {
     }
   }
 
-  // Get all available languages
-  getAvailableLanguages() {
-    try {
-      const items = SecurityUtils.safeReaddirSync(this.sourceDir, process.cwd(), { withFileTypes: true });
-      if (!items) {
-        console.error('Error reading source directory: Unable to access directory');
+  // Get all available languages
+  isValidLanguageCode(code) {
+    if (!code || typeof code !== 'string') return false;
+    return /^[a-z]{2}(?:-[A-Za-z0-9]{2,8})*$/i.test(code.trim());
+  }
+
+  isExcludedLanguageDirectory(name) {
+    if (!name || typeof name !== 'string') return true;
+    const lowered = name.toLowerCase();
+    return lowered.startsWith('backup-') || lowered === 'backup' || lowered === 'reports' || lowered === 'i18ntk-reports';
+  }
+
+  getAvailableLanguages() {
+    try {
+      const items = SecurityUtils.safeReaddirSync(this.sourceDir, process.cwd(), { withFileTypes: true });
+      if (!items) {
+        console.error('Error reading source directory: Unable to access directory');
         return [];
       }
       
       const languages = [];
       
       // Check for directory-based structure
-      const directories = items
-        .filter(item => item.isDirectory())
-        .map(item => item.name)
-        .filter(name => name !== 'node_modules' && !name.startsWith('.') && name !== this.config.sourceLanguage);
+      const directories = items
+        .filter(item => item.isDirectory())
+        .map(item => item.name)
+        .filter(name =>
+          name !== 'node_modules' &&
+          !name.startsWith('.') &&
+          name !== this.config.sourceLanguage &&
+          !this.isExcludedLanguageDirectory(name) &&
+          this.isValidLanguageCode(name)
+        )
+        .filter(name => {
+          const dirPath = path.join(this.sourceDir, name);
+          const dirItems = SecurityUtils.safeReaddirSync(dirPath, process.cwd(), { withFileTypes: true }) || [];
+          return dirItems.some(item => item.isFile() && item.name.endsWith('.json'));
+        });
       
       // Check for monolith files (language.json files)
       const files = items
@@ -168,34 +190,17 @@ class I18nAnalyzer {
       languages.push(...directories);
       
       // Add monolith files as languages (without .json extension)
-      const monolithLanguages = files
-        .map(file => file.replace('.json', ''))
-        .filter(lang => !languages.includes(lang) && lang !== this.config.sourceLanguage);
-      languages.push(...monolithLanguages);
-      
-      // Check for nested structures
-      for (const dir of directories) {
-        const dirPath = path.join(this.sourceDir, dir);
-        try {
-          const dirItems = SecurityUtils.safeReaddirSync(dirPath, process.cwd(), { withFileTypes: true });
-          if (dirItems) {
-            const jsonFiles = dirItems
-              .filter(item => item.isFile() && item.name.endsWith('.json'))
-              .map(item => item.name.replace('.json', ''));
-            
-            // If directory contains JSON files, it's likely a language directory
-            if (jsonFiles.length > 0) {
-              if (!languages.includes(dir)) {
-                languages.push(dir);
-              }
-            }
-          }
-        } catch (error) {
-          // Skip directories we can't read
-        }
-      }
-      
-      return [...new Set(languages)].sort();
+      const monolithLanguages = files
+        .map(file => file.replace('.json', ''))
+        .filter(lang =>
+          !languages.includes(lang) &&
+          lang !== this.config.sourceLanguage &&
+          !this.isExcludedLanguageDirectory(lang) &&
+          this.isValidLanguageCode(lang)
+        );
+      languages.push(...monolithLanguages);
+
+      return [...new Set(languages)].sort();
     } catch (error) {
       console.error('Error reading source directory:', error.message);
       return [];
@@ -707,8 +712,7 @@ try {
         throw new Error(t('analyze.failedToWriteReportFile') || 'Failed to write report file securely');
       }
       
-      console.log(`Report saved to: ${reportPath}`);
-      return reportPath;
+      return reportPath;
       
     } catch (error) {
       console.error(`Failed to save report for ${language}:`, error.message);
@@ -775,20 +779,21 @@ try {
           console.log(t('analyze.analyzing', { language }) || `\n🔄 Analyzing ${language}...`);
         }
         
-        const analysis = this.analyzeLanguage(language);
-        const report = this.generateLanguageReport(analysis);
-        
-        // Save report
-        const reportPath = await this.saveReport(language, report);
-        
-        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}`);
-        }
+          const analysis = this.analyzeLanguage(language);
+          const report = this.generateLanguageReport(analysis);
+
+          // Save report
+          const reportPath = await this.saveReport(language, report);
+          const processedCount = results.length + 1;
+
+          if (!args.json) {
+            console.log(t('analyze.completed', { language }) || `✅ Analysis completed for ${language}`);
+            console.log(t('analyze.progress', {
+              translated: processedCount,
+              total: languages.length
+            }) || `   Progress: ${processedCount}/${languages.length} languages processed`);
+            console.log(t('analyze.reportSaved', { reportPath }) || `   Report saved: ${reportPath}`);
+          }
         
         results.push({
           language,

package/main/i18ntk-ui.js

@@ -11,13 +11,13 @@ const legacyConfigManager = require('../utils/config-manager');
 const { getIcon, isUnicodeSupported } = require('../utils/terminal-icons');
 const configManager = new SettingsManager();
 
-class UIi18n {
-    constructor() {
-        this.currentLanguage = 'en';
-this.translations = {};
-        this.uiLocalesDir = path.resolve(__dirname, '..', 'resources', 'i18n', 'ui-locales');
-        this.availableLanguages = [];
-        this.configFile = path.resolve(configManager.configFile);
+class UIi18n {
+    constructor() {
+        this.currentLanguage = 'en';
+this.translations = {};
+        this.uiLocalesDir = this.resolveUiLocalesDir();
+        this.availableLanguages = [];
+        this.configFile = path.resolve(configManager.configFile);
         
 
         // Initialize with safe defaults
@@ -25,13 +25,13 @@ this.translations = {};
     }
     
 
-    initialize() {
-        try {
-            const config = configManager.loadSettings ? configManager.loadSettings() : configManager.getConfig ? configManager.getConfig() : {};
-            
-            // Use safe defaults if config is not available
-            this.uiLocalesDir = path.resolve(__dirname, '..', 'resources', 'i18n', 'ui-locales');
-            this.availableLanguages = this.detectAvailableLanguages();
+    initialize() {
+        try {
+            const config = configManager.loadSettings ? configManager.loadSettings() : configManager.getConfig ? configManager.getConfig() : {};
+            
+            // Use safe defaults if config is not available
+            this.uiLocalesDir = this.resolveUiLocalesDir();
+            this.availableLanguages = this.detectAvailableLanguages();
             
 
             const configuredLanguage = config?.language || config?.uiLanguage || 'en';
@@ -42,25 +42,71 @@ this.translations = {};
             } else {
                 this.loadLanguage('en');
             }
-        } catch (error) {
-            console.warn('UIi18n: Failed to initialize with config, using defaults:', error.message);
-            this.uiLocalesDir = path.resolve(__dirname, '..', 'resources', 'i18n', 'ui-locales');
-            this.availableLanguages = this.detectAvailableLanguages();
-            this.loadLanguage('en');
-        }
-    }
+        } catch (error) {
+            console.warn('UIi18n: Failed to initialize with config, using defaults:', error.message);
+            this.uiLocalesDir = this.resolveUiLocalesDir();
+            this.availableLanguages = this.detectAvailableLanguages();
+            this.loadLanguage('en');
+        }
+    }
+
+    getValidationBase(targetPath) {
+        const fallbackBase = path.resolve(__dirname, '..');
+        if (!targetPath || typeof targetPath !== 'string') {
+            return fallbackBase;
+        }
+
+        let current = path.resolve(path.dirname(targetPath));
+        while (true) {
+            try {
+                if (fs.statSync(current).isDirectory()) {
+                    return current;
+                }
+            } catch (_) {
+                // Continue walking up until an existing directory is found.
+            }
+
+            const parent = path.dirname(current);
+            if (parent === current) {
+                break;
+            }
+            current = parent;
+        }
+
+        return fallbackBase;
+    }
+
+    resolveUiLocalesDir() {
+        const candidates = [
+            path.resolve(__dirname, '..', 'ui-locales'),
+            path.resolve(__dirname, '..', 'resources', 'i18n', 'ui-locales')
+        ];
+
+        for (const candidate of candidates) {
+            try {
+                const stats = SecurityUtils.safeStatSync(candidate, this.getValidationBase(candidate));
+                if (stats && stats.isDirectory()) {
+                    return candidate;
+                }
+            } catch (_) {
+                // Try next candidate.
+            }
+        }
+
+        return candidates[0];
+    }
     /**
     /**
      * Detect which UI locales are currently installed
      * @returns {string[]} Array of available language codes
      */
-    detectAvailableLanguages() {
-        const all = ['en', 'de', 'es', 'fr', 'ru', 'ja', 'zh'];
-        return all.filter(lang => {
-            const filePath = path.join(this.uiLocalesDir, `${lang}.json`);
-            return SecurityUtils.safeExistsSync(filePath);
-        });
-    }
+    detectAvailableLanguages() {
+        const all = ['en', 'de', 'es', 'fr', 'ru', 'ja', 'zh'];
+        return all.filter(lang => {
+            const filePath = path.join(this.uiLocalesDir, `${lang}.json`);
+            return SecurityUtils.safeExistsSync(filePath, this.getValidationBase(filePath));
+        });
+    }
 
     /**
      * Refresh the list of available languages and ensure current language is valid
@@ -91,13 +137,13 @@ this.translations = {};
         }
         
         try {
-            // Primary: Use monolith JSON file (en.json, de.json, etc.)
-            const monolithTranslationFile = path.join(this.uiLocalesDir, `${language}.json`);
-            
-            if (SecurityUtils.safeExistsSync(monolithTranslationFile)) {
-                try {
-                    const content = SecurityUtils.safeReadFileSync(monolithTranslationFile, path.dirname(monolithTranslationFile), 'utf8');
-                    const fullTranslations = JSON.parse(content);
+            // Primary: Use monolith JSON file (en.json, de.json, etc.)
+            const monolithTranslationFile = path.join(this.uiLocalesDir, `${language}.json`);
+            
+            if (SecurityUtils.safeExistsSync(monolithTranslationFile, this.getValidationBase(monolithTranslationFile))) {
+                try {
+                    const content = SecurityUtils.safeReadFileSync(monolithTranslationFile, path.dirname(monolithTranslationFile), 'utf8');
+                    const fullTranslations = JSON.parse(content);
                     
                     // Flatten the nested structure for easier key access
                     this.translations = this.flattenTranslations(fullTranslations);
@@ -111,13 +157,14 @@ this.translations = {};
                     this.translations = {};
                 }
             } else {
-                // Fallback: Use folder-based structure if monolith file doesn't exist
-                const langDir = path.join(this.uiLocalesDir, language);
-                
-                if (SecurityUtils.safeExistsSync(langDir) && fs.statSync(langDir).isDirectory()) {
-                    const files = fs.readdirSync(langDir).filter(file => file.endsWith('.json'));
-                    if (debugEnabled) {
-                        console.log(`UI: Found files in ${langDir}: ${files.join(', ')}`);
+                // Fallback: Use folder-based structure if monolith file doesn't exist
+                const langDir = path.join(this.uiLocalesDir, language);
+                
+                const langDirStats = SecurityUtils.safeStatSync(langDir, this.getValidationBase(langDir));
+                if (langDirStats && langDirStats.isDirectory()) {
+                    const files = fs.readdirSync(langDir).filter(file => file.endsWith('.json'));
+                    if (debugEnabled) {
+                        console.log(`UI: Found files in ${langDir}: ${files.join(', ')}`);
                     }
     
                     for (const file of files) {
@@ -381,12 +428,12 @@ this.translations = {};
      * @param {object} replacements - Object with replacement values
      * @returns {string|null} English translation or null if not found
      */
-    getEnglishFallback(keyPath, replacements = {}) {
-        try {
-            const englishFile = path.join(this.uiLocalesDir, 'en.json');
-            if (SecurityUtils.safeExistsSync(englishFile)) {
-                const englishContent = SecurityUtils.safeReadFileSync(englishFile, path.dirname(englishFile), 'utf8');
-                const englishTranslations = JSON.parse(englishContent);
+    getEnglishFallback(keyPath, replacements = {}) {
+        try {
+            const englishFile = path.join(this.uiLocalesDir, 'en.json');
+            if (SecurityUtils.safeExistsSync(englishFile, this.getValidationBase(englishFile))) {
+                const englishContent = SecurityUtils.safeReadFileSync(englishFile, path.dirname(englishFile), 'utf8');
+                const englishTranslations = JSON.parse(englishContent);
                 
                 // Use the same flattening approach for consistency
                 const flattenedEnglish = this.flattenTranslations(englishTranslations);
@@ -523,4 +570,4 @@ this.translations = {};
 }
 
 // Export the class, not a singleton instance
-module.exports = UIi18n;
+module.exports = UIi18n;

package/main/manage/commands/AnalyzeCommand.js

@@ -149,22 +149,44 @@ class AnalyzeCommand {
         }
     }
 
-    // Get all available languages
-    getAvailableLanguages() {
-        try {
-            const items = SecurityUtils.safeReaddirSync(this.sourceDir, process.cwd(), { withFileTypes: true });
-            if (!items) {
-                console.error('Error reading source directory: Unable to access directory');
+    // Get all available languages
+    isValidLanguageCode(code) {
+        if (!code || typeof code !== 'string') return false;
+        return /^[a-z]{2}(?:-[A-Za-z0-9]{2,8})*$/i.test(code.trim());
+    }
+
+    isExcludedLanguageDirectory(name) {
+        if (!name || typeof name !== 'string') return true;
+        const lowered = name.toLowerCase();
+        return lowered.startsWith('backup-') || lowered === 'backup' || lowered === 'reports' || lowered === 'i18ntk-reports';
+    }
+
+    getAvailableLanguages() {
+        try {
+            const items = SecurityUtils.safeReaddirSync(this.sourceDir, process.cwd(), { withFileTypes: true });
+            if (!items) {
+                console.error('Error reading source directory: Unable to access directory');
                 return [];
             }
 
             const languages = [];
 
             // Check for directory-based structure
-            const directories = items
-                .filter(item => item.isDirectory())
-                .map(item => item.name)
-                .filter(name => name !== 'node_modules' && !name.startsWith('.') && name !== this.config.sourceLanguage);
+            const directories = items
+                .filter(item => item.isDirectory())
+                .map(item => item.name)
+                .filter(name =>
+                    name !== 'node_modules' &&
+                    !name.startsWith('.') &&
+                    name !== this.config.sourceLanguage &&
+                    !this.isExcludedLanguageDirectory(name) &&
+                    this.isValidLanguageCode(name)
+                )
+                .filter(name => {
+                    const dirPath = path.join(this.sourceDir, name);
+                    const dirItems = SecurityUtils.safeReaddirSync(dirPath, process.cwd(), { withFileTypes: true }) || [];
+                    return dirItems.some(item => item.isFile() && item.name.endsWith('.json'));
+                });
 
             // Check for monolith files (language.json files)
             const files = items
@@ -175,34 +197,17 @@ class AnalyzeCommand {
             languages.push(...directories);
 
             // Add monolith files as languages (without .json extension)
-            const monolithLanguages = files
-                .map(file => file.replace('.json', ''))
-                .filter(lang => !languages.includes(lang) && lang !== this.config.sourceLanguage);
-            languages.push(...monolithLanguages);
-
-            // Check for nested structures
-            for (const dir of directories) {
-                const dirPath = path.join(this.sourceDir, dir);
-                try {
-                    const dirItems = SecurityUtils.safeReaddirSync(dirPath, process.cwd(), { withFileTypes: true });
-                    if (dirItems) {
-                        const jsonFiles = dirItems
-                            .filter(item => item.isFile() && item.name.endsWith('.json'))
-                            .map(item => item.name.replace('.json', ''));
-
-                        // If directory contains JSON files, it's likely a language directory
-                        if (jsonFiles.length > 0) {
-                            if (!languages.includes(dir)) {
-                                languages.push(dir);
-                            }
-                        }
-                    }
-                } catch (error) {
-                    // Skip directories we can't read
-                }
-            }
-
-            return [...new Set(languages)].sort();
+            const monolithLanguages = files
+                .map(file => file.replace('.json', ''))
+                .filter(lang =>
+                    !languages.includes(lang) &&
+                    lang !== this.config.sourceLanguage &&
+                    !this.isExcludedLanguageDirectory(lang) &&
+                    this.isValidLanguageCode(lang)
+                );
+            languages.push(...monolithLanguages);
+
+            return [...new Set(languages)].sort();
         } catch (error) {
             console.error('Error reading source directory:', error.message);
             return [];
@@ -714,8 +719,7 @@ class AnalyzeCommand {
                 throw new Error(t('analyze.failedToWriteReportFile') || 'Failed to write report file securely');
             }
 
-            console.log(`Report saved to: ${reportPath}`);
-            return reportPath;
+            return reportPath;
 
         } catch (error) {
             console.error(`Failed to save report for ${language}:`, error.message);
@@ -782,20 +786,21 @@ class AnalyzeCommand {
                     console.log(t('analyze.analyzing', { language }) || `\n🔄 Analyzing ${language}...`);
                 }
 
-                const analysis = this.analyzeLanguage(language);
-                const report = this.generateLanguageReport(analysis);
-
-                // Save report
-                const reportPath = await this.saveReport(language, report);
-
-                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}`);
-                }
+                const analysis = this.analyzeLanguage(language);
+                const report = this.generateLanguageReport(analysis);
+
+                // Save report
+                const reportPath = await this.saveReport(language, report);
+                const processedCount = results.length + 1;
+
+                if (!args.json) {
+                    console.log(t('analyze.completed', { language }) || `✅ Analysis completed for ${language}`);
+                    console.log(t('analyze.progress', {
+                        translated: processedCount,
+                        total: languages.length
+                    }) || `   Progress: ${processedCount}/${languages.length} languages processed`);
+                    console.log(t('analyze.reportSaved', { reportPath }) || `   Report saved: ${reportPath}`);
+                }
 
                 results.push({
                     language,