i18ntk 2.1.0 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
-# i18ntk v2.1.0
+# i18ntk v2.3.0
 
-Zero-dependency i18n toolkit for initialization, scanning, analysis, validation, usage tracking, and translation completion.
+Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, and translation completion.
 
 ![i18ntk Logo](docs/screenshots/i18ntk-logo-public.PNG)
 
@@ -9,52 +9,76 @@ Zero-dependency i18n toolkit for initialization, scanning, analysis, validation,
 [![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.1.0)](https://socket.dev/npm/package/i18ntk/overview/2.1.0)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/2.3.0)](https://socket.dev/npm/package/i18ntk/overview/2.3.0)
 
-## Why i18ntk
+## Upgrade Notice
+
+Versions earlier than `2.3.0` may contain known stability and security issues.
+They are considered unsupported for production use. Upgrade to `2.3.0` or newer.
+
+## What i18ntk Does
 
 - 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`
+- Interactive and non-interactive project setup
+- Translation completeness analysis and usage tracking
+- Validation, sizing, and summary reporting
+- Missing-key completion and fixer workflows
+- Runtime translation helpers for application code
+- Support for JS/TS, React, Vue, Angular, and generic projects
+
+## Getting Started
+
+1. Install the package.
+2. Run `i18ntk` or `i18ntk --command=init` to initialize the project.
+3. Confirm the source language and locale directories.
+4. Run `i18ntk --command=analyze` or `i18ntk --command=validate` to inspect translation coverage.
+5. Use `i18ntk --command=complete` to fill missing keys when needed.
+
+The full onboarding flow is documented in [docs/getting-started.md](docs/getting-started.md).
 
 ## Install
 
 ```bash
-# global (recommended for CLI use)
+# global CLI use
 npm install -g i18ntk
 
-# local
+# local project use
 npm install --save-dev i18ntk
 
-# one-off
+# one-off execution
 npx i18ntk --help
 ```
 
-## Quick Start
+## Setup
+
+The toolkit stores project configuration in `.i18ntk-config` at the project root.
+
+Recommended setup flow:
 
 ```bash
-# initialize locales/project settings
+i18ntk
+# or
 i18ntk --command=init
+```
 
-# analyze translation completeness
-i18ntk --command=analyze
+During setup, you can define:
 
-# validate translation structure/content
-i18ntk --command=validate
+- source directory
+- source language
+- UI language
+- framework preference
+- output directory
+- backup behavior
 
-# complete missing keys
-i18ntk --command=complete
-```
+If you run in CI or a non-interactive shell, use:
 
-## Command Model (v2)
+```bash
+i18ntk --command=init --no-prompt
+```
 
-Primary CLI:
+## Daily Use
 
 ```bash
-i18ntk
-i18ntk --command=init
 i18ntk --command=analyze
 i18ntk --command=validate
 i18ntk --command=usage
@@ -62,10 +86,9 @@ i18ntk --command=scanner
 i18ntk --command=sizing
 i18ntk --command=complete
 i18ntk --command=summary
-i18ntk --command=debug
 ```
 
-Standalone executables:
+Standalone commands are also available:
 
 ```bash
 i18ntk-init
@@ -92,15 +115,43 @@ i18ntk-backup
 - `--dry-run`
 - `--help`
 
-## Configuration
+Example:
+
+```bash
+i18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports
+```
 
-i18ntk reads project settings from `.i18ntk-config` in your project root.
+## Runtime API
 
-Example:
+Use `i18ntk/runtime` when your application needs to read locale JSON files at runtime.
+
+```js
+const runtime = require('i18ntk/runtime');
+
+runtime.initRuntime({
+  baseDir: './locales',
+  language: 'en',
+  fallbackLanguage: 'en',
+  keySeparator: '.',
+  preload: true
+});
+
+console.log(runtime.t('common.hello'));
+runtime.setLanguage('fr');
+console.log(runtime.getLanguage());
+console.log(runtime.getAvailableLanguages());
+runtime.refresh('fr');
+```
+
+For a deeper walkthrough, see [docs/runtime.md](docs/runtime.md).
+
+## Configuration
+
+Example `.i18ntk-config`:
 
 ```json
 {
-  "version": "2.1.0",
+  "version": "2.3.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -112,34 +163,20 @@ Example:
 }
 ```
 
-## Runtime API
-
-```ts
-import { initRuntime, t, setLanguage, getLanguage } from 'i18ntk/runtime';
-
-initRuntime({
-  baseDir: './locales',
-  language: 'en',
-  fallbackLanguage: 'en',
-  preload: true
-});
-
-console.log(t('common.hello'));
-setLanguage('fr');
-console.log(getLanguage());
-```
+See [docs/api/CONFIGURATION.md](docs/api/CONFIGURATION.md) for the full configuration model.
 
-## Documentation
+## Docs
 
 - [Documentation Index](docs/README.md)
+- [Getting Started](docs/getting-started.md)
 - [API Reference](docs/api/API_REFERENCE.md)
 - [Configuration Guide](docs/api/CONFIGURATION.md)
 - [Runtime API Guide](docs/runtime.md)
 - [Scanner Guide](docs/scanner-guide.md)
 - [Environment Variables](docs/environment-variables.md)
-- [Migration Guide v2.1.0](docs/migration-guide-v2.1.0.md)
-- [Release Runbook](DEVUPDATE.md)
+- [Migration Guide v2.3.0](docs/migration-guide-v2.3.0.md)
+- [Optimization Prompt](docs/development/package-optimization-prompt.md)
 
 ## License
 
-MIT
+MIT

package/main/i18ntk-analyze.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * I18NTK TRANSLATION ANALYSIS SCRIPT
  * 
@@ -27,7 +27,7 @@ const SetupEnforcer = require('../utils/setup-enforcer');
   }
 })();
 
-loadTranslations( 'en', path.resolve(__dirname, '..', 'resources', 'i18n', 'ui-locales'));
+loadTranslations('en', path.resolve(__dirname, '..', 'ui-locales'));
 
 const PROJECT_ROOT = process.cwd();
 
@@ -67,7 +67,7 @@ class I18nAnalyzer {
       this.config = { ...baseConfig, ...(this.config || {}) };
       
       const uiLanguage = (this.config && this.config.uiLanguage) || 'en';
-      loadTranslations(uiLanguage, path.resolve(__dirname, '..', 'resources', 'i18n', 'ui-locales'));
+      loadTranslations(uiLanguage, path.resolve(__dirname, '..', 'ui-locales'));
       
       this.sourceDir = this.config.sourceDir;
       this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);
@@ -142,44 +142,44 @@ class I18nAnalyzer {
     }
   }
 
-  // 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');
+  // 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 &&
-          !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'));
-        });
+      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
@@ -190,17 +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 &&
-          !this.isExcludedLanguageDirectory(lang) &&
-          this.isValidLanguageCode(lang)
-        );
-      languages.push(...monolithLanguages);
-
-      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 [];
@@ -712,7 +712,7 @@ try {
         throw new Error(t('analyze.failedToWriteReportFile') || 'Failed to write report file securely');
       }
       
-      return reportPath;
+      return reportPath;
       
     } catch (error) {
       console.error(`Failed to save report for ${language}:`, error.message);
@@ -779,21 +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);
-          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}`);
-          }
+          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,
@@ -889,7 +889,7 @@ try {
         this.config = { ...baseConfig, ...this.config };
         
         const uiLanguage = this.config.uiLanguage || 'en';
-        loadTranslations(uiLanguage, path.resolve(__dirname, '..', 'resources', 'i18n', 'ui-locales'));
+        loadTranslations(uiLanguage, path.resolve(__dirname, '..', 'ui-locales'));
         
         this.sourceDir = this.config.sourceDir;
         this.sourceLanguageDir = path.join(this.sourceDir, this.config.sourceLanguage);

package/main/i18ntk-backup-class.js

@@ -2,12 +2,12 @@
 
 'use strict';
 
-const fs = require('fs/promises');
-const path = require('path');
-const { existsSync } = require('fs');
-const configManager = require('../utils/config-manager');
-const { logger } = require('../utils/logger');
-const { colors } = require('../utils/logger');
+const fs = require('fs');
+const fsp = fs.promises;
+const path = require('path');
+const configManager = require('../utils/config-manager');
+const { logger } = require('../utils/logger');
+const { colors } = require('../utils/logger');
 const SecurityUtils = require('../utils/security');
 
 /**
@@ -16,10 +16,10 @@ const SecurityUtils = require('../utils/security');
  * Class-based implementation of backup functionality for use with CommandRouter
  */
 class I18nBackup {
-    constructor(config = {}) {
-        this.config = config;
-        this.backupDir = path.join(process.cwd(), 'i18n-backups');
-        this.maxBackups = config.backup?.maxBackups || 10;
+    constructor(config = {}) {
+        this.config = config;
+        this.backupDir = path.join(process.cwd(), 'i18ntk-backups');
+        this.maxBackups = Math.min(Math.max(parseInt(config.backup?.maxBackups, 10) || 1, 1), 3);
     }
 
     /**
@@ -93,7 +93,7 @@ Options:
 
         // Create backup directory if it doesn't exist
         try {
-            await fs.mkdir(outputDir, { recursive: true });
+            await fsp.mkdir(outputDir, { recursive: true });
             logger.debug(`Created backup directory: ${outputDir}`);
         } catch (err) {
             if (err.code !== 'EEXIST') {
@@ -106,7 +106,7 @@ Options:
         // Validate directory
         const sourceDir = path.resolve(dir);
         try {
-            const stats = await fs.stat(sourceDir);
+            const stats = await fsp.stat(sourceDir);
             if (!stats.isDirectory()) {
                 throw new Error(`Path exists but is not a directory: ${sourceDir}`);
             }
@@ -121,7 +121,7 @@ Options:
         logger.info('\nCreating backup...');
 
         // Read all files in the directory
-        const files = (await fs.readdir(sourceDir, { withFileTypes: true }))
+        const files = (await fsp.readdir(sourceDir, { withFileTypes: true }))
             .filter(dirent => dirent.isFile() && dirent.name.endsWith('.json'))
             .map(dirent => dirent.name);
 
@@ -135,7 +135,7 @@ Options:
         for (const file of files) {
             const filePath = path.join(sourceDir, file);
             try {
-                const content = JSON.parse(await fs.readFile(filePath, 'utf8'));
+                const content = JSON.parse(await fsp.readFile(filePath, 'utf8'));
                 translations[file] = content;
             } catch (error) {
                 logger.error(`Could not read file ${file}: ${error.message}`);
@@ -143,8 +143,8 @@ Options:
         }
 
         // Create the backup
-        await fs.writeFile(backupPath, JSON.stringify(translations, null, 2));
-        const stats = await fs.stat(backupPath);
+        await fsp.writeFile(backupPath, JSON.stringify(translations, null, 2));
+        const stats = await fsp.stat(backupPath);
 
         logger.success('Backup created successfully');
         logger.info(`  Location: ${backupPath}`);
@@ -218,7 +218,7 @@ Options:
         try {
             // Ensure backup directory exists
             try {
-                await fs.access(this.backupDir);
+                await fsp.access(this.backupDir);
             } catch (err) {
                 if (err.code === 'ENOENT') {
                     logger.warn('No backups found. The backup directory does not exist yet.');
@@ -228,14 +228,14 @@ Options:
                 return { success: true, backups: [] };
             }
 
-            const files = await fs.readdir(this.backupDir);
+            const files = await fsp.readdir(this.backupDir);
             const backups = [];
 
             for (const file of files) {
                 if (file.startsWith('backup-') && file.endsWith('.json')) {
                     try {
                         const filePath = path.join(this.backupDir, file);
-                        const stats = await fs.stat(filePath);
+                        const stats = await fsp.stat(filePath);
                         backups.push({
                             name: file,
                             path: filePath,
@@ -298,14 +298,14 @@ Options:
         logger.info('\nVerifying backup...');
 
         try {
-            const data = await fs.readFile(backupPath, 'utf8');
+            const data = await fsp.readFile(backupPath, 'utf8');
             const content = JSON.parse(data);
 
             if (typeof content === 'object' && content !== null) {
                 const fileCount = Object.keys(content).length;
                 logger.success('Backup is valid');
                 logger.info(`  Contains ${fileCount} translation files`);
-                logger.info(`  Last modified: ${(await fs.stat(backupPath)).mtime.toLocaleString()}`);
+                logger.info(`  Last modified: ${(await fsp.stat(backupPath)).mtime.toLocaleString()}`);
 
                 return {
                     success: true,
@@ -334,14 +334,14 @@ Options:
         logger.info('\nCleaning up old backups...');
 
         try {
-            const files = await fs.readdir(this.backupDir);
+            const files = await fsp.readdir(this.backupDir);
             const backupFiles = files
                 .filter(file => file.startsWith('backup-') && file.endsWith('.json'))
                 .map(file => ({
                     name: file,
-                    path: path.join(this.backupDir, file),
-                    time: fs.statSync(path.join(this.backupDir, file)).mtime.getTime()
-                }))
+                    path: path.join(this.backupDir, file),
+                    time: fs.statSync(path.join(this.backupDir, file)).mtime.getTime()
+                }))
                 .sort((a, b) => b.time - a.time);
 
             // Keep only the most recent 'keep' files
@@ -355,7 +355,7 @@ Options:
             // Delete old backups
             for (const file of toDelete) {
                 try {
-                    await fs.unlink(file.path);
+                    await fsp.unlink(file.path);
                     logger.info(`  - Deleted: ${file.name}`);
                 } catch (err) {
                     logger.error(`  - Failed to delete ${file.name}: ${err.message}`);
@@ -374,12 +374,10 @@ Options:
         } catch (error) {
             logger.error('Error cleaning up backups:');
             logger.error(`  ${error.message}`);
-            if (process.env.DEBUG) {
-                console.error(error);
-            }
-            throw error;
-        }
-    }
+            logger.debug(error.stack || error.message);
+            throw error;
+        }
+    }
 
     async cleanupOldBackups(outputDir) {
         try {
@@ -408,13 +406,11 @@ Options:
         }
     }
 
-    handleError(error) {
-        logger.error('Backup operation failed:');
-        logger.error(`  ${error.message}`);
-        if (process.env.DEBUG) {
-            console.error(error);
-        }
-    }
-}
+    handleError(error) {
+        logger.error('Backup operation failed:');
+        logger.error(`  ${error.message}`);
+        logger.debug(error.stack || error.message);
+    }
+}
 
-module.exports = I18nBackup;
+module.exports = I18nBackup;