i18ntk 3.1.2 → 3.3.0

package/CHANGELOG.md

@@ -3,34 +3,105 @@
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [3.1.2] - 2026-05-07
-
-### Fixed
-- Auto Translate now resolves locale roots such as `./locales` to the selected source-language folder such as `./locales/en` when JSON files are stored under language folders.
-- Public package staging now verifies root `package.json` and `package.public.json` release metadata are synchronized before pack or publish.
-- Added a safe `publish:public:dry-run` path for validating the exact staged npm publish flow.
-
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.3.0] - 2026-05-20
+
 ### Changed
-- Updated release docs, npm README metadata, and package manifests for v3.1.2.
-- Kept generated backups, temporary benchmark datasets, local setup state, and debug repair files out of future public repo commits through `.gitignore`.
+- Auto Translate now supports `--provider google|deepl|libretranslate`; DeepL uses `DEEPL_API_KEY`, while LibreTranslate supports `LIBRETRANSLATE_URL` and optional `LIBRETRANSLATE_API_KEY`.
+- Auto Translate provider networking now keeps HTTPS, host allowlist, response-size, private-network, and redacted security logging protections in place for additional providers.
 
-## [3.1.1] - 2026-05-07
+### Fixed
+- `i18ntk-complete` now fills missing target-language keys from the English source value with a language prefix such as `[DE] Home` instead of writing `NOT_TRANSLATED`; this works for both `locales/en/*.json` and monolith `locales/en.json` layouts.
 
-### Added
-- **Auto Translate protection file workflow**: Added user-editable `i18ntk-auto-translate.json` support for protected terms, key paths, exact values, and regex patterns.
-- **Public package README guard**: Public package staging now verifies `README.md` is included and non-empty before publish.
+### Security
+- Eliminated all 21 dynamic `require()` calls flagged by Socket.dev: 20 `require(path.join(__dirname, ...))` patterns in `i18ntk-js.js`, `i18ntk-py.js`, `i18ntk-java.js`, `i18ntk-php.js`, and `i18ntk-go.js` converted to static string literal requires.
+- Added `SecurityUtils.validatePath()` gate around the remaining dynamic `require()` in `i18ntk-translate.js` `loadCustomTranslateFn`.
+- Created `utils/translate/safe-network.js` — a secure HTTPS wrapper with URL host/path allowlist validation, response size limits (100KB), suspicious query parameter detection, and security event logging. All outbound network access now flows through this validated layer.
+- Replaced direct `https.get` call in `utils/translate/api.js` with `safeHttpGet` from the safe-network wrapper.
+
+### Docs
+- README.md updated for v3.3.0 Auto Translate providers and secure provider operations.
+- SECURITY.md updated with Socket.dev analysis disclaimer and guidance on expected alerts for a CLI/i18n toolkit.
+- CHANGELOG.md and `package.json` versionInfo updated for v3.3.0.
+
+### Socket.dev Analysis Disclaimer
+
+This package is a developer CLI and runtime helper that performs file I/O, network access (translation provider APIs on user request), and environment variable access. As such, Socket.dev will flag the following alerts that are **expected and by design**:
+
+| Alert | Why it's expected |
+|---|---|
+| Network access | Only contacts configured translation providers via HTTPS when user invokes auto-translate. All outbound calls flow through `safe-network.js` with host/path allowlist validation, response size limits, private-network blocking, and redacted security event logging. No telemetry, no unexpected outbound calls. |
+| Environment variable access | Centralized through `env-manager.js` with a strict allowlist. Blocks `SECRET`, `PASSWORD`, `KEY`, `TOKEN`, `AWS_*`, `NPM_*`, and 15+ other patterns. |
+| Filesystem access | Reads/writes only project locale files and reports within validated paths. All FS operations gated by `SecurityUtils.validatePath`. |
+| URL strings | Hardcoded default provider URLs for Google, DeepL, and LibreTranslate used only for auto-translation. No external resource loading. |
 
-### Changed
-- Updated README and release documentation for the current Auto Translate protection workflow and public package contents.
-- Removed project-specific hardcoded validation examples so users configure their own brand and domain terms.
+The v3.3.0 release resolves the actionable dynamic-require alert by eliminating all 21 instances.
 
-### Fixed
-- Removed provider-shaped fake secret fixtures from tests to avoid GitHub push protection false positives.
-- Ensured public package metadata includes `readmeFilename: "README.md"` so npm can render the package README.
-
-## [3.1.0] - 2026-05-07
+## [3.2.0] - 2026-05-16
+
+### Security
+- **CRITICAL**: Fixed invalid `crypto.createCipherGCM`/`createDecipherGCM` API calls in `admin-pin.js` — replaced with `crypto.createCipheriv`/`createDecipheriv`.
+- **CRITICAL**: Fixed missing `SecurityUtils` imports in `admin-pin.js`, `security-config.js`, and `scripts/security-check.js` causing `ReferenceError` at runtime.
+- **CRITICAL**: Removed encryption key stored alongside ciphertext in `admin-pin.js`. The AES key was stored in the same JSON file as the encrypted PIN, providing zero cryptographic protection. Encryption key is now derived via HKDF from the scrypt hash.
+- Enforced HTTPS-only for Google Translate API requests in `utils/translate/api.js`; dropped `http` protocol support.
+- Fixed `http.get` timeout for Node.js <16.14 compatibility by using `req.setTimeout()` instead of the options-based `{ timeout }` parameter.
+- Added `SecurityUtils.validatePath` checks to `secure-backup.js` `restoreBackup` and `verifyBackup` methods.
+- Added `backupDir` traversal validation in `secure-backup.js` constructor.
+- Fixed `FileManagementService` `isAuthRequiredForScript`/`verifyPin` stubs — previously returned hardcoded `false`/`true`, disabling PIN protection. Now delegates to proper `AdminAuth` module.
+- Fixed `admin-auth.js` `logSecurityEvent` signature mismatches — 6 calls passed raw strings instead of structured objects.
+- Fixed `admin-pin.js` `getPinDisplay` to use stored `pinLength` instead of decrypting the raw PIN into memory.
+
+### Fixed
+- `admin-pin.js` lockout now uses timestamp-based expiry (`lockedUntil`) instead of `setTimeout`, ensuring lockout state survives process restarts.
+- `translate/traverse.js` `setLeaf` now correctly creates `[]` for numeric array indices (was creating `{}`).
+- `translate/traverse.js` extracted shared `parseKeyPath` function — `setLeaf` and `getLeaf` had duplicate path-parsing logic.
+- `translate/traverse.js` `deepClone` now handles `null`, `undefined`, and circular references gracefully.
+- `translate/api.js` retry logic now retries `TimeoutError` and `NetworkError` with exponential backoff (previously only retried rate-limit errors).
+- `translate/api.js` added `User-Agent` header to Google Translate API requests.
+- `main/manage/index.js` `startupTimeout` no longer cleared before `createPrompt` and other blocking initialization steps.
+- `main/manage/index.js` removed silent no-op `t('init.autoDetectedI18nDirectory', ...)` whose return value was never used.
+- `ultra-performance-optimizer.js` removed dead `preallocateMemory` pools (`stringPool`, `objectPool`, `arrayPool`) — ~1MB wasted allocation.
+- `ultra-performance-optimizer.js` `getCacheKey` now uses async `fs.stat` instead of blocking `fs.statSync`.
+- `ultra-performance-optimizer.js` GC timer now enforces minimum 5-second interval and warns when `--expose-gc` is missing.
+- `ultra-performance-optimizer.js` `readFileUltra` now handles files >64KB with chunked reads.
+- `ultra-performance-optimizer.js` `createUltraCache` replaced per-entry `setTimeout` (timer leak) with unified cleanup interval.
+- `ultra-performance-optimizer.js` benchmark now uses real benchmark datasets instead of non-existent mock files.
+- `config-manager.js` now exports `loadSettings`/`saveSettings` aliases — resolves 20+ phantom API fallback calls across the codebase.
+- `config-manager.js` `updateConfig` now clones before deep-merging to prevent in-place cache corruption.
+- `admin-pin.js` scrypt→pbkdf2 fallback now emits a console warning instead of failing silently.
+
+### Changed
+- Updated all documentation to v3.2.0: README, CHANGELOG, docs/README, getting-started, runtime, auto-translate, environment-variables, scanner-guide, API_REFERENCE, COMPONENTS, and CONFIGURATION.
+- Updated `package.json` version, `versionInfo`, `majorChanges`, and `nextVersion` for v3.2.0.
+- Socket badge URL updated to v3.2.0.
+
+## [3.1.2] - 2026-05-07
+
+### Fixed
+- Auto Translate now resolves locale roots such as `./locales` to the selected source-language folder such as `./locales/en` when JSON files are stored under language folders.
+- Public package staging now verifies root `package.json` and `package.public.json` release metadata are synchronized before pack or publish.
+- Added a safe `publish:public:dry-run` path for validating the exact staged npm publish flow.
+
+### Changed
+- Updated release docs, npm README metadata, and package manifests for v3.1.2.
+- Kept generated backups, temporary benchmark datasets, local setup state, and debug repair files out of future public repo commits through `.gitignore`.
+
+## [3.1.1] - 2026-05-07
+
+### Added
+- **Auto Translate protection file workflow**: Added user-editable `i18ntk-auto-translate.json` support for protected terms, key paths, exact values, and regex patterns.
+- **Public package README guard**: Public package staging now verifies `README.md` is included and non-empty before publish.
+
+### Changed
+- Updated README and release documentation for the current Auto Translate protection workflow and public package contents.
+- Removed project-specific hardcoded validation examples so users configure their own brand and domain terms.
+
+### Fixed
+- Removed provider-shaped fake secret fixtures from tests to avoid GitHub push protection false positives.
+- Ensured public package metadata includes `readmeFilename: "README.md"` so npm can render the package README.
+
+## [3.1.0] - 2026-05-07
 
 ### Added
 - **Placeholder-preserve translation mode**: Translates text segments around dynamic placeholders and reinserts the original tokens exactly.

package/README.md

@@ -1,6 +1,6 @@
-# i18ntk v3.1.2
+# i18ntk v3.3.0
 
-Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
+A i18n toolkit - A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
 
 ![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)
 
@@ -9,7 +9,7 @@ Zero-dependency internationalization toolkit for setup, scanning, analysis, vali
 [![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/3.1.2)](https://socket.dev/npm/package/i18ntk/overview/3.1.2)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/3.3.0)](https://socket.dev/npm/package/i18ntk/overview/3.3.0)
 
 ## Install
 
@@ -30,21 +30,14 @@ Requirements:
 - npm `>=8.0.0`
 - No runtime dependencies
 
-## What's New in 3.1.2
+## What's New in 3.3.0
 
-- Auto Translate can translate strings that contain placeholders by translating text around the placeholders and reinserting the original tokens.
-- Auto Translate supports user-editable protection rules in `i18ntk-auto-translate.json` for brand names, product terms, exact values, key paths, and regex patterns.
-- The manager Auto Translate flow runs in-process, avoiding production `child_process` usage for that command.
-- The target-language prompt supports `all` to translate into every configured target language while excluding the source language.
-- Source-directory prompts are clearer and accept absolute paths or project-relative paths.
-- Validation warnings now distinguish URLs, email addresses, secret-like values, and likely untranslated English content.
-- Sizing reports now include per-language file counts, file-set mismatches, and per-file key/character statistics.
-- Internal UI locale coverage is enforced against the English UI locale.
-- Public package staging verifies `README.md` is present before publish.
-- Auto Translate now resolves locale roots such as `./locales` to the selected source-language folder such as `./locales/en` when needed.
-- Public package staging now fails when root `package.json` and `package.public.json` release metadata drift.
+- **SECURITY**: Eliminated all 21 dynamic `require()` calls flagged by Socket.dev; 20 converted to static string literals, 1 gated with `SecurityUtils.validatePath`.
+- **AUTO TRANSLATE**: Added provider selection for Google, DeepL, and LibreTranslate.
+- **FIX**: `i18ntk-complete` now fills missing target-language keys from English values with language prefixes instead of `NOT_TRANSLATED`.
+- **DOCS**: SECURITY.md updated with Socket.dev analysis disclaimer explaining expected alerts for a CLI/i18n toolkit.
 
-See [CHANGELOG.md](./CHANGELOG.md) and [docs/migration-guide-v3.1.2.md](./docs/migration-guide-v3.1.2.md) for release details.
+See [CHANGELOG.md](./CHANGELOG.md) for more release details.
 
 ## Quick Start
 
@@ -52,7 +45,7 @@ Initialize a project:
 
 ```bash
 i18ntk
-# or
+# or with explicit command
 i18ntk --command=init
 ```
 
@@ -118,8 +111,8 @@ i18ntk-fixer
 i18ntk-backup
 i18ntk-translate
 ```
-
-Note: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` directly for backup operations.
+`n
+Note: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` (or legacy `i18ntk-backup`) directly for backup operations.
 
 ## Common Options
 
@@ -157,6 +150,21 @@ i18ntk-translate locales/en/common.json fr --dry-run --report-stdout
 i18ntk-translate locales/en es --source-dir locales/en --files "*.json" --no-confirm --preserve-placeholders
 ```
 
+Provider examples:
+
+```bash
+export DEEPL_API_KEY="your-deepl-api-key"
+i18ntk-translate locales/en/common.json de --provider deepl --no-confirm --preserve-placeholders
+
+export LIBRETRANSLATE_URL="https://libretranslate.com/translate"
+export LIBRETRANSLATE_API_KEY="optional-api-key"
+i18ntk-translate locales/en/common.json es --provider libretranslate --no-confirm --preserve-placeholders
+```
+
+`google` remains the default provider. You can also set `I18NTK_TRANSLATE_PROVIDER=deepl` or `I18NTK_TRANSLATE_PROVIDER=libretranslate`.
+
+Provider requests are HTTPS-only and response-size limited, and security logs redact provider query strings and response bodies. DeepL is pinned to official DeepL hosts by default; set `I18NTK_ALLOW_CUSTOM_TRANSLATE_HOSTS=1` only for a trusted DeepL-compatible proxy. Custom LibreTranslate URLs are blocked for localhost/private IP ranges unless `I18NTK_ALLOW_PRIVATE_TRANSLATE_URLS=1` is set for trusted local testing. Keep provider API keys in environment variables or a secret manager.
+
 The manager flow asks for:
 
 - source locale directory, either the folder with JSON files or a locale root such as `./locales`
@@ -296,7 +304,7 @@ Example:
 
 ```json
 {
-  "version": "3.1.2",
+  "version": "3.3.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -354,11 +362,9 @@ The public package manifest includes `readmeFilename: "README.md"`, and the rele
 - [Auto Translate Guide](./docs/auto-translate.md)
 - [Scanner Guide](./docs/scanner-guide.md)
 - [Environment Variables](./docs/environment-variables.md)
-- [Migration Guide v3.1.2](./docs/migration-guide-v3.1.2.md)
+- [Migration Guide v3.2.0](./docs/migration-guide-v3.2.0.md)
 - [Migration Guide v3.1.1](./docs/migration-guide-v3.1.1.md)
 - [Migration Guide v3.0.0](./docs/migration-guide-v3.0.0.md)
-- [Migration Guide v2.6.0](./docs/migration-guide-v2.6.0.md)
-- [Migration Guide v2.5.1](./docs/migration-guide-v2.5.1.md)
 
 ## Security
 

package/SECURITY.md

@@ -2,9 +2,9 @@
 
 ## Supported Versions
 
-The supported production line is `2.5.x`.
+The supported production line is `3.x`.
 
-Versions earlier than `2.5.0` are not recommended for production use because later releases include package, filesystem, environment, and admin-auth hardening.
+Versions earlier than `3.3.0` are not recommended for production use because later releases include Auto Translate provider hardening, dynamic-require elimination, and path-validation hardening.
 
 ## Security Model
 
@@ -14,8 +14,8 @@ Security priorities:
 
 - zero runtime dependencies
 - no install-time lifecycle commands in the public package manifest
-- no shipped local setup state, admin PINs, backups, reports, logs, credentials, or generated artifacts
-- centralized environment-variable access through `utils/env-manager.js`
+- no shipped local setup state, admin PINs, backup files, reports, logs, credentials, or generated artifacts
+- centralized environment-variable access through `utils/env-manager.js` with a strict allowlist
 - path containment checks based on resolved paths and `path.relative()`
 - timing-safe comparison for authentication hashes or tokens
 - silent-by-default logging for production-like contexts
@@ -24,6 +24,20 @@ Security priorities:
 
 The npm package uses a stripped public manifest. It must not contain install-time lifecycle commands, dependency fields, local setup state, or development tooling.
 
+## Socket.dev Analysis Disclaimer
+
+Socket.dev scans the published npm package and may flag the following alerts. These are **expected behaviors** for a developer CLI/i18n toolkit and are mitigated as described:
+
+| Alert | Design Rationale | Mitigation |
+|---|---|---|
+| **Network access** | Contacts configured translation providers via HTTPS only when user explicitly invokes auto-translate. No telemetry, no beaconing, no background network activity. | `utils/translate/safe-network.js` enforces HTTPS, host/path allowlists, response-size limits, private-network blocking, and redacted security logging for Google, DeepL, and LibreTranslate provider requests. |
+| **Environment variable access** | Reads env vars for logging level, output directory, UI language, and project paths. Required for CLI configuration. | `utils/env-manager.js` uses a fixed allowlist (28 vars). Blocks `SECRET`, `PASSWORD`, `KEY`, `TOKEN`, `AWS_*`, `GITHUB_*`, `NPM_*`, `NODE_*`, `PATH`, `HOME`, `USER`, `SHELL`, and 8 more patterns. |
+| **Filesystem access** | Reads/writes locale JSON files, config files, and reports within the user's project. Core function of the toolkit. | All FS operations are gated by `SecurityUtils.validatePath()` with path-traversal detection, symlink resolution, and base-path containment checks. |
+| **URL strings** | Contains hardcoded translation provider endpoint URLs for Google, DeepL, and LibreTranslate defaults. | Only used when user invokes `i18ntk-translate`. Custom provider URLs remain HTTPS-only and are validated before use. |
+
+The v3.3.0 release **resolved** the previously actionable Socket.dev alert:
+- **Dynamic require** — all 21 instances eliminated (20 converted to static string literals, 1 gated with `SecurityUtils.validatePath`).
+
 ## Reporting Vulnerabilities
 
 Do not report security vulnerabilities in public GitHub issues.
@@ -46,7 +60,7 @@ Security reports are reviewed privately first. Confirmed issues should receive:
 
 ## User Guidance
 
-- Keep i18ntk updated to `2.5.0` or newer.
+- Keep i18ntk updated to `3.3.0` or newer.
 - Do not commit `.i18ntk-config`, admin PIN files, backup directories, generated reports, logs, npm credentials, or secret material.
 - Run i18ntk only in project directories you trust.
 - Review generated translation changes before committing them.

package/main/i18ntk-complete.js

@@ -161,9 +161,14 @@ class I18nCompletionTool {
     return lowered.startsWith('backup-') || lowered === 'backup' || lowered === 'reports' || lowered === 'i18ntk-reports';
   }
 
-  // Get all JSON files from a language directory
-  getLanguageFiles(language) {
-    const languageDir = path.join(this.sourceDir, language);
+  // Get all JSON files from a language directory
+  getLanguageFiles(language) {
+    const monolithFile = path.join(this.sourceDir, `${language}.json`);
+    if (SecurityUtils.safeExistsSync(monolithFile, this.config.projectRoot)) {
+      return [`${language}.json`];
+    }
+
+    const languageDir = path.join(this.sourceDir, language);
     
     if (!SecurityUtils.safeExistsSync(languageDir, this.config.projectRoot)) {
       return [];
@@ -173,8 +178,20 @@ class I18nCompletionTool {
       .filter(file => {
         return file.endsWith('.json') && 
                !this.config.excludeFiles.includes(file);
-      });
-  }
+      });
+  }
+
+  getLanguageFilePath(language, fileName) {
+    if (fileName === `${language}.json`) {
+      return path.join(this.sourceDir, fileName);
+    }
+
+    return path.join(this.sourceDir, language, fileName);
+  }
+
+  usesMonolithFile(language) {
+    return SecurityUtils.safeExistsSync(path.join(this.sourceDir, `${language}.json`), this.config.projectRoot);
+  }
 
   // Parse key path and determine which file it belongs to
   parseKeyPath(keyPath) {
@@ -238,25 +255,30 @@ class I18nCompletionTool {
   }
 
   // Add missing keys to a language
-  addMissingKeysToLanguage(language, missingKeys, dryRun = false) {
-    const languageDir = path.join(this.sourceDir, language);
-    const changes = [];
+  addMissingKeysToLanguage(language, missingKeys, dryRun = false) {
+    const languageDir = path.join(this.sourceDir, language);
+    const changes = [];
+    const usesMonolith = this.usesMonolithFile(language);
     
     // Group keys by file
     const keysByFile = {};
     
-    missingKeys.forEach(keyPath => {
-      const { file, key } = this.parseKeyPath(keyPath);
-      if (!keysByFile[file]) {
-        keysByFile[file] = [];
-      }
+    missingKeys.forEach(keyPath => {
+      const { file, key } = usesMonolith
+        ? { file: `${language}.json`, key: keyPath }
+        : this.parseKeyPath(keyPath);
+      if (!keysByFile[file]) {
+        keysByFile[file] = [];
+      }
       keysByFile[file].push({ keyPath, key });
     });
     
-    // Process each file
-    for (const [fileName, keys] of Object.entries(keysByFile)) {
-      const filePath = path.join(languageDir, fileName);
-      let fileContent = {};
+    // Process each file
+    for (const [fileName, keys] of Object.entries(keysByFile)) {
+      const filePath = usesMonolith
+        ? path.join(this.sourceDir, fileName)
+        : path.join(languageDir, fileName);
+      let fileContent = {};
       
       // Load existing file or create new
       if (SecurityUtils.safeExistsSync(filePath, this.config.projectRoot)) {
@@ -266,12 +288,12 @@ class I18nCompletionTool {
           console.warn(t("completeTranslations.warning_could_not_parse_filepa", { filePath })); ;
           fileContent = {};
         }
-      } else {
-        // Create directory if it doesn't exist
-        if (!SecurityUtils.safeExistsSync(languageDir, this.config.projectRoot)) {
-          if (!dryRun) {
-            SecurityUtils.safeMkdirSync(languageDir, this.config.projectRoot, { recursive: true });
-          }
+      } else {
+        // Create directory if it doesn't exist
+        if (!usesMonolith && !SecurityUtils.safeExistsSync(languageDir, this.config.projectRoot)) {
+          if (!dryRun) {
+            SecurityUtils.safeMkdirSync(languageDir, this.config.projectRoot, { recursive: true });
+          }
         }
       }
       
@@ -303,19 +325,66 @@ class I18nCompletionTool {
     return changes;
   }
 
-  // Generate appropriate translation value based on key and language
-  generateTranslationValue(keyPath, language) {
-    // Generate value from key path for source language
-    const baseValue = this.generateValueFromKey(keyPath);
-    
-    // For source language, use the generated value
-    if (language === this.config.sourceLanguage) {
-      return baseValue;
-    }
-    
-    // For other languages, use the not translated marker
-    return this.config.notTranslatedMarker || 'NOT_TRANSLATED';
-  }
+  // Generate appropriate translation value based on key and language
+  generateTranslationValue(keyPath, language) {
+    const sourceValue = this.getSourceValueForKeyPath(keyPath);
+    const baseValue = typeof sourceValue === 'string' && sourceValue.trim() !== ''
+      ? sourceValue
+      : this.generateValueFromKey(keyPath);
+    
+    // For source language, use the generated value
+    if (language === this.config.sourceLanguage) {
+      return baseValue;
+    }
+    
+    return `[${language.toUpperCase()}] ${baseValue}`;
+  }
+
+  getNestedValue(obj, keyPath) {
+    const keys = String(keyPath || '').split('.');
+    let current = obj;
+
+    for (const key of keys) {
+      if (!current || typeof current !== 'object' || !(key in current)) {
+        return undefined;
+      }
+      current = current[key];
+    }
+
+    return current;
+  }
+
+  getSourceValueForKeyPath(keyPath) {
+    if (!this.sourceLanguageDir && !this.usesMonolithFile(this.config.sourceLanguage)) {
+      return undefined;
+    }
+
+    const sourceFiles = this.getLanguageFiles(this.config.sourceLanguage);
+    const keyPathStr = String(keyPath || '');
+    const parsed = this.parseKeyPath(keyPathStr);
+
+    for (const fileName of sourceFiles) {
+      const sourceFilePath = this.getLanguageFilePath(this.config.sourceLanguage, fileName);
+      try {
+        const sourceContent = SecurityUtils.safeParseJSON(SecurityUtils.safeReadFileSync(sourceFilePath, this.config.projectRoot, 'utf8'));
+        if (!sourceContent || typeof sourceContent !== 'object') continue;
+
+        const candidates = [keyPathStr];
+        if (fileName === parsed.file) {
+          candidates.push(parsed.key);
+        }
+
+        for (const candidate of candidates) {
+          const value = this.getNestedValue(sourceContent, candidate);
+          if (value !== undefined) return value;
+        }
+      } catch (error) {
+        console.warn(t("complete.couldNotParseSource", { file: sourceFilePath }));
+      }
+    }
+
+    return undefined;
+  }
 
   // Generate a readable value from a key path
   generateValueFromKey(keyPath) {
@@ -351,18 +420,18 @@ class I18nCompletionTool {
   }
 
   // Get missing keys by comparing source language with target languages
-  getMissingKeysFromComparison() {
-    const sourceFiles = this.getLanguageFiles(this.config.sourceLanguage);
-    const missingKeys = [];
-    
-    if (!SecurityUtils.safeExistsSync(this.sourceLanguageDir, this.config.projectRoot)) {
-      console.log(t("complete.sourceLanguageNotFound", { sourceLanguage: this.config.sourceLanguage }));
-      return [];
-    }
-    
-    // Process each file in source language
-    for (const fileName of sourceFiles) {
-      const sourceFilePath = path.join(this.sourceLanguageDir, fileName);
+  getMissingKeysFromComparison() {
+    const sourceFiles = this.getLanguageFiles(this.config.sourceLanguage);
+    const missingKeys = [];
+    
+    if (sourceFiles.length === 0) {
+      console.log(t("complete.sourceLanguageNotFound", { sourceLanguage: this.config.sourceLanguage }));
+      return [];
+    }
+    
+    // Process each file in source language
+    for (const fileName of sourceFiles) {
+      const sourceFilePath = this.getLanguageFilePath(this.config.sourceLanguage, fileName);
       
       try {
         const sourceContent = SecurityUtils.safeParseJSON(SecurityUtils.safeReadFileSync(sourceFilePath, this.config.projectRoot, 'utf8'));
@@ -373,7 +442,9 @@ class I18nCompletionTool {
         for (const language of languages) {
           if (language === this.config.sourceLanguage) continue;
           
-          const targetFilePath = path.join(this.sourceDir, language, fileName);
+          const targetFilePath = fileName === `${this.config.sourceLanguage}.json` || this.usesMonolithFile(language)
+            ? path.join(this.sourceDir, `${language}.json`)
+            : path.join(this.sourceDir, language, fileName);
           let targetKeys = [];
           
           if (SecurityUtils.safeExistsSync(targetFilePath, this.config.projectRoot)) {

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/manage/index.js

@@ -146,7 +146,6 @@ class I18nManager {
 
                     if (hasLanguageDirs) {
                         this.config.sourceDir = possiblePath;
-                        t('init.autoDetectedI18nDirectory', { path: possiblePath });
                         break;
                     }
                 } catch (error) {
@@ -347,7 +346,6 @@ class I18nManager {
             if (!shouldSkipInitCheck) {
                 await SetupEnforcer.checkSetupCompleteAsync();
             }
-            clearStartupTimeout();
 
             prompt = createPrompt({ noPrompt: args.noPrompt });
             const interactive = isInteractive({ noPrompt: args.noPrompt });

package/main/manage/managers/InteractiveMenu.js

@@ -1,6 +1,10 @@
 /**
  * Interactive Menu Manager
  * @module managers/InteractiveMenu
+ * @deprecated This module is superseded by the I18nManager.showInteractiveMenu
+ *   implementation in main/manage/index.js. This file is retained only for
+ *   backward compatibility with existing test references and should not be
+ *   used in new code.
  */
 
 const { t } = require('../../../utils/i18n-helper');