i18ntk 4.5.2 → 4.5.3

package/CHANGELOG.md

@@ -3,15 +3,24 @@
 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).
-
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [4.5.3] - 2026-06-19
+
+### Fixed
+
+- **Usage Scanner (Critical):** Fixed `supportedExtensions` default fallback in `config-helper.js` that excluded `.tsx` and `.jsx` files from source scanning. The default was `['.json', '.js', '.ts']` — missing `.jsx` and `.tsx`. In a Next.js project with 2704 keys across 1087 files, this caused the scanner to find only 57 keys (2.1%) instead of 2702 (99.9%) because all `.tsx` component files were silently ignored. The fix adds `.jsx` and `.tsx` to the default fallback: `['.json', '.js', '.jsx', '.ts', '.tsx']`.
+- **Usage Dead Code:** Cleaned up unreachable initializer in `i18ntk-usage.js` that was supposed to set default `includeExtensions` but never ran because `supportedExtensions` was always set by `config-helper.js`. Added `.vue` and `.svelte` to the fallback for completeness.
+
 ## [4.5.2] - 2026-06-19
 
 ### Fixed
+
 - **Complete (Namespace Wrapper):** Fixed critical bug where missing keys were inserted at the wrong nesting level in target locale files. When a file (e.g., `auth.json`) contains a namespace wrapper matching its filename (`{ "auth": { ... } }`), the `complete` command now detects this wrapper and inserts keys inside it (`auth.panel.sign_in`) instead of at root level (`panel.sign_in`). This prevents runtime lookup failures for `t("auth.panel.sign_in")`.
 - **Translate (--output-dir):** Fixed bug where the `--output-dir` flag wrote translated files directly to `<output-dir>/<filename>` instead of `<output-dir>/<targetLang>/<filename>`. This caused all translations (regardless of target language) to land in the same directory, silently overwriting files from other languages in multi-language projects. When `args.outputDir` is provided, `processFile()` now appends `targetLang` to construct the correct output path.
 
 ### Tests
+
 - Added `tests/regression-v452.test.js` with 18 regression tests covering:
   - Complete command namespace wrapper detection (parseKeyPath, setNestedValue, hasNestedKey, wrapper detection logic)
   - Validate getAllKeys leaf-only mode and completeness calculation
@@ -19,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Scanner source directory fallback when sourceDir equals i18nDir
   - Doctor auto-detection of languages from i18n directory
   - Version consistency across package files
-- Added `--output-dir` target language subdirectory tests to `tests/regression-v452.test.js`: verifies `processFile()` places output in `<outputDir>/<targetLang>/<file>` and that CLI `--output-dir` produces the correct nested path
+- Added `--output-dir` target language subdirectory tests to `tests/regression-v452.test.js`: verifies `processFile()` places output in `<outputDir>/<targetLang>/<file>` and that CLI `--output-dir` produces the correct nested path
 - Added 8 tests in `tests/usage-insights.test.js` for hardcoded text false-positive filtering:
   - JS/TS built-in type name rejection (Promise, Boolean, String)
   - Code expression operator rejection (&&, ||, ===, !==, =>)
@@ -29,6 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.5.1] - 2026-06-19
 
 ### Fixed
+
 - **Complete:** Fixed wrong nesting level when adding missing keys to target locale files that have a namespace wrapper matching the file name. Previously, `parseKeyPath("auth.panel.sign_in")` returned `{ file: "auth.json", key: "panel.sign_in" }`, and `setNestedValue` inserted `panel` at the root level instead of inside the existing `auth` wrapper. The fix detects namespace wrappers (e.g., `auth.json` containing `{ "auth": { ... } }`) and prepends the namespace to the insertion path so keys go inside the wrapper.
 - **Validate:** `getAllKeys()` no longer reports parent namespace objects (e.g., `footer`) as missing keys alongside their leaf children (`footer.copyright`). Only leaf (string) keys are now compared during structural validation.
 - **Validate:** Completion percentage now compares against source locale total keys, not target locale self-count. A locale with 14 of 42 source keys now correctly shows 33% instead of 100%.
@@ -39,12 +49,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.5.0] - 2026-06-19
 
 ### Security — Prototype Pollution Hardened
+
 - **safe-json.js:** Added `stripPrototypePollution()` function that recursively filters `__proto__`, `constructor`, and `prototype` keys from parsed JSON locale files. Applied to all `readJsonSafe()` calls.
 - **runtime/index.js:** `deepMerge()` now blocks `__proto__`, `constructor`, and `prototype` keys during locale data merging. `readJsonSafe()` now applies `stripPrototypeKeys()` to all parsed JSON, ensuring prototype pollution protection at runtime data ingestion point.
 - **settings-manager.js:** `mergeWithDefaults()` now filters prototype pollution keys from user-supplied settings before spreading into defaults.
 - **safe-json.js:** Exported `stripPrototypePollution` for use by other modules.
 
 ### Fixed
+
 - **Backup:** Removed duplicate `const sourceDir` declaration that caused SyntaxError at module load (was unrecoverable crash for all backup operations).
 - **Backup:** Added `try/catch` around `JSON.parse()` in restore path to handle corrupt backup files gracefully with a descriptive error message.
 - **Complete:** Added missing `getUnifiedConfig` import from `utils/config-helper` (was ReferenceError at runtime).
@@ -56,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **i18n-helper:** `stripBOMAndComments()` now safely handles null/undefined inputs.
 
 ### Changed
+
 - **Version:** Bumped to 4.5.0 (minor version due to scope and severity of security fixes).
 - **i18n-helper deepMerge:** Synchronized with runtime `deepMerge` — now uses `Object.keys` (safe) instead of `for...in`, handles null target/fallback, and filters `__proto__`/`constructor`/`prototype` keys for consistent prototype pollution protection across all code paths.
 - **Testing:** Added `tests/edge-case-hardening.test.js` with 33 new tests covering prototype pollution protection, SecurityUtils edge cases, backup corrupt handling, report malformed JSON resilience, validation risk detection null-safety, config manager robustness, version consistency, and deepMerge edge cases.
@@ -64,6 +77,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.4.5] - 2026-06-08
 
 ### Fixed
+
 - Removed orphaned duplicate code block from `main/i18ntk-scanner.js` that caused a SyntaxError when loading the scanner CLI.
 - Fixed `utils/safe-json.js` where a duplicate `readJsonSafe` function overwrote the SecurityUtils-based implementation with an insecure version that referenced an undefined `fs` variable.
 - Added periodic cache eviction to `missingKeyCache` in `utils/i18n-helper.js` to prevent unbounded memory growth in long-running processes.
@@ -78,43 +92,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Security:** `validateConfig` now runs `isSafePath` validation on absolute paths instead of skipping them entirely (`return` in forEach was bypassing all checks for absolute config paths).
 
 ### Added
+
 - **Framework detection:** Added support for ngx-translate (Angular), next-intl (Next.js), nuxt-i18n (Nuxt), svelte-i18n (Svelte), and solid-i18n (Solid) framework detection via dependency lookup.
 - `detectFramework()` now also checks the `dependencies` property as a fallback for the `deps` array, ensuring backward compatibility.
 - Created `tests/fixtures/test.json` fixture so file system security tests validate real file reads instead of passing vacuously.
 
 ### Changed
+
 - Removed dead `{ gte }` import from `version-utils` and unused `FRAMEWORK_COMPATIBILITY` object from `framework-detector.js`.
 - Security test `logSecurityEvent` now properly sets `I18NTK_DEBUG` and `I18NTK_ENABLE_SECURITY_LOGS` env vars and uses try/catch to verify non-throw behavior.
 - `validateConfig` "reject invalid configuration" test now uses `assert.strictEqual` for stronger path traversal assertions.
 
-## [4.4.4] - 2026-06-05
-
-### Fixed
-- Likely-untranslated reporting now ignores placeholder-only and symbol/dynamic values such as `{file}`, `{path}`, and icon-prefixed labels instead of treating them as untranslated English.
-- Dynamic values with translated surrounding copy and English placeholder tokens, such as `"command": "指示： {command}"`, are no longer flagged as untranslated.
-
-### Changed
-- `.i18ntk-config` now accepts a top-level `extensions` object for VS Code Workbench and Lens settings. The CLI preserves this section during config validation and ignores unknown extension-owned nested keys.
-- Documented shared config edge cases so editor extensions can sync workspace defaults without changing CLI behavior.
-
-## [4.4.3] - 2026-06-04
-
-### Fixed
+## [4.4.4] - 2026-06-05
+
+### Fixed
+
+- Likely-untranslated reporting now ignores placeholder-only and symbol/dynamic values such as `{file}`, `{path}`, and icon-prefixed labels instead of treating them as untranslated English.
+- Dynamic values with translated surrounding copy and English placeholder tokens, such as `"command": "指示： {command}"`, are no longer flagged as untranslated.
+
+### Changed
+
+- `.i18ntk-config` now accepts a top-level `extensions` object for VS Code Workbench and Lens settings. The CLI preserves this section during config validation and ignores unknown extension-owned nested keys.
+- Documented shared config edge cases so editor extensions can sync workspace defaults without changing CLI behavior.
+
+## [4.4.3] - 2026-06-04
+
+### Fixed
+
 - `package.public.json` now includes the `./report` export entry (`./utils/report-model.js`) that was missing, fixing the sync check during public package builds.
 
-## [4.4.2] - 2026-06-02
-
-### Fixed
-- Auto Translate `processFile()` now accepts source file paths relative to the current project, matching direct CLI behavior and avoiding safe-read failures in programmatic callers.
-- Auto Translate now treats protected product terms as allowed English when deciding whether existing target values should be kept in `only-missing` mode.
-- Auto Translate detects and retries more visibly broken target values, including replacement-character artifacts, mojibake, repeated question marks, and target-language prefix leftovers.
-
-### Added
-- Added regression coverage for relative source paths, protected product terms, broken target values, placeholder handling, and managed Auto Translate residual checks.
-
-## [4.4.1] - 2026-06-02
-
-### Security
+## [4.4.2] - 2026-06-02
+
+### Fixed
+
+- Auto Translate `processFile()` now accepts source file paths relative to the current project, matching direct CLI behavior and avoiding safe-read failures in programmatic callers.
+- Auto Translate now treats protected product terms as allowed English when deciding whether existing target values should be kept in `only-missing` mode.
+- Auto Translate detects and retries more visibly broken target values, including replacement-character artifacts, mojibake, repeated question marks, and target-language prefix leftovers.
+
+### Added
+
+- Added regression coverage for relative source paths, protected product terms, broken target values, placeholder handling, and managed Auto Translate residual checks.
+
+## [4.4.1] - 2026-06-02
+
+### Security
+
 - **HIGH**: Backup operations (`create`, `restore`, `list`, `verify`) now validate all path arguments via `SecurityUtils.validatePath()`. Previously, `i18ntk-backup` accepted arbitrary `--output` and source directory paths without any validation, enabling writes outside project boundaries.
 - **HIGH**: Backup `handleCreate`, `handleRestore` now use `SecurityUtils.safeWriteFileSync`, `safeReadFileSync`, `safeMkdirSync` instead of raw `fs.promises`/`fs` calls.
 - **HIGH**: `i18ntk-complete` now validates `--source-dir` CLI override through `SecurityUtils.validatePath()` and sanitizes `--source-language` through `SecurityUtils.sanitizeInput()` instead of accepting raw user input.
@@ -127,11 +149,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **LOW**: i18ntk Lens `scanner.ts` now rejects custom wrapper names > 100 characters to prevent ReDoS via malicious VSCode config values.
 
 ### Added
+
 - `SecurityUtils.MAX_JSON_SIZE`, `SecurityUtils.MAX_JSON_DEPTH`, `SecurityUtils.MAX_FILENAME_LENGTH` constants for configurable safety limits.
 
 ## [4.4.0] - 2026-06-02
 
 ### Added
+
 - Dead-key detection now uses resolved dynamic key data from usage insights instead of crude text-overlap heuristics. Keys expanded from template literals or const arrays are properly tracked and marked with low confidence.
 - Locale JSON import detection: `import en from '../../locales/en/foo.json'` is detected and property accesses are tracked as key usages.
 - Confidence-split unused key reports: confirmed (≥80%), likely (40-80%), possibly used (<40%).
@@ -150,10 +174,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - i18ntk Workbench and i18ntk Lens can read Auto Translate residual reports, show the affected key in the VS Code editor, and offer a quick action to add intentionally unchanged keys to Auto Translate protection.
 - Bounded dynamic expansion suggestions in usage report with explicit-map recommendation pattern.
 - Telemetry/event literal classification: known-key strings inside `trackEvent()`, `emitDomainEvent()`, `analytics.track()`, etc. are classified as `literal-telemetry` and excluded from translation usage counts. Non-translation calls get context notes in the report.
-- Object-method translation calls: `input.tx("key")`, `helper.tx("key")`, and `.tx(\`key.${var}\`)` are now recognized as translation calls alongside standalone `tx()`.
+- Object-method translation calls: `input.tx("key")`, `helper.tx("key")`, and `.tx(\`key.${var}\`)`are now recognized as translation calls alongside standalone`tx()`.
 - Local wrapper resolution: functions like `const text = (key, fallback) => tx(key)` that internally call known translation runtimes are detected and their string-literal invocations resolved to keys with `local-wrapper` match type.
 
 ### Fixed
+
 - `--source-dir` and `--i18n-dir` no longer forced to the same value when both are explicitly passed via CLI.
 - Path display (`displayPaths`) now reflects CLI overrides instead of only config file values.
 - Dead-key detection `_matchesDynamicPattern` replaced with `_matchesDynamicPrefix` using actual resolved data.
@@ -162,12 +187,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Object-method `tx()` calls and local wrapper functions are now included in usage analysis, preventing Lens false positives on keys used through these patterns.
 
 ### Changed
+
 - VSCode workbench bumped to 1.1.0, lens extension to 1.1.0.
 - Major changes list in package.json and package.public.json updated for 4.4.0.
 
 ## [4.3.3] - 2026-06-01
 
 ### Fixed
+
 - Usage extraction no longer reports ordinary method calls such as `get("next")`, `headers.get("etag")`, `set(...)`, or `setItem(...)` as missing translation keys.
 - Usage insights now resolve `tx(...)` wrapper calls and bounded dynamic `tx` template keys, reducing false unused-key reports for local wrappers.
 - Key naming validation now supports hybrid dot-path plus snake_case segment keys, such as `namespace.section.snake_case_leaf`, while still rejecting malformed separators and uppercase segments.
@@ -176,12 +203,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.3.2] - 2026-05-31
 
 ### Changed
+
 - Documentation, README badges, and migration guidance now reference the current 4.3.2 release.
 - Release metadata now marks 4.3.0 for npm deprecation because its npm tarball is unavailable.
 
 ## [4.3.1] - 2026-05-31
 
 ### Fixed
+
 - Published tarball now includes `utils/english-placeholder-checker.js`, resolving `MODULE_NOT_FOUND` at startup for `i18ntk-fixer --check-placeholders` and manager option 7.
 - Language-specific CLI entry points (`main/i18ntk-go.js`, `main/i18ntk-java.js`, `main/i18ntk-js.js`, `main/i18ntk-php.js`, `main/i18ntk-py.js`) and their shared `utils/mini-commander.js` dependency are now included in the published package.
 - Removed inconsistent `.js` extension suffixes from require paths in `main/i18ntk-js.js`.
@@ -189,6 +218,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.3.0] - 2026-05-31
 
 ### Fixed
+
 - Auto Translate now treats single-word uppercase target-language placeholders such as `[AR] Email` and `[AR] Password` as untranslated target values, matching the existing multi-word `[AR] What We Offer` detection.
 - Auto Translate now treats bracketed target-language placeholders case-insensitively, so `[zh] Email` and `[TR] Password` are both retried for the matching target language.
 - Managed Auto Translate now checks every selected source file for a target language before reporting leftover failures, instead of stopping after the first failed file.
@@ -199,11 +229,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.2.1] - 2026-05-31
 
 ### Changed
+
 - Auto Translate now treats uppercase target-language placeholders such as `[AR] What We Offer` as untranslated target values when the bracketed code matches the target language, so target-aware mode sends the source text for translation instead of keeping the placeholder copy.
 - Auto Translate now performs a final pre-write leftover check and retries values that still look like placeholder-prefixed untranslated text, untranslated markers, source-language copies, or broken output.
 - Auto Translate reports leftover values in the post-translation report and exits with validation failure when leftovers remain after the final retry, instead of reporting a clean completion.
 
 ### Fixed
+
 - Usage analysis no longer writes its inferred app source fallback, such as `src`, back into the shared locale configuration when `sourceDir` and `i18nDir` are both the locale directory.
 - Manager sizing now reads the configured i18n directory unless `--source-dir` is explicitly provided, so running sizing after usage no longer silently analyzes the wrong directory.
 - Manager sizing now treats a failed sizing analysis as a command failure instead of printing a generic operation success.
@@ -212,6 +244,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.2.0] - 2026-05-30
 
 ### Security
+
 - Shared path validation no longer permits artifact-like filenames such as `.lock` or `.temp-config.json` to bypass base-directory containment.
 - Shared path validation now rejects Windows cross-drive escape cases where `path.relative()` returns an absolute path.
 - Custom `I18NTK_INTERNAL_PATH_PREFIXES` entries can no longer mark arbitrary outside directories as internal roots.
@@ -220,6 +253,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Auto Translate provider URL validation now blocks IPv4-mapped IPv6 loopback/private hosts.
 
 ### Changed
+
 - Main runtime now includes production-safe features from the enhanced runtime surface: per-call language overrides, synchronous `translateBatch()`, and `clearCache()` / `getCacheInfo()` helpers.
 - `i18ntk/runtime/enhanced` remains available as a legacy public subpath for compatibility, while new production integrations should prefer the lightweight `i18ntk/runtime` API.
 - Usage analysis now indexes known translation keys back to source files, including direct i18n calls and literal key references that were previously missed.
@@ -242,6 +276,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated public, root, and development package metadata for the 4.2.0 release line.
 
 ### Fixed
+
 - Runtime JSON loading now preserves valid translation strings containing comment-like text such as `/* token */` by parsing valid JSON before using the comment-stripping fallback.
 - Enhanced runtime now exports the top-level `translateBatch()`, `translateBatchEncrypted()`, and `tTyped()` helpers declared by its TypeScript definitions, and those declarations now reflect async return values.
 - Usage analysis no longer scans the project root when `sourceDir` and `i18nDir` both point at the locale directory; it now uses a detected app source directory or disables usage scanning with a clear warning.
@@ -258,6 +293,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.1.0] - 2026-05-21
 
 ### Fixed
+
 - Runtime: stale manifest entries (deleted files after manifest construction) no longer cause unhandled exceptions; loadedFiles set before load with try/catch guard.
 - Runtime: `refresh()` now correctly clears the key manifest for the refreshed language, preventing stale file references.
 - Runtime: null `baseDir` guard prevents cascading `validatePath(null)` errors in `loadKeyManifestFromDir`.
@@ -275,7 +311,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Watch: debounce `setTimeout` timers are now stored per-watcher and cleared on `emitter.stop()`, preventing memory leaks and spurious I/O after stop.
 - Watch: `'unlink'` events are now subscribed for backward-compatible plain-function callback users.
 - Usage: duplicate `require.main === module` block removed (caused `TypeError: Identifier 'main' has already been declared` at execution).
-- Usage: `_keyInSourceComments` optimized from O(n*m) to O(n+m) by pre-computing a `Set` of all comment strings once before the dead key loop.
+- Usage: `_keyInSourceComments` optimized from O(n\*m) to O(n+m) by pre-computing a `Set` of all comment strings once before the dead key loop.
 - Usage: `--cleanup=false` and `--dry-run-delete=false` now correctly parse as falsy via `toBool()` helper.
 - Usage: broken `detectFrameworkPatterns()` call with `undefined` arguments removed.
 - Usage: dead `return;` in `analyze()` removed so the result object is now actually returned.
@@ -295,6 +331,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Public package metadata updated.
 
 ### Security
+
 - Watch module: debounce timers properly cleaned up on stop and callback subscriptions corrected for object-format and unlink handlers.
 - Runtime: loadedFiles lock-before-load pattern prevents duplicate I/O and stale manifest crash.
 - Backup: circular parent reference detection; `--incremental=false` string truthy bypass closed.
@@ -307,6 +344,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.0.0] - 2026-05-21
 
 ### Added
+
 - **Sizing Expansion Prediction**: `i18ntk-sizing` now supports `--predict-expansion` flag that computes per-key character-count expansion ratios across languages and classifies them into Safe/Warning/Critical risk tiers for UI layout planning. Includes a built-in language-pair expansion reference table (EN→DE 35%, EN→RU 50%, EN→JA -40%, etc.).
 - **Watch Hot Reload**: `utils/watch-locales.js` rewritten as an EventEmitter-compatible watcher with debouncing (300ms default) and SHA-256 hash tracking to skip no-change saves. Returns a callable watcher object with `change`, `add`, `unlink`, `error` events and `stop()`.
 - **Usage Dead Key Detection**: `i18ntk-usage` adds `--cleanup` and `--dry-run-delete` flags that identify unused translation keys with confidence scores (0.0–1.0) factoring dynamic access patterns, comment references, and file recency. Produces a `.dead-keys.json` report for safe review before deletion.
@@ -317,28 +355,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Protection Context-Aware Rules**: `utils/translate/protection.js` extends the protection config schema to support context rules (`after:word`, `before:word`, `standalone`, `surrounded:left,right`). Plain string terms remain fully backward compatible. Total context rules capped at 100.
 
 ### Fixed
+
 - `i18ntk/runtime` `initRuntime()` now returns independent runtime instances with separate language, fallback language, base directory, and cache state. Later `initRuntime()` calls no longer overwrite earlier returned runtimes or the module-level compatibility singleton.
 
 ### Changed
+
 - `watchLocales()` now returns a callable watcher object with EventEmitter methods instead of only a bare `stop` function. Existing `const stop = watchLocales(...); stop();` usage remains supported. The returned object fires `change`, `add`, `unlink`, `error` events. If a callback function is passed as the second argument, it is auto-subscribed to `change` and `add` for backward compatibility.
 - **BREAKING**: `i18ntk-sizing` JSON reports now include `expansionPredictions` at the top level when `--predict-expansion` is used. This field is additive — existing report fields are preserved.
 
 ## [3.3.0] - 2026-05-20
 
 ### Changed
+
 - 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.
 
 ### 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.
 
 ### 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.
@@ -347,18 +391,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 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. |
+| 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.                                                                                                                                                                                |
 
 The v3.3.0 release resolves the actionable dynamic-require alert by eliminating all 21 instances.
 
 ## [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.
@@ -371,6 +416,7 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - 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.
@@ -390,6 +436,7 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - `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.
@@ -397,31 +444,37 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 ## [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.
 - **Auto Translate beta settings**: Added settings for placeholder mode, concurrency, batch size, progress interval, retry count, retry delay, timeout, dry-run preview, report output, and BOM output.
 - **Large-file tuning flags**: Added `--batch-size` and `--progress-interval` to `i18ntk-translate`.
@@ -430,6 +483,7 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - **Sizing file-set analysis**: Added per-language file counts, per-file sizing statistics, and missing/extra file comparison across locale folders.
 
 ### Changed
+
 - Automated and manager Auto Translate flows now default to placeholder `preserve` mode instead of skipping placeholder-bearing strings.
 - `i18ntk-translate` can now be imported and run in-process by other package modules.
 - Source JSON reads tolerate UTF-8 BOM-prefixed files.
@@ -438,17 +492,20 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - Sizing reports now include folder-level file counts and per-file key/character breakdowns for each language.
 
 ### Fixed
+
 - Fixed false-positive validation warnings for normal product copy terms.
 - Fixed validator handling so ordinary explanatory uses of words like `token` or `secret` are not treated as leaked credentials.
 - Fixed distorted `i18ntk-sizing` table output by rendering aligned columns from measured values instead of fixed localized spacing.
 - Fixed sizing language comparison output so it uses analyzed languages and the configured source language baseline.
 
 ### Security
+
 - Removed production `child_process` usage from `main/manage/commands/TranslateCommand.js` by replacing the spawned CLI process with an in-process translator call.
 
 ## [3.0.0] - 2026-05-05
 
 ### Added
+
 - **`i18ntk-translate`**: Zero-dependency CLI tool that converts English source JSON locale files into any target language via Google's free Translate API.
 - **Placeholder protection**: Intelligent detection, masking, and unmasking of dynamic placeholder tokens (`{name}`, `{{count}}`, `%d`, `%s`, `:param`, `{{variable}}`, `%{name}`, `${var}`, etc.) to prevent corruption during translation.
 - **Custom regex support**: `--custom-regex` flag to define additional placeholder patterns for detection and protection.
@@ -463,11 +520,13 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - **Deep JSON traversal**: Full support for nested objects and arrays, preserving data types, null values, and non-string leaf values.
 
 ### Changed
+
 - Version bumped to 3.0.0 (major release with new translation tool feature).
 
 ## [2.6.0] - 2026-05-03
 
 ### Security
+
 - **CRITICAL**: Fixed 8+ silent-write failures where `safeWriteFileSync` was called without basePath parameter across `utils/config.js`, `utils/config-helper.js`, `utils/secure-errors.js`, and `main/i18ntk-scanner.js`.
 - Replaced all raw `fs` calls (`readdirSync`, `statSync`, `mkdirSync`, `unlinkSync`, `rmSync`) with `SecurityUtils` wrappers in `main/i18ntk-validate.js`, `main/i18ntk-scanner.js`, `main/manage/commands/FixerCommand.js`, and `utils/secure-errors.js`.
 - Fixed path traversal checks in `security.js` and `config-manager.js` — replaced fragile `path.sep`-based comparison with robust `startsWith('..')` prefix check.
@@ -475,6 +534,7 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - Fixed `SecurityUtils.safeParseJSON` reference leak — deep-clones objects instead of returning caller's reference.
 
 ### Fixed
+
 - Fixed `main/i18ntk-analyze.js` `this.adminAuth` reference error (local variable was not assigned to instance property).
 - Fixed `main/i18ntk-validate.js` `ExitCodes.CONFIG_ERROR` referenced before declaration.
 - Fixed `main/i18ntk-scanner.js` `fs.readdirSync(projectRoot, { recursive: true })` removed (unsupported in older Node.js).
@@ -491,37 +551,45 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - Fixed `utils/admin-auth.js` `uncaughtException` handler wrong parameter format.
 
 ### Added
+
 - `SecurityUtils.safeUnlinkSync(filePath, basePath)` — safely delete a file.
 - `SecurityUtils.safeRmdirSync(dirPath, basePath)` — safely remove a directory.
 
 ### Changed
+
 - `configManager.resolvePaths`, `configManager.toRelative`, and config lock path now dynamically resolve via `getUserProjectRoot()`/`getProjectConfigPath()`.
 - `configManager.CONFIG_PATH` is now a getter that dynamically returns the project config path.
 - `configManager.migrateLegacyIfNeeded` exported for testability.
 
 ### TypeScript
+
 - Fixed `runtime/i18ntk.d.ts` `BasicI18nRuntime.translate` and `t` return types from `Promise<string>` to `string`.
 
 ### Scripts
+
 - Fixed `scripts/build-public-package.js` and `scripts/reset-release-state.js` `npm_execpath` fallback for missing env var.
 - Fixed `scripts/lint-locales.js` BOM handling and try-catch for `fs.readdirSync`.
 
 ## [2.5.1] - 2026-04-29
 
 ### Security
+
 - Fixed `AdminAuth.verifyPin()` to fail closed when admin config is missing, disabled, or malformed instead of returning success.
 - Fixed auth-required checks to fail closed when settings require admin PIN protection but the admin config is unusable.
 - Normalized admin session expiry handling by storing both `expires` and `expiresAt` and cleaning up both formats consistently.
 
 ### Added
+
 - Added regression tests for admin PIN fail-closed behavior and session expiry cleanup.
 
 ### Changed
+
 - Documented the public npm package staging flow introduced after `2.5.0`.
 
 ## [2.5.0] - 2026-04-29
 
 ### Security
+
 - Centralized environment-variable access behind the `utils/env-manager.js` allowlist.
 - Hardened `SecurityUtils.safeJoin()` and path validation against sibling-prefix containment bypasses.
 - Switched admin PIN hash verification to timing-safe comparison.
@@ -529,17 +597,20 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - Expanded the release security scanner to inspect nested production source files.
 
 ### Fixed
+
 - Fixed the manager fixer command so applied fixes are written to the same parsed object that is saved.
 - Fixed fixer writes for absolute source directories outside the current working directory.
 - Fixed debug-menu file reads to use `SecurityUtils` wrappers.
 - Fixed `secure-errors` to import its `SecurityUtils` dependency explicitly.
 
 ### Changed
+
 - Updated package and documentation metadata to `2.5.0`.
 
 ## [2.4.0] - 2026-04-16
 
 ### Changed
+
 - Disabled npm registry update-check behavior in CLI startup paths.
 - Disabled manager-route backup execution (`i18ntk --command=backup`); standalone `i18ntk-backup` remains available.
 - Disabled setup prerequisite command probing via `PATH` inspection.
@@ -548,6 +619,7 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 ## [2.3.8] - 2026-04-13
 
 ### Added
+
 - Added centralized structured logger with standardized prefixes and configurable levels (`error`, `warn`, `info`, `debug`).
 - Added opt-in JSON log output for CI/build pipelines via `JSON_LOG=true`.
 - Added missing-translation-key cache TTL (5 minutes) to prevent repeated key-miss spam.
@@ -555,11 +627,13 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - Added test coverage for logger timing/progress/worker aggregation behavior.
 
 ### Fixed
+
 - Fixed repeated default-configuration fallback output by emitting a single fallback notice per process.
 - Fixed recursive security/i18n logging interactions that could trigger repeated warning cascades.
 - Fixed false-positive security warnings for internal package/project absolute paths through internal root whitelisting.
 
 ### Changed
+
 - Logging is now silent by default for non-critical output in production-like builds unless `DEBUG_MODE=true`.
 - Security warning reasons now use specific detection details instead of generic "dangerous patterns".
 - Updated package/docs/version metadata to `2.3.8`.
@@ -567,10 +641,12 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 ## [2.3.7] - 2026-04-12
 
 ### Fixed
+
 - Removed false-positive path traversal warnings for safe absolute project paths during framework builds.
 - Reduced repeated default-configuration console noise in multi-worker build environments.
 
 ### Changed
+
 - Security event console logging is now fully opt-in via `I18NTK_ENABLE_SECURITY_LOGS=true` (or debug envs).
 - Config-manager diagnostic console logging is now fully opt-in via `I18NTK_ENABLE_LOGS=true` (or debug envs).
 - Updated docs to reflect new default-silent logging behavior and troubleshooting toggles.
@@ -578,16 +654,19 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 ## [2.3.6] - 2026-04-12
 
 ### Security
+
 - **Fixed path traversal vulnerability** in temporary file creation
 - **Added `safeJoin` function** for secure path construction
 - **Improved path validation** throughout the codebase
 
 ### Fixed
+
 - Hardened settings reset and backup cleanup paths to reduce risk of broad/deep unintended file deletion.
 - Hardened backup command path handling to keep source/output/restore operations inside project boundaries by default.
 - Fixed backup-class async file operations to consistently use `fs.promises` APIs.
 
 ### Changed
+
 - **Silent security logging by default**: Info-level messages suppressed, warnings/errors shown
 - **Debug mode**: Enable verbose logging with `I18N_DEBUG=true`
 - **Centralized security logging**: All security events use `SecurityUtils.logSecurityEvent()`
@@ -597,76 +676,92 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 ## [2.3.4] - 2026-04-12
 
 ### Fixed
+
 - Fixed runtime autosave behavior so configuration write failures no longer hard-throw through request/render paths.
 - Fixed config save race resilience by combining queued writes, cross-process lock files, and unique temp filenames per write.
 
 ### Added
+
 - Added `I18NTK_DISABLE_AUTOSAVE` support to skip disk persistence and keep in-memory config in server/runtime environments.
 - Added config-manager concurrency regression test covering parallel `saveConfig` calls.
 
 ### Changed
+
 - Updated package/docs/version metadata to `2.3.4`.
 - Updated support policy guidance to recommend upgrading from versions below `2.3.4`.
 
 ## [2.3.3] - 2026-04-12
 
 ### Fixed
+
 - Fixed production config persistence race across multiple Node processes by adding cross-process file locking for `.i18ntk-config` writes.
 - Fixed intermittent `ENOENT` during atomic config rename operations under concurrent production traffic.
 
 ### Changed
+
 - Updated package/docs/version metadata to `2.3.3`.
 - Updated support policy guidance to recommend upgrading from versions below `2.3.3`.
 
 ## [2.3.2] - 2026-04-12
 
 ### Added
+
 - Added startup npm-registry version checks that warn when the installed CLI is behind the latest published `i18ntk` release.
 - Added support for checking all published semver versions up to the current latest tag to improve outdated-version detection reliability.
 
 ### Fixed
+
 - Fixed fatal analyze-command startup failure in manager command flow caused by missing `validateSourceDir` import.
 
 ### Changed
+
 - Updated package/docs/version metadata to `2.3.2`.
 - Updated support policy guidance to recommend upgrading from versions below `2.3.2`.
 
 ## [2.3.1] - 2026-04-12
 
 ### Fixed
+
 - Fixed package export-path fallback in `utils/i18n-helper` that could trigger build warnings in production bundlers (`i18ntk/resources/i18n/ui-locales/en.json` not exported).
 
 ### Changed
+
 - Updated package/docs/version metadata to `2.3.1`.
 - Updated support policy guidance to recommend upgrading from versions below `2.3.1`.
 
 ## [2.3.0] - 2026-04-12
 
 ### Added
+
 - Added validation summary report output after validation runs.
 - Added init-time backup configuration prompt (default disabled, optional enable).
 
 ### Fixed
+
 - Fixed backup recursion/pollution risk by moving automated fixer backups to a dedicated backup root.
 - Fixed backup retention behavior to keep 1 by default with enforced bounds up to 3.
 - Fixed language discovery in validate/fixer flows to ignore backup/report directories.
 
 ### Changed
+
 - Updated package/docs/version metadata to `2.3.0`.
 - Updated support policy guidance to recommend upgrading from versions below `2.3.0`.
 
 ## [2.2.0] - 2026-04-12
 
 ### Added
+
 - Added an explicit upgrade/support notice in docs recommending upgrade from pre-`2.2.0` versions.
 - Added migration guide for `v2.2.0`.
 
 ### Fixed
+
 - Fixed critical sizing workflow regressions.
 - Fixed critical usage-analysis workflow regressions.
 - Fixed runtime locale optimizer dependency path after publish-surface cleanup.
 
 ### Changed
+
 - Reduced publish surface by excluding internal development scripts from npm package artifacts.
 - Excluded legacy fixed artifacts from package output (`main/manage/index-fixed.js`, `utils/security-fixed.js`).
 - Updated package/docs/version metadata to `2.2.0`.
@@ -674,15 +769,18 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 ## [2.1.1] - 2026-04-11
 
 ### Added
+
 - Version bump to 2.1.1 for release.
 - Added `SecurityUtils.debugLog` function for consistent debugging.
 
 ### Fixed
+
 - Fixed `SecurityUtils.logSecurityEvent` calls missing `level` parameter in `i18ntk-usage` and `UsageService`.
 - Fixed `level.toLowerCase is not a function` error in usage analysis.
 - Fixed `SecurityUtils.debugLog is not a function` error in sizing analysis.
 
 ### Changed
+
 - Updated package and release metadata to `2.1.1`.
 - Removed legacy `resources/i18n/ui-locales` path references (use `ui-locales/` instead).
 - Updated all UI locale loading to use `ui-locales/` directory.
@@ -690,10 +788,12 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 ## [2.1.0] - 2026-04-11
 
 ### Added
+
 - Added a v2.1.0 migration guide and updated release runbook references.
 - Added stricter language-directory filtering in analysis paths to ignore backup/report folders.
 
 ### Fixed
+
 - Fixed interactive menu command flow so it reliably returns to the main menu after command completion.
 - Fixed analysis progress output to report the correct processed-language count.
 - Fixed duplicate report-save output lines during analysis.
@@ -702,70 +802,84 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - Fixed locale-loading path fallback behavior to avoid noisy startup errors in global installs.
 
 ### Changed
+
 - Synchronized and normalized UI locale keys across `resources/i18n/ui-locales` and `ui-locales`.
 - Updated package/release metadata to `2.1.0`.
 
 ## [2.0.0] - 2026-01-01
 
 ### Added
+
 - Added missing runtime translation keys across `init`, `fixer`, `sizing`, `summary`, `usage`, and settings import/export flows.
 - Added `SecurityUtils.safeParseJSON`, `SecurityUtils.safeReadFile`, and `SecurityUtils.safeWriteFile` compatibility APIs used by v2 command paths.
 - Added source-locale bootstrap behavior during `init` when the source language directory exists but has no translation files.
 
 ### Fixed
+
 - Fixed initialization state detection to use project `.i18ntk-config` setup metadata as the v2 source of truth.
 - Fixed false setup-invalid states caused by BOM-encoded config files during setup checks.
 - Fixed config persistence risk by using atomic writes in `config-manager` save flow.
 - Fixed self-dependency metadata so the package remains zero-dependency in v2.
 
 ### Changed
+
 - Updated package release metadata for the v2 line (`versionInfo`, deprecations, nextVersion).
 
 ## [1.10.2] - 2025-08-23
 
 ### 🚨 Critical Fix
+
 - **Fixed projectRoot default path**: Resetting settings now correctly restores `projectRoot` to `/` instead of `./`, ensuring fresh installs work out-of-the-box
 
 ### 🆕 New Features
+
 - **Centralized Environment Variable Management**: Added comprehensive environment variable support with validation and security controls
 - **Enhanced Debug Logging**: Improved debug logging with environment variable support for better troubleshooting
 - **Secure Plugin Loading**: Added path sanitization for module loading to prevent security issues
 
 ### 🔒 Security Enhancements
+
 - **Enhanced Path Validation**: Strengthened path validation and file operations security
 - **Secure Module Loading**: Added path sanitization for all plugin/module loading operations
 - **Environment Variable Security**: Implemented centralized environment variable management with security filtering
 
 ### 🛠️ Improvements
+
 - **Refactored Configuration Handling**: Updated config system with integrated environment variable support
 - **Enhanced Logging System**: Improved debug logging capabilities with environment variable integration
 - **Better Error Handling**: Enhanced error messages and debugging information
 
 ### 📚 Documentation
+
 - **Environment Variables Guide**: Added comprehensive documentation for all supported environment variables
 - **Migration Notes**: Added clear migration guidance for projectRoot path changes
 
 ### 🔧 Technical Changes
+
 - **Package Version**: Updated to v1.10.2 across all files
 - **Security Patches**: Applied security improvements to path handling and file operations
 
 ## [1.10.1] - 2025-08-22
 
 ### Added
+
 - **New Terminal-Icons Utility**: Added `terminal-icons` utility for better emoji support in terminal output
 - **Enhanced UI Text Processing**: Improved text processing with terminal-safe fallbacks for special characters
 
 ### Fixed
+
 - Fixed infinite setup loop issue (Hotfix)
 - Resolved version string update inconsistencies
 
 ### Changed
+
 - Update version strings across all files from 1.9.1 to 1.10.1
 - Remove outdated package-lock.json and backup config
 
 ## [1.10.0] - 2025-08-22
 
 ### Added
+
 - **Enhanced Runtime API**: Improved framework-agnostic translation runtime with better TypeScript support
 - **Framework Detection**: Enhanced support for Next.js, Nuxt.js, and SvelteKit projects
 - **Reset Script**: Added `reset-for-publish.js` for clean package publishing
@@ -774,6 +888,7 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - **Caching System**: Added configuration caching to prevent redundant initialization
 
 ### Fixed
+
 - **DNR Functionality**: Fixed persistence of "Do Not Remind" settings across version updates
 - **Settings Management**: Improved error handling and logging for settings operations
 - **TypeScript Definitions**: Enhanced type safety and autocomplete for better developer experience
@@ -783,17 +898,17 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - **Path Resolution**: Fixed source directory path handling for CLI arguments
 
 ### Security
+
 - **Settings Persistence**: Secure handling of user preferences and framework settings
 - **Error Handling**: Improved error reporting for configuration issues
 - **Dependencies**: Maintained zero runtime dependencies for maximum security
 - **Shell Access**: Confirmed no child_process usage in setup-enforcer.js
 - **Input Validation**: Enhanced path validation for source and output directories
 
-
-
 ## [1.9.1] - 2025-08-14
 
 ### Added
+
 - **Python Support**: Full support for Python frameworks including Django, Flask, FastAPI, and generic Python projects
 - **Enhanced Framework Detection**: Improved accuracy for all supported frameworks with new Python detection algorithms
 - **Common Locale File**: Added `locales/common.json` for shared translation keys across frameworks
@@ -801,6 +916,7 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - **Exit/Cancel Option**: Added option to exit/cancel (press 0) during directory selection in fixer command
 
 ### Changed
+
 - **Security Overhaul**: Replaced all `child_process` imports with native Node.js APIs
 - **Performance**: Maintained 97% performance improvement while adding security enhancements
 - **Framework Detection**: Updated detection patterns for JavaScript, Python, Go, Java, and PHP
@@ -808,18 +924,21 @@ The v3.3.0 release resolves the actionable dynamic-require alert by eliminating
 - **Documentation**: Comprehensive updates to reflect new features and security improvements
 
 ### Removed
+
 - **Outdated Test Files**: Cleaned up test directories and removed deprecated test scripts
 - **Debug Tools**: Removed unused benchmark and package test files
 - **Shell Dependencies**: Eliminated all shell command dependencies
 - **Legacy Files**: Removed outdated configuration and development files
 
 ### Security
+
 - **Zero Vulnerabilities**: Successfully passed security audit with 0 vulnerabilities
 - **Memory Safety**: Enhanced memory-safe operations throughout the codebase
 - **Input Validation**: Improved validation for all user inputs and file operations
 - **Dependency Cleanup**: Removed all shell-related dependencies
 
 ### Performance
+
 - **Zero Overhead**: Security enhancements added zero performance overhead
 - **Python Detection**: Minimal overhead from new Python framework detection
 - **Memory Usage**: Maintained <2MB memory usage for all operations

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v4.5.2
+# i18ntk v4.5.3
 
 A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
 
@@ -9,7 +9,7 @@ A zero-dependency internationalization toolkit for setup, scanning, analysis, va
 [![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/4.5.2)](https://socket.dev/npm/package/i18ntk/overview/4.5.2)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.5.3)](https://socket.dev/npm/package/i18ntk/overview/4.5.3)
 
 [![i18ntk Workbench](https://img.shields.io/badge/VS_Code-i18ntk_Workbench-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-workbench)
 [![i18ntk Lens](https://img.shields.io/badge/VS_Code-i18ntk_Lens-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-lens)
@@ -64,6 +64,10 @@ i18next is mainly a runtime internationalization library. i18ntk is mainly workf
 | Validation reports        | Yes           | Limited          |
 | Auto-translation workflow | Yes           | External tooling |
 
+## What's New in 4.5.3
+
+- **TSX/JSX SCANNING**: `supportedExtensions` default now includes `.tsx` and `.jsx`. Previously excluded from source scanning, causing React/Next.js projects to miss 97%+ of translation keys.
+
 ## What's New in 4.5.2
 
 - The `complete` command now correctly inserts missing keys at the right nesting level when target locale files have namespace wrappers (e.g., `auth.json` containing `{ "auth": { ... } }`). Keys inside `auth.panel.sign_in` now go inside the `auth` wrapper, not at root level.
@@ -542,7 +546,7 @@ Example:
 
 ```json
 {
-  "version": "4.5.2",
+  "version": "4.5.3",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",

package/main/i18ntk-usage.js

@@ -195,7 +195,7 @@ class I18nUsageAnalyzer {
         this.config.excludeDirs = ['node_modules', '.git'];
       }
       if (!Array.isArray(this.config.includeExtensions) && !Array.isArray(this.config.supportedExtensions)) {
-        this.config.includeExtensions = ['.js', '.jsx', '.ts', '.tsx', '.py', '.pyx', '.pyi'];
+        this.config.includeExtensions = ['.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte', '.py', '.pyx', '.pyi'];
       }
       
       await SecurityUtils.logSecurityEvent(t('usage.analyzerInitialized'), 'info', { component: 'i18ntk-usage' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18ntk",
-  "version": "4.5.2",
+  "version": "4.5.3",
   "description": "i18n Tool Kit - Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, auto translation, fixing, reporting, and runtime translation loading.",
   "readmeFilename": "README.md",
   "keywords": [
@@ -179,7 +179,7 @@
   },
   "preferGlobal": true,
   "versionInfo": {
-    "version": "4.5.2",
+    "version": "4.5.3",
     "releaseDate": "05/06/2026",
     "lastUpdated": "06/19/2026",
     "maintainer": "Vlad Noskov",
@@ -215,7 +215,7 @@
       "i18ntk/runtime module-level helpers keep the first initialized runtime configuration for compatibility instead of being overwritten by later initRuntime() calls.",
       "utils/watch-locales.js returns a callable watcher object with EventEmitter methods and stop(); existing bare stop-function usage remains supported."
     ],
-    "nextVersion": "4.5.3",
+    "nextVersion": "4.5.4",
     "supportedNodeVersions": ">=16.0.0",
     "supportedFrameworks": {
       "react-i18next": ">=11.0.0",
@@ -237,18 +237,18 @@
       "spring-boot": ">=2.5.0",
       "laravel": ">=8.0.0"
     },
-    "supportPolicy": "Versions earlier than 4.4.1 may be unstable or insecure. Upgrade to 4.5.2 or newer.",
+    "supportPolicy": "Versions earlier than 4.4.1 may be unstable or insecure. Upgrade to 4.5.3 or newer.",
     "deprecations": [
       "4.3.0",
       "4.3.1",
       "4.3.2",
       "4.3.3"
     ],
-    "deprecationMessage": "i18ntk 4.3.x and earlier have known security vulnerabilities (path traversal, JSON DoS). Upgrade to i18ntk@4.5.2 or newer: npm install -g i18ntk@latest",
+    "deprecationMessage": "i18ntk 4.3.x and earlier have known security vulnerabilities (path traversal, JSON DoS). Upgrade to i18ntk@4.5.3 or newer: npm install -g i18ntk@latest",
     "securityAdvisories": [
       "GHSA-i18ntk-4.3.x-path-traversal: Backup command accepted arbitrary paths without validation (fixed in 4.4.1)",
       "GHSA-i18ntk-4.3.x-json-dos: Deeply nested JSON files could cause denial of service (fixed in 4.4.1)"
     ]
   },
-  "readme": "# i18ntk v4.5.2\n\nA zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.\n\n![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)\n\n[![npm version](https://img.shields.io/npm/v/i18ntk.svg?color=brightgreen)](https://www.npmjs.com/package/i18ntk)\n[![npm downloads](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)\n[![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)\n[![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)\n[![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.5.2)](https://socket.dev/npm/package/i18ntk/overview/4.5.2)\n\n[![i18ntk Workbench](https://img.shields.io/badge/VS_Code-i18ntk_Workbench-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-workbench)\n[![i18ntk Lens](https://img.shields.io/badge/VS_Code-i18ntk_Lens-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-lens)\n\n## The i18ntk ecosystem\n\n- i18ntk — CLI and runtime toolkit\n- i18ntk Workbench — full VS Code dashboard and reports\n- i18ntk Lens — inline hovers, CodeLens, and diagnostics\n\nUse the CLI in CI, Workbench for project-level management, and Lens for day-to-day editor feedback.\n\n## Install\n\n```bash\n# global CLI use\nnpm install -g i18ntk\n\n# local project use\nnpm install --save-dev i18ntk\n\n# one-off execution\nnpx i18ntk --help\n```\n\n## i18ntk Summary\n\n**What it does**\n\n- Manages locale files from the command line.\n- Finds missing, unused, risky, and inconsistent translation keys.\n- Produces validation and summary reports.\n- Supports framework-aware i18n workflows.\n- Provides a lightweight runtime translation toolkit.\n\n**What it does not do**\n\n- It is not a translation management SaaS.\n- It does not replace human translation review.\n- It does not force you to replace i18next, react-i18next, vue-i18n, or another runtime.\n\n**Why not i18next?**\n\ni18next is mainly a runtime internationalization library. i18ntk is mainly workflow tooling around translation files. They can work together: i18next handles runtime translation, while i18ntk handles setup, scanning, validation, reporting, and maintenance.\n\n| Need                      | i18ntk        | i18next          |\n| ------------------------- | ------------- | ---------------- |\n| Runtime translation       | Basic toolkit | Mature runtime   |\n| Locale file scanning      | Yes           | No               |\n| Missing key detection     | Yes           | No               |\n| Unused key detection      | Yes           | No               |\n| Validation reports        | Yes           | Limited          |\n| Auto-translation workflow | Yes           | External tooling |\n\n## What's New in 4.5.2\n\n- The `complete` command now correctly inserts missing keys at the right nesting level when target locale files have namespace wrappers (e.g., `auth.json` containing `{ \"auth\": { ... } }`). Keys inside `auth.panel.sign_in` now go inside the `auth` wrapper, not at root level.\n- Fixed `complete` command: missing keys now inserted inside namespace wrapper when file has top-level key matching filename (e.g., auth.json with `{ \"auth\": … }`).\n- Fixed `translate --output-dir`: output now placed in `<outputDir>/<targetLang>/<filename>`, preventing language overwrites.\n- Enhanced `scanner` and `report-model` to filter out JS built-in type names (e.g., Promise, Boolean) and code expressions (e.g., `&&`, `${…}`) from hardcoded text detection.\n\n## What's New in 4.5.1\n\n- **CORRECT COMPLETENESS**: Validation now shows accurate completion percentages vs source locale (e.g., 33% instead of misleading 100%).\n- **NO MORE PARENT KEYS**: `getAllKeys()` no longer reports parent namespace objects (`footer`) as missing keys alongside their leaf children (`footer.copyright`).\n- **DOCTOR SMARTER**: No longer flags unconfigured languages (`de`, `ru`) as issues. Auto-detects available languages from the i18n directory structure.\n- **SCANNER FIXED**: Scanner now correctly scans `src/` directory for hardcoded text, not `locales/`.\n- **RUNTIME ALIASES**: `initRuntime()` now supports `localeDir`/`targetLocale`/`sourceLocale` as aliases for `baseDir`/`language`/`fallbackLanguage`.\n\n## What's New in 4.5.0\n\n- **PROTOTYPE POLLUTION HARDENED**: Three layers of defense added — `readJsonSafe()` now recursively strips `__proto__`, `constructor`, and `prototype` keys from all parsed JSON; `deepMerge()` in the runtime blocks these keys during locale merging; `mergeWithDefaults()` in settings-manager filters them from user settings.\n- **BACKUP FIXED**: All backup operations (create, restore, list, verify, cleanup) now work. A duplicate `sourceDir` declaration that caused a SyntaxError at module load has been removed. Corrupt backup files are now handled gracefully with descriptive error messages.\n- **COMPLETE COMMAND FIXED**: `i18ntk-complete` no longer crashes with `getUnifiedConfig is not defined`. The missing config-helper import has been added.\n- **MALFORMED JSON HANDLING**: Report generation now gracefully skips malformed JSON files with a warning instead of aborting the entire report.\n- **NULL SAFETY**: `stripBOMAndComments()` in i18n-helper now handles null/undefined inputs without throwing.\n- **ERROR HANDLING HARDENED**: Lazy-load failures in runtime now log to console when `I18NTK_DEBUG` is set. Settings save errors are now re-thrown instead of silently swallowed. Legacy config migration has proper error handling.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for more release details.\n\n## Quick Start\n\nInitialize a project:\n\n```bash\ni18ntk\n# or with explicit command\ni18ntk --command=init\n```\n\nRun common checks:\n\n```bash\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk report --json\ni18ntk --command=sizing\ni18ntk --command=summary\n```\n\nComplete or fix translation files:\n\n```bash\ni18ntk --command=complete\ni18ntk-fixer --help\n```\n\nAuto-translate locale JSON:\n\n```bash\ni18ntk --command=translate\n# or\ni18ntk-translate locales/en/common.json de --report-stdout\n```\n\nThe full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).\n\n## Main Commands\n\nPrimary CLI:\n\n```bash\ni18ntk\ni18ntk --help\ni18ntk --command=init\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk report --json --markdown --html --out ./i18ntk-reports\ni18ntk --command=scanner\ni18ntk --command=sizing\ni18ntk --command=complete\ni18ntk --command=translate\ni18ntk --command=summary\n```\n\nStandalone executables:\n\n```bash\ni18ntk-init\ni18ntk-analyze\ni18ntk-validate\ni18ntk-usage\ni18ntk-report\ni18ntk-scanner\ni18ntk-sizing\ni18ntk-complete\ni18ntk-summary\ni18ntk-doctor\ni18ntk-fixer\ni18ntk-backup\ni18ntk-translate\n```\n\nNote: manager route `i18ntk --command=backup` is available via the interactive menu. Use `i18ntk-backup` directly for scripted backup operations.\n\n## Command Reference\n\n| Command                                           | What it does                                                                                                 | Looks for                                                                                                                                                                            | Writes or changes                                                                                                                                                                                                                           |\n| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `i18ntk`                                          | Opens the interactive management menu.                                                                       | Project config, setup state, available commands.                                                                                                                                     | Only changes files after you choose a command that writes.                                                                                                                                                                                  |\n| `i18ntk --command=init` / `i18ntk-init`           | Sets up locale folders and missing target-language files.                                                    | Source language files and selected target languages.                                                                                                                                 | Locale JSON files, `.i18ntk-config`, optional reports/backups.                                                                                                                                                                              |\n| `i18ntk --command=analyze` / `i18ntk-analyze`     | Compares source and target translation coverage.                                                             | Missing keys, extra keys, untranslated markers, completion by language.                                                                                                              | Markdown/JSON/text reports when report output is enabled.                                                                                                                                                                                   |\n| `i18ntk --command=validate` / `i18ntk-validate`   | Validates structure and translation quality risks.                                                           | Placeholder mismatches, missing keys, risky URLs/emails/secrets, likely English target text.                                                                                         | Validation summary report. Does not edit locale files.                                                                                                                                                                                      |\n| `i18ntk --command=usage` / `i18ntk-usage`         | Maps translation keys to source files and finds unused/missing keys.                                         | Direct i18n calls, literal known-key references, bounded dynamic templates/object maps, unresolved dynamic expressions, hardcoded text candidates, namespace/file naming mismatches. | Usage report with key locations, namespace recommendations, unresolved dynamic expressions, hardcoded text suggestions, and optional dead-key report. Does not delete unless cleanup deletion is explicitly enabled.                        |\n| `i18ntk report` / `i18ntk-report`                 | Generates the stable schemaVersion 1 report used by CLI automation and i18ntk Workbench.                     | Locale completeness, missing keys, unused keys with confidence, placeholders, likely untranslated values, expansion risk, and hardcoded text candidates.                             | JSON to stdout by default, plus JSON/Markdown/HTML files when `--out` is used. Does not edit locale files.                                                                                                                                  |\n| `i18ntk --command=scanner` / `i18ntk-scanner`     | Scans source for i18n issues and hardcoded user-facing text.                                                 | JSX/template text, common text attributes, i18n usage patterns, source-language text profiles.                                                                                       | Scanner report. Does not edit files.                                                                                                                                                                                                        |\n| `i18ntk --command=complete` / `i18ntk-complete`   | Adds missing keys to target language files for 100% key coverage.                                            | Source-language keys missing from targets.                                                                                                                                           | Target locale JSON files, using missing translation markers/prefixes.                                                                                                                                                                       |\n| `i18ntk --command=translate` / `i18ntk-translate` | Auto-translates locale JSON using configured provider behavior.                                              | Missing, empty, untranslated-marker, source-copy, likely-English, or visibly corrupt target values by default.                                                                       | Target locale JSON files and translation reports. Existing translated values are kept unless `--translate-all` is used. If unresolved values remain after retry, writes `i18ntk-reports/auto-translate/latest.json` for targeted follow-up. |\n| `i18ntk --command=sizing` / `i18ntk-sizing`       | Estimates translated string length expansion and layout risk.                                                | Text length, expansion ratios, placeholder-bearing strings.                                                                                                                          | Sizing report. Does not edit locale files.                                                                                                                                                                                                  |\n| `i18ntk --command=summary` / `i18ntk-summary`     | Shows project translation status.                                                                            | Configured locales, reports, completeness status.                                                                                                                                    | Console/report output only.                                                                                                                                                                                                                 |\n| `i18ntk-fixer`                                    | Fixes placeholder and missing-marker issues, and can audit English source files with `--check-placeholders`. | Placeholder corruption, missing translation markers, configured language files, `[LANG] ...` leftovers in English locales.                                                           | Locale JSON files when fixes are applied. Use dry-run options where available before bulk edits.                                                                                                                                            |\n| `i18ntk-backup`                                   | Creates, verifies, restores, and cleans locale backups.                                                      | Locale JSON files and backup manifests.                                                                                                                                              | Backup archives/manifests, or restored locale files when using restore.                                                                                                                                                                     |\n\n## Common Options\n\nMany commands support:\n\n- `--source-dir <path>`\n- `--i18n-dir <path>`\n- `--output-dir <path>`\n- `--source-language <code>`\n- `--ui-language <code>`\n- `--no-prompt`\n- `--help`\n\nCommand-specific tools add their own flags such as `--dry-run`, `--output-report`, `--cleanup`, `--predict-expansion`, or Auto Translate provider options.\n\nExample:\n\n```bash\ni18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports\n```\n\n## Auto Translate\n\nInteractive manager flow:\n\n```bash\ni18ntk\n# choose \"Auto Translate\"\n```\n\nDirect CLI examples:\n\n```bash\ni18ntk-translate locales/en/common.json de\ni18ntk-translate locales/en/common.json fr --dry-run --report-stdout\ni18ntk-translate locales/en es --source-dir locales/en --files \"*.json\" --no-confirm --preserve-placeholders\n```\n\nProvider examples:\n\n```bash\nexport DEEPL_API_KEY=\"your-deepl-api-key\"\ni18ntk-translate locales/en/common.json de --provider deepl --no-confirm --preserve-placeholders\n\nexport LIBRETRANSLATE_URL=\"https://libretranslate.com/translate\"\nexport LIBRETRANSLATE_API_KEY=\"optional-api-key\"\ni18ntk-translate locales/en/common.json es --provider libretranslate --no-confirm --preserve-placeholders\n```\n\n`google` remains the default provider. You can also set `I18NTK_TRANSLATE_PROVIDER=deepl` or `I18NTK_TRANSLATE_PROVIDER=libretranslate`.\n\nProvider 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.\n\nThe manager flow asks for:\n\n- source locale directory, either the folder with JSON files or a locale root such as `./locales`\n- source language code\n- one or more target languages, or `all`\n- one JSON file or all JSON files in the source directory\n\nIf you select a locale root such as `./locales` and choose source language `en`, the manager automatically uses `./locales/en` when that folder contains the source JSON files.\n\nBefore writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:\n\n```text\nlocales/en/common.json\nlocales/de/common.json\nlocales/fr/common.json\n```\n\nAuto Translate is target-aware by default. When a target file already exists, it keeps translated target values and only sends values that are missing, empty, marked as untranslated, still identical to the source, likely still English, or visibly corrupt from encoding damage such as `?????`, replacement characters, or common mojibake. Use `--translate-all` when you intentionally want to re-translate every source string.\n\n### Placeholder Handling\n\nAuto Translate detects common placeholders such as:\n\n- `{name}`\n- `{{count}}`\n- `%s`\n- `%d`\n- `:id`\n- `%{name}`\n- `${value}`\n- `{count, plural, one {# item} other {# items}}`\n- `$t(common.save)`\n- `%(total).2f`\n\nUseful flags:\n\n- `--preserve-placeholders`: translate text around placeholders and reinsert original tokens\n- `--skip-placeholders`: copy placeholder-bearing strings unchanged\n- `--send-placeholders`: send placeholder-bearing strings through translation after masking\n- `--custom-regex <regex>`: add project-specific placeholder detection\n- `--only-missing`: keep existing translated target values and translate only missing/source-copy/likely English values (default)\n- `--translate-all`: re-translate every source string\n\nProgress output is stage-aware for large files. Normal keys are reported as `Translating strings`, while preserve-mode placeholder work is reported as `Translating placeholder-safe text segments`; each progress update includes the current key path when available.\n\n### Protected Terms and Keys\n\nAuto Translate can create and use a project-local protection file:\n\n```bash\ni18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json\n```\n\nExample `i18ntk-auto-translate.json`:\n\n```json\n{\n  \"version\": 1,\n  \"terms\": [\n    \"BrandName\",\n    \"PRODUCT_CODE\",\n    { \"value\": \"OK\", \"context\": \"after:Click|Press|Tap\" },\n    { \"value\": \"API\", \"context\": \"standalone\" }\n  ],\n  \"keys\": [\"app.brandName\", \"legal.companyName\", \"product.*.symbol\"],\n  \"values\": [\"BrandName Ltd\", \"support@example.com\"],\n  \"patterns\": [\"[A-Z]{2,}-\\\\d+\"]\n}\n```\n\n- `terms` are masked before translation and restored exactly afterward.\n  - **Plain strings**: masked everywhere (backward compatible).\n  - **Context objects**: masked only in specific contexts (`after:word`, `before:word`, `standalone`, `surrounded:left,right`).\n- `keys` are exact key paths or `*` wildcard paths copied unchanged.\n- `values` are exact source values copied unchanged.\n- `patterns` are JavaScript regex strings for advanced protected substrings.\n\nUseful flags:\n\n- `--protection-file <path>`\n- `--create-protection-file`\n- `--no-protection`\n\nOpen Settings and choose `Auto Translate` to edit defaults for placeholder mode, translate-only-needed mode, concurrency, batch size, retry settings, report output, BOM output, protection file path, first-run setup prompt, and update prompt.\n\nSee [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.\n\n## Validation\n\nValidation checks locale structure, completeness, placeholders, and content risks.\n\nValidation warning types are specific:\n\n- `Potential risky content`: URL, email address, or secret-like value\n- `Possible untranslated English content`: target-language value appears to contain too much English\n\nEnglish-content warnings include:\n\n- detected English percentage\n- configured threshold\n- matched word count\n- sample matched words\n\nTune warnings in `.i18ntk-config`:\n\n```json\n{\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"]\n}\n```\n\n## Sizing Analysis\n\n`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.\n\n```bash\ni18ntk-sizing --source-dir ./locales --format table\ni18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports\n```\n\nUse `--detailed` to print per-file rows in the terminal.\n\n### Expansion Prediction (New in 4.0.0)\n\nPredict UI layout overflow risk by analyzing per-key character-count expansion across languages:\n\n```bash\ni18ntk-sizing --source-dir ./locales --predict-expansion --output-report\n```\n\nExpansion ratios are classified into risk tiers:\n\n- **Safe** (<30% expansion): no UI impact expected\n- **Warning** (30–50%): may overflow in tight layouts — test on target languages\n- **Critical** (>50%): high risk of truncation — review UI element sizing\n\nThe report includes a built-in language-pair expansion reference table (EN→DE +35%, EN→RU +50%, EN→JA −40%, etc.) and lists the top-30 most-expanded keys.\n\n## Scanner: Multi-Language Detection (New in 4.0.0)\n\n`i18ntk-scanner` now supports detecting hardcoded text in multiple source languages beyond English:\n\n```bash\ni18ntk-scanner --source-dir ./src --source-language de\ni18ntk-scanner --source-dir ./src --source-language ja --output-report\n```\n\nSupported language profiles (12+): English, German, French, Spanish, Japanese, Chinese, Russian, Korean, Arabic, Hindi, and more. Each profile includes language-specific character ranges, stopword lists for false-positive filtering, and transliteration rules for key generation.\n\n## Usage: Dead Key Detection (New in 4.0.0)\n\n`i18ntk-usage` can identify translation keys that are defined but never referenced in source code:\n\n```bash\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup --dry-run-delete\n```\n\nEach dead key receives a confidence score (0.0–1.0) factoring:\n\n- Unresolved dynamic key patterns (e.g., ``t(`prefix.${dynamic}`)``) — lower score and listed in the usage report; simple consts, bounded arrays, object maps, and ternaries are expanded to exact keys where possible\n- Key appears in source code comments or JSDoc — medium score\n- Parent file recently modified (<30 days) — medium score\n- No references found anywhere — high score (>0.8)\n\nThe `--dry-run-delete` flag writes a `.dead-keys.json` report for review before any destructive action.\n\n## Validator: Key Naming Conventions (New in 4.0.0)\n\nEnforce consistent translation key naming across your project:\n\n```bash\ni18ntk-validate --enforce-key-style\n```\n\nConfigure the expected style in `.i18ntk-config`:\n\n```json\n{\n  \"keyStyle\": \"dot.notation\"\n}\n```\n\nSupported styles: `dot.notation`, `snake_case`, `camelCase`, `kebab-case`, `flat`. Violations are reported as warnings with suggested canonical forms.\n\n## Watch: Hot Reload (New in 4.0.0)\n\n`utils/watch-locales.js` now provides debounced file watching with EventEmitter support:\n\n```js\nconst watchLocales = require('i18ntk/utils/watch-locales');\nconst watcher = watchLocales('./locales');\n\nwatcher.on('change', (filePath) => {\n  console.log('Locale changed:', filePath);\n});\n\nwatcher.on('add', (filePath) => {\n  console.log('Locale added:', filePath);\n});\n\n// Later:\nwatcher.stop();\n```\n\nFeatures: 300ms debounce (configurable), SHA-256 hash tracking to skip no-change saves, and a maximum of 50 watched directories.\n\n### Migration\n\nThe `watchLocales` return value gained EventEmitter methods in v4.0.0. Existing stop-function usage still works:\n\n```js\nconst stop = watchLocales('./locales', onChange);\n```\n\nCan be updated to:\n\n```js\nconst watcher = watchLocales('./locales');\nwatcher.on('change', onChange);\nwatcher.stop();\n```\n\nPassing a callback as the second argument is still supported — it auto-subscribes to `change` and `add` events.\n\n## Backup: Incremental Mode (New in 4.0.0)\n\nCreate differential backups that only include changed files:\n\n```bash\ni18ntk-backup create ./locales --incremental\n```\n\nIncremental backups store SHA-256 hashes per file and a parent-chain reference. Restoring an incremental backup automatically chains from the oldest full backup through each incremental diff in order. Chain depth is capped at 10 increments. Use `verify` to validate the hash chain.\n\n## Runtime: Lazy Loading (New in 4.0.0)\n\nReduce memory usage by deferring locale file loads until first key access:\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  lazy: true,\n});\n\nconsole.log(i18n.t('common.hello')); // loads common.json on first access\n```\n\nWhen `lazy: true`, the runtime builds a key-to-file manifest on first access and loads individual files on demand. Files are loaded once and cached. If the manifest is missing or incomplete, the runtime falls back to full eager loading for that language. Manifest size is capped at 100KB with path containment validation.\n\nProduction guidance:\n\n- Prefer the object returned from `initRuntime()` instead of module-level `runtime.t()` in apps with multiple tenants, projects, or locale roots.\n- Use `lazy: true` for large modular locale folders where lower steady-state memory matters more than a small first-key lookup cost.\n- Use `preload: true` without `lazy` for small locale sets or latency-sensitive startup paths.\n- Call `refresh(language)` after deploying or writing changed locale files so cached data and lazy manifests are rebuilt.\n- Use per-call language overrides when rendering one-off alternate-language strings: `i18n.t('common.hello', {}, { language: 'de' })`.\n- Use `translateBatch()` for small groups of labels and `clearCache()` / `getCacheInfo()` for cache maintenance and diagnostics.\n- `i18ntk/runtime/enhanced` remains available for compatibility with existing async/encryption users, but new production integrations should start with `i18ntk/runtime`.\n\n## Runtime API\n\nUse `i18ntk/runtime` when an application needs to read locale JSON files at runtime.\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  fallbackLanguage: 'en',\n  keySeparator: '.',\n  preload: true,\n});\n\nconsole.log(i18n.t('common.hello'));\ni18n.setLanguage('fr');\nconsole.log(i18n.getLanguage());\nconsole.log(i18n.getAvailableLanguages());\ni18n.refresh('fr');\n```\n\nUseful production helpers:\n\n```js\ni18n.t('common.hello', {}, { language: 'de' }); // per-call language override\ni18n.translateBatch(['menu.home', 'menu.settings']);\ni18n.clearCache('fr');\nconsole.log(i18n.getCacheInfo());\n```\n\nSee [docs/runtime.md](./docs/runtime.md) for runtime details.\n\n## Configuration\n\ni18ntk uses a project-local `.i18ntk-config` file.\n\nExample:\n\n```json\n{\n  \"version\": \"4.5.2\",\n  \"sourceDir\": \"./locales\",\n  \"i18nDir\": \"./locales\",\n  \"outputDir\": \"./i18ntk-reports\",\n  \"sourceLanguage\": \"en\",\n  \"defaultLanguages\": [\"en\", \"de\", \"es\", \"fr\", \"ru\"],\n  \"reports\": {\n    \"format\": \"markdown\"\n  },\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"],\n  \"autoTranslate\": {\n    \"placeholderMode\": \"preserve\",\n    \"concurrency\": 12,\n    \"batchSize\": 100,\n    \"progressInterval\": 25,\n    \"retryCount\": 3,\n    \"retryDelay\": 1000,\n    \"timeout\": 15000,\n    \"dryRunFirst\": true,\n    \"onlyMissingOrEnglish\": true,\n    \"reportStdout\": true,\n    \"bom\": false,\n    \"protectionEnabled\": true,\n    \"protectionFile\": \"./i18ntk-auto-translate.json\",\n    \"promptProtectionSetup\": true,\n    \"promptProtectionUpdate\": true\n  },\n  \"setup\": {\n    \"completed\": true\n  },\n  \"extensions\": {\n    \"workbench\": {\n      \"localeDirectory\": \"./locales\",\n      \"sourceLocale\": \"en\"\n    },\n    \"lens\": {\n      \"localeDirectory\": \"./locales\",\n      \"sourceLocale\": \"en\",\n      \"keyFormats\": [\"dot\", \"snake\"]\n    }\n  }\n}\n```\n\nSee [docs/api/CONFIGURATION.md](./docs/api/CONFIGURATION.md) for the full configuration model.\n\n## Public Package Contents\n\nThe public package intentionally ships runtime and CLI files only.\n\nThe package includes:\n\n- CLI entry points under `main/`\n- manager commands and services\n- runtime API files under `runtime/`\n- settings UI files required at runtime\n- bundled internal UI locales\n- shared utilities required by the shipped commands\n- `README.md`, `CHANGELOG.md`, `LICENSE`, and policy files\n\nThe public package manifest includes `readmeFilename: \"README.md\"`, and the release staging script fails if `README.md` is missing or empty.\n\n## Documentation\n\n- [Documentation Index](./docs/README.md)\n- [Getting Started](./docs/getting-started.md)\n- [API Reference](./docs/api/API_REFERENCE.md)\n- [Configuration Guide](./docs/api/CONFIGURATION.md)\n- [Runtime API Guide](./docs/runtime.md)\n- [Auto Translate Guide](./docs/auto-translate.md)\n- [Scanner Guide](./docs/scanner-guide.md)\n- [Environment Variables](./docs/environment-variables.md)\n- [Migration Guide v4.3.3](./docs/migration-guide-v4.3.3.md)\n\n## Security\n\n- No API key is required for the default Auto Translate flow.\n- Do not store secrets in locale files, `.i18ntk-config`, or protection files.\n- Project-specific brand/product terms should be configured by the user, not hardcoded into the package.\n- Report security issues using [SECURITY.md](./SECURITY.md).\n\n## Community\n\n- [Contributing](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Funding](./FUNDING.md)\n\n## Related Tools\n\n| Tool                 | Purpose                                                                                           |\n| -------------------- | ------------------------------------------------------------------------------------------------- |\n| **i18ntk**           | Zero-dependency i18n toolkit for scanning, validation, translation, reports, and runtime loading. |\n| **i18ntk Workbench** | Full VS Code localization health dashboard powered by i18ntk.                                     |\n| **i18ntk Lens**      | Lightweight inline translation hovers, diagnostics, and key navigation.                           |\n| **PublishGuard**     | Pre-publish safety scanner for npm packages and VS Code extensions.                               |\n| **ContextKit**       | AI coding context manager for AGENTS.md, Claude, Cursor, Copilot, Roo, and Codex files.           |\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n"
+  "readme": "# i18ntk v4.5.3\n\nA zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.\n\n![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)\n\n[![npm version](https://img.shields.io/npm/v/i18ntk.svg?color=brightgreen)](https://www.npmjs.com/package/i18ntk)\n[![npm downloads](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)\n[![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)\n[![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)\n[![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.5.3)](https://socket.dev/npm/package/i18ntk/overview/4.5.3)\n\n[![i18ntk Workbench](https://img.shields.io/badge/VS_Code-i18ntk_Workbench-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-workbench)\n[![i18ntk Lens](https://img.shields.io/badge/VS_Code-i18ntk_Lens-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-lens)\n\n## The i18ntk ecosystem\n\n- i18ntk — CLI and runtime toolkit\n- i18ntk Workbench — full VS Code dashboard and reports\n- i18ntk Lens — inline hovers, CodeLens, and diagnostics\n\nUse the CLI in CI, Workbench for project-level management, and Lens for day-to-day editor feedback.\n\n## Install\n\n```bash\n# global CLI use\nnpm install -g i18ntk\n\n# local project use\nnpm install --save-dev i18ntk\n\n# one-off execution\nnpx i18ntk --help\n```\n\n## i18ntk Summary\n\n**What it does**\n\n- Manages locale files from the command line.\n- Finds missing, unused, risky, and inconsistent translation keys.\n- Produces validation and summary reports.\n- Supports framework-aware i18n workflows.\n- Provides a lightweight runtime translation toolkit.\n\n**What it does not do**\n\n- It is not a translation management SaaS.\n- It does not replace human translation review.\n- It does not force you to replace i18next, react-i18next, vue-i18n, or another runtime.\n\n**Why not i18next?**\n\ni18next is mainly a runtime internationalization library. i18ntk is mainly workflow tooling around translation files. They can work together: i18next handles runtime translation, while i18ntk handles setup, scanning, validation, reporting, and maintenance.\n\n| Need                      | i18ntk        | i18next          |\n| ------------------------- | ------------- | ---------------- |\n| Runtime translation       | Basic toolkit | Mature runtime   |\n| Locale file scanning      | Yes           | No               |\n| Missing key detection     | Yes           | No               |\n| Unused key detection      | Yes           | No               |\n| Validation reports        | Yes           | Limited          |\n| Auto-translation workflow | Yes           | External tooling |\n\n## What's New in 4.5.3\n\n- **TSX/JSX SCANNING**: `supportedExtensions` default now includes `.tsx` and `.jsx`. Previously excluded from source scanning, causing React/Next.js projects to miss 97%+ of translation keys.\n\n## What's New in 4.5.2\n\n- The `complete` command now correctly inserts missing keys at the right nesting level when target locale files have namespace wrappers (e.g., `auth.json` containing `{ \"auth\": { ... } }`). Keys inside `auth.panel.sign_in` now go inside the `auth` wrapper, not at root level.\n- Fixed `complete` command: missing keys now inserted inside namespace wrapper when file has top-level key matching filename (e.g., auth.json with `{ \"auth\": … }`).\n- Fixed `translate --output-dir`: output now placed in `<outputDir>/<targetLang>/<filename>`, preventing language overwrites.\n- Enhanced `scanner` and `report-model` to filter out JS built-in type names (e.g., Promise, Boolean) and code expressions (e.g., `&&`, `${…}`) from hardcoded text detection.\n\n## What's New in 4.5.1\n\n- **CORRECT COMPLETENESS**: Validation now shows accurate completion percentages vs source locale (e.g., 33% instead of misleading 100%).\n- **NO MORE PARENT KEYS**: `getAllKeys()` no longer reports parent namespace objects (`footer`) as missing keys alongside their leaf children (`footer.copyright`).\n- **DOCTOR SMARTER**: No longer flags unconfigured languages (`de`, `ru`) as issues. Auto-detects available languages from the i18n directory structure.\n- **SCANNER FIXED**: Scanner now correctly scans `src/` directory for hardcoded text, not `locales/`.\n- **RUNTIME ALIASES**: `initRuntime()` now supports `localeDir`/`targetLocale`/`sourceLocale` as aliases for `baseDir`/`language`/`fallbackLanguage`.\n\n## What's New in 4.5.0\n\n- **PROTOTYPE POLLUTION HARDENED**: Three layers of defense added — `readJsonSafe()` now recursively strips `__proto__`, `constructor`, and `prototype` keys from all parsed JSON; `deepMerge()` in the runtime blocks these keys during locale merging; `mergeWithDefaults()` in settings-manager filters them from user settings.\n- **BACKUP FIXED**: All backup operations (create, restore, list, verify, cleanup) now work. A duplicate `sourceDir` declaration that caused a SyntaxError at module load has been removed. Corrupt backup files are now handled gracefully with descriptive error messages.\n- **COMPLETE COMMAND FIXED**: `i18ntk-complete` no longer crashes with `getUnifiedConfig is not defined`. The missing config-helper import has been added.\n- **MALFORMED JSON HANDLING**: Report generation now gracefully skips malformed JSON files with a warning instead of aborting the entire report.\n- **NULL SAFETY**: `stripBOMAndComments()` in i18n-helper now handles null/undefined inputs without throwing.\n- **ERROR HANDLING HARDENED**: Lazy-load failures in runtime now log to console when `I18NTK_DEBUG` is set. Settings save errors are now re-thrown instead of silently swallowed. Legacy config migration has proper error handling.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for more release details.\n\n## Quick Start\n\nInitialize a project:\n\n```bash\ni18ntk\n# or with explicit command\ni18ntk --command=init\n```\n\nRun common checks:\n\n```bash\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk report --json\ni18ntk --command=sizing\ni18ntk --command=summary\n```\n\nComplete or fix translation files:\n\n```bash\ni18ntk --command=complete\ni18ntk-fixer --help\n```\n\nAuto-translate locale JSON:\n\n```bash\ni18ntk --command=translate\n# or\ni18ntk-translate locales/en/common.json de --report-stdout\n```\n\nThe full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).\n\n## Main Commands\n\nPrimary CLI:\n\n```bash\ni18ntk\ni18ntk --help\ni18ntk --command=init\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk report --json --markdown --html --out ./i18ntk-reports\ni18ntk --command=scanner\ni18ntk --command=sizing\ni18ntk --command=complete\ni18ntk --command=translate\ni18ntk --command=summary\n```\n\nStandalone executables:\n\n```bash\ni18ntk-init\ni18ntk-analyze\ni18ntk-validate\ni18ntk-usage\ni18ntk-report\ni18ntk-scanner\ni18ntk-sizing\ni18ntk-complete\ni18ntk-summary\ni18ntk-doctor\ni18ntk-fixer\ni18ntk-backup\ni18ntk-translate\n```\n\nNote: manager route `i18ntk --command=backup` is available via the interactive menu. Use `i18ntk-backup` directly for scripted backup operations.\n\n## Command Reference\n\n| Command                                           | What it does                                                                                                 | Looks for                                                                                                                                                                            | Writes or changes                                                                                                                                                                                                                           |\n| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `i18ntk`                                          | Opens the interactive management menu.                                                                       | Project config, setup state, available commands.                                                                                                                                     | Only changes files after you choose a command that writes.                                                                                                                                                                                  |\n| `i18ntk --command=init` / `i18ntk-init`           | Sets up locale folders and missing target-language files.                                                    | Source language files and selected target languages.                                                                                                                                 | Locale JSON files, `.i18ntk-config`, optional reports/backups.                                                                                                                                                                              |\n| `i18ntk --command=analyze` / `i18ntk-analyze`     | Compares source and target translation coverage.                                                             | Missing keys, extra keys, untranslated markers, completion by language.                                                                                                              | Markdown/JSON/text reports when report output is enabled.                                                                                                                                                                                   |\n| `i18ntk --command=validate` / `i18ntk-validate`   | Validates structure and translation quality risks.                                                           | Placeholder mismatches, missing keys, risky URLs/emails/secrets, likely English target text.                                                                                         | Validation summary report. Does not edit locale files.                                                                                                                                                                                      |\n| `i18ntk --command=usage` / `i18ntk-usage`         | Maps translation keys to source files and finds unused/missing keys.                                         | Direct i18n calls, literal known-key references, bounded dynamic templates/object maps, unresolved dynamic expressions, hardcoded text candidates, namespace/file naming mismatches. | Usage report with key locations, namespace recommendations, unresolved dynamic expressions, hardcoded text suggestions, and optional dead-key report. Does not delete unless cleanup deletion is explicitly enabled.                        |\n| `i18ntk report` / `i18ntk-report`                 | Generates the stable schemaVersion 1 report used by CLI automation and i18ntk Workbench.                     | Locale completeness, missing keys, unused keys with confidence, placeholders, likely untranslated values, expansion risk, and hardcoded text candidates.                             | JSON to stdout by default, plus JSON/Markdown/HTML files when `--out` is used. Does not edit locale files.                                                                                                                                  |\n| `i18ntk --command=scanner` / `i18ntk-scanner`     | Scans source for i18n issues and hardcoded user-facing text.                                                 | JSX/template text, common text attributes, i18n usage patterns, source-language text profiles.                                                                                       | Scanner report. Does not edit files.                                                                                                                                                                                                        |\n| `i18ntk --command=complete` / `i18ntk-complete`   | Adds missing keys to target language files for 100% key coverage.                                            | Source-language keys missing from targets.                                                                                                                                           | Target locale JSON files, using missing translation markers/prefixes.                                                                                                                                                                       |\n| `i18ntk --command=translate` / `i18ntk-translate` | Auto-translates locale JSON using configured provider behavior.                                              | Missing, empty, untranslated-marker, source-copy, likely-English, or visibly corrupt target values by default.                                                                       | Target locale JSON files and translation reports. Existing translated values are kept unless `--translate-all` is used. If unresolved values remain after retry, writes `i18ntk-reports/auto-translate/latest.json` for targeted follow-up. |\n| `i18ntk --command=sizing` / `i18ntk-sizing`       | Estimates translated string length expansion and layout risk.                                                | Text length, expansion ratios, placeholder-bearing strings.                                                                                                                          | Sizing report. Does not edit locale files.                                                                                                                                                                                                  |\n| `i18ntk --command=summary` / `i18ntk-summary`     | Shows project translation status.                                                                            | Configured locales, reports, completeness status.                                                                                                                                    | Console/report output only.                                                                                                                                                                                                                 |\n| `i18ntk-fixer`                                    | Fixes placeholder and missing-marker issues, and can audit English source files with `--check-placeholders`. | Placeholder corruption, missing translation markers, configured language files, `[LANG] ...` leftovers in English locales.                                                           | Locale JSON files when fixes are applied. Use dry-run options where available before bulk edits.                                                                                                                                            |\n| `i18ntk-backup`                                   | Creates, verifies, restores, and cleans locale backups.                                                      | Locale JSON files and backup manifests.                                                                                                                                              | Backup archives/manifests, or restored locale files when using restore.                                                                                                                                                                     |\n\n## Common Options\n\nMany commands support:\n\n- `--source-dir <path>`\n- `--i18n-dir <path>`\n- `--output-dir <path>`\n- `--source-language <code>`\n- `--ui-language <code>`\n- `--no-prompt`\n- `--help`\n\nCommand-specific tools add their own flags such as `--dry-run`, `--output-report`, `--cleanup`, `--predict-expansion`, or Auto Translate provider options.\n\nExample:\n\n```bash\ni18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports\n```\n\n## Auto Translate\n\nInteractive manager flow:\n\n```bash\ni18ntk\n# choose \"Auto Translate\"\n```\n\nDirect CLI examples:\n\n```bash\ni18ntk-translate locales/en/common.json de\ni18ntk-translate locales/en/common.json fr --dry-run --report-stdout\ni18ntk-translate locales/en es --source-dir locales/en --files \"*.json\" --no-confirm --preserve-placeholders\n```\n\nProvider examples:\n\n```bash\nexport DEEPL_API_KEY=\"your-deepl-api-key\"\ni18ntk-translate locales/en/common.json de --provider deepl --no-confirm --preserve-placeholders\n\nexport LIBRETRANSLATE_URL=\"https://libretranslate.com/translate\"\nexport LIBRETRANSLATE_API_KEY=\"optional-api-key\"\ni18ntk-translate locales/en/common.json es --provider libretranslate --no-confirm --preserve-placeholders\n```\n\n`google` remains the default provider. You can also set `I18NTK_TRANSLATE_PROVIDER=deepl` or `I18NTK_TRANSLATE_PROVIDER=libretranslate`.\n\nProvider 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.\n\nThe manager flow asks for:\n\n- source locale directory, either the folder with JSON files or a locale root such as `./locales`\n- source language code\n- one or more target languages, or `all`\n- one JSON file or all JSON files in the source directory\n\nIf you select a locale root such as `./locales` and choose source language `en`, the manager automatically uses `./locales/en` when that folder contains the source JSON files.\n\nBefore writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:\n\n```text\nlocales/en/common.json\nlocales/de/common.json\nlocales/fr/common.json\n```\n\nAuto Translate is target-aware by default. When a target file already exists, it keeps translated target values and only sends values that are missing, empty, marked as untranslated, still identical to the source, likely still English, or visibly corrupt from encoding damage such as `?????`, replacement characters, or common mojibake. Use `--translate-all` when you intentionally want to re-translate every source string.\n\n### Placeholder Handling\n\nAuto Translate detects common placeholders such as:\n\n- `{name}`\n- `{{count}}`\n- `%s`\n- `%d`\n- `:id`\n- `%{name}`\n- `${value}`\n- `{count, plural, one {# item} other {# items}}`\n- `$t(common.save)`\n- `%(total).2f`\n\nUseful flags:\n\n- `--preserve-placeholders`: translate text around placeholders and reinsert original tokens\n- `--skip-placeholders`: copy placeholder-bearing strings unchanged\n- `--send-placeholders`: send placeholder-bearing strings through translation after masking\n- `--custom-regex <regex>`: add project-specific placeholder detection\n- `--only-missing`: keep existing translated target values and translate only missing/source-copy/likely English values (default)\n- `--translate-all`: re-translate every source string\n\nProgress output is stage-aware for large files. Normal keys are reported as `Translating strings`, while preserve-mode placeholder work is reported as `Translating placeholder-safe text segments`; each progress update includes the current key path when available.\n\n### Protected Terms and Keys\n\nAuto Translate can create and use a project-local protection file:\n\n```bash\ni18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json\n```\n\nExample `i18ntk-auto-translate.json`:\n\n```json\n{\n  \"version\": 1,\n  \"terms\": [\n    \"BrandName\",\n    \"PRODUCT_CODE\",\n    { \"value\": \"OK\", \"context\": \"after:Click|Press|Tap\" },\n    { \"value\": \"API\", \"context\": \"standalone\" }\n  ],\n  \"keys\": [\"app.brandName\", \"legal.companyName\", \"product.*.symbol\"],\n  \"values\": [\"BrandName Ltd\", \"support@example.com\"],\n  \"patterns\": [\"[A-Z]{2,}-\\\\d+\"]\n}\n```\n\n- `terms` are masked before translation and restored exactly afterward.\n  - **Plain strings**: masked everywhere (backward compatible).\n  - **Context objects**: masked only in specific contexts (`after:word`, `before:word`, `standalone`, `surrounded:left,right`).\n- `keys` are exact key paths or `*` wildcard paths copied unchanged.\n- `values` are exact source values copied unchanged.\n- `patterns` are JavaScript regex strings for advanced protected substrings.\n\nUseful flags:\n\n- `--protection-file <path>`\n- `--create-protection-file`\n- `--no-protection`\n\nOpen Settings and choose `Auto Translate` to edit defaults for placeholder mode, translate-only-needed mode, concurrency, batch size, retry settings, report output, BOM output, protection file path, first-run setup prompt, and update prompt.\n\nSee [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.\n\n## Validation\n\nValidation checks locale structure, completeness, placeholders, and content risks.\n\nValidation warning types are specific:\n\n- `Potential risky content`: URL, email address, or secret-like value\n- `Possible untranslated English content`: target-language value appears to contain too much English\n\nEnglish-content warnings include:\n\n- detected English percentage\n- configured threshold\n- matched word count\n- sample matched words\n\nTune warnings in `.i18ntk-config`:\n\n```json\n{\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"]\n}\n```\n\n## Sizing Analysis\n\n`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.\n\n```bash\ni18ntk-sizing --source-dir ./locales --format table\ni18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports\n```\n\nUse `--detailed` to print per-file rows in the terminal.\n\n### Expansion Prediction (New in 4.0.0)\n\nPredict UI layout overflow risk by analyzing per-key character-count expansion across languages:\n\n```bash\ni18ntk-sizing --source-dir ./locales --predict-expansion --output-report\n```\n\nExpansion ratios are classified into risk tiers:\n\n- **Safe** (<30% expansion): no UI impact expected\n- **Warning** (30–50%): may overflow in tight layouts — test on target languages\n- **Critical** (>50%): high risk of truncation — review UI element sizing\n\nThe report includes a built-in language-pair expansion reference table (EN→DE +35%, EN→RU +50%, EN→JA −40%, etc.) and lists the top-30 most-expanded keys.\n\n## Scanner: Multi-Language Detection (New in 4.0.0)\n\n`i18ntk-scanner` now supports detecting hardcoded text in multiple source languages beyond English:\n\n```bash\ni18ntk-scanner --source-dir ./src --source-language de\ni18ntk-scanner --source-dir ./src --source-language ja --output-report\n```\n\nSupported language profiles (12+): English, German, French, Spanish, Japanese, Chinese, Russian, Korean, Arabic, Hindi, and more. Each profile includes language-specific character ranges, stopword lists for false-positive filtering, and transliteration rules for key generation.\n\n## Usage: Dead Key Detection (New in 4.0.0)\n\n`i18ntk-usage` can identify translation keys that are defined but never referenced in source code:\n\n```bash\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup --dry-run-delete\n```\n\nEach dead key receives a confidence score (0.0–1.0) factoring:\n\n- Unresolved dynamic key patterns (e.g., ``t(`prefix.${dynamic}`)``) — lower score and listed in the usage report; simple consts, bounded arrays, object maps, and ternaries are expanded to exact keys where possible\n- Key appears in source code comments or JSDoc — medium score\n- Parent file recently modified (<30 days) — medium score\n- No references found anywhere — high score (>0.8)\n\nThe `--dry-run-delete` flag writes a `.dead-keys.json` report for review before any destructive action.\n\n## Validator: Key Naming Conventions (New in 4.0.0)\n\nEnforce consistent translation key naming across your project:\n\n```bash\ni18ntk-validate --enforce-key-style\n```\n\nConfigure the expected style in `.i18ntk-config`:\n\n```json\n{\n  \"keyStyle\": \"dot.notation\"\n}\n```\n\nSupported styles: `dot.notation`, `snake_case`, `camelCase`, `kebab-case`, `flat`. Violations are reported as warnings with suggested canonical forms.\n\n## Watch: Hot Reload (New in 4.0.0)\n\n`utils/watch-locales.js` now provides debounced file watching with EventEmitter support:\n\n```js\nconst watchLocales = require('i18ntk/utils/watch-locales');\nconst watcher = watchLocales('./locales');\n\nwatcher.on('change', (filePath) => {\n  console.log('Locale changed:', filePath);\n});\n\nwatcher.on('add', (filePath) => {\n  console.log('Locale added:', filePath);\n});\n\n// Later:\nwatcher.stop();\n```\n\nFeatures: 300ms debounce (configurable), SHA-256 hash tracking to skip no-change saves, and a maximum of 50 watched directories.\n\n### Migration\n\nThe `watchLocales` return value gained EventEmitter methods in v4.0.0. Existing stop-function usage still works:\n\n```js\nconst stop = watchLocales('./locales', onChange);\n```\n\nCan be updated to:\n\n```js\nconst watcher = watchLocales('./locales');\nwatcher.on('change', onChange);\nwatcher.stop();\n```\n\nPassing a callback as the second argument is still supported — it auto-subscribes to `change` and `add` events.\n\n## Backup: Incremental Mode (New in 4.0.0)\n\nCreate differential backups that only include changed files:\n\n```bash\ni18ntk-backup create ./locales --incremental\n```\n\nIncremental backups store SHA-256 hashes per file and a parent-chain reference. Restoring an incremental backup automatically chains from the oldest full backup through each incremental diff in order. Chain depth is capped at 10 increments. Use `verify` to validate the hash chain.\n\n## Runtime: Lazy Loading (New in 4.0.0)\n\nReduce memory usage by deferring locale file loads until first key access:\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  lazy: true,\n});\n\nconsole.log(i18n.t('common.hello')); // loads common.json on first access\n```\n\nWhen `lazy: true`, the runtime builds a key-to-file manifest on first access and loads individual files on demand. Files are loaded once and cached. If the manifest is missing or incomplete, the runtime falls back to full eager loading for that language. Manifest size is capped at 100KB with path containment validation.\n\nProduction guidance:\n\n- Prefer the object returned from `initRuntime()` instead of module-level `runtime.t()` in apps with multiple tenants, projects, or locale roots.\n- Use `lazy: true` for large modular locale folders where lower steady-state memory matters more than a small first-key lookup cost.\n- Use `preload: true` without `lazy` for small locale sets or latency-sensitive startup paths.\n- Call `refresh(language)` after deploying or writing changed locale files so cached data and lazy manifests are rebuilt.\n- Use per-call language overrides when rendering one-off alternate-language strings: `i18n.t('common.hello', {}, { language: 'de' })`.\n- Use `translateBatch()` for small groups of labels and `clearCache()` / `getCacheInfo()` for cache maintenance and diagnostics.\n- `i18ntk/runtime/enhanced` remains available for compatibility with existing async/encryption users, but new production integrations should start with `i18ntk/runtime`.\n\n## Runtime API\n\nUse `i18ntk/runtime` when an application needs to read locale JSON files at runtime.\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  fallbackLanguage: 'en',\n  keySeparator: '.',\n  preload: true,\n});\n\nconsole.log(i18n.t('common.hello'));\ni18n.setLanguage('fr');\nconsole.log(i18n.getLanguage());\nconsole.log(i18n.getAvailableLanguages());\ni18n.refresh('fr');\n```\n\nUseful production helpers:\n\n```js\ni18n.t('common.hello', {}, { language: 'de' }); // per-call language override\ni18n.translateBatch(['menu.home', 'menu.settings']);\ni18n.clearCache('fr');\nconsole.log(i18n.getCacheInfo());\n```\n\nSee [docs/runtime.md](./docs/runtime.md) for runtime details.\n\n## Configuration\n\ni18ntk uses a project-local `.i18ntk-config` file.\n\nExample:\n\n```json\n{\n  \"version\": \"4.5.3\",\n  \"sourceDir\": \"./locales\",\n  \"i18nDir\": \"./locales\",\n  \"outputDir\": \"./i18ntk-reports\",\n  \"sourceLanguage\": \"en\",\n  \"defaultLanguages\": [\"en\", \"de\", \"es\", \"fr\", \"ru\"],\n  \"reports\": {\n    \"format\": \"markdown\"\n  },\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"],\n  \"autoTranslate\": {\n    \"placeholderMode\": \"preserve\",\n    \"concurrency\": 12,\n    \"batchSize\": 100,\n    \"progressInterval\": 25,\n    \"retryCount\": 3,\n    \"retryDelay\": 1000,\n    \"timeout\": 15000,\n    \"dryRunFirst\": true,\n    \"onlyMissingOrEnglish\": true,\n    \"reportStdout\": true,\n    \"bom\": false,\n    \"protectionEnabled\": true,\n    \"protectionFile\": \"./i18ntk-auto-translate.json\",\n    \"promptProtectionSetup\": true,\n    \"promptProtectionUpdate\": true\n  },\n  \"setup\": {\n    \"completed\": true\n  },\n  \"extensions\": {\n    \"workbench\": {\n      \"localeDirectory\": \"./locales\",\n      \"sourceLocale\": \"en\"\n    },\n    \"lens\": {\n      \"localeDirectory\": \"./locales\",\n      \"sourceLocale\": \"en\",\n      \"keyFormats\": [\"dot\", \"snake\"]\n    }\n  }\n}\n```\n\nSee [docs/api/CONFIGURATION.md](./docs/api/CONFIGURATION.md) for the full configuration model.\n\n## Public Package Contents\n\nThe public package intentionally ships runtime and CLI files only.\n\nThe package includes:\n\n- CLI entry points under `main/`\n- manager commands and services\n- runtime API files under `runtime/`\n- settings UI files required at runtime\n- bundled internal UI locales\n- shared utilities required by the shipped commands\n- `README.md`, `CHANGELOG.md`, `LICENSE`, and policy files\n\nThe public package manifest includes `readmeFilename: \"README.md\"`, and the release staging script fails if `README.md` is missing or empty.\n\n## Documentation\n\n- [Documentation Index](./docs/README.md)\n- [Getting Started](./docs/getting-started.md)\n- [API Reference](./docs/api/API_REFERENCE.md)\n- [Configuration Guide](./docs/api/CONFIGURATION.md)\n- [Runtime API Guide](./docs/runtime.md)\n- [Auto Translate Guide](./docs/auto-translate.md)\n- [Scanner Guide](./docs/scanner-guide.md)\n- [Environment Variables](./docs/environment-variables.md)\n- [Migration Guide v4.3.3](./docs/migration-guide-v4.3.3.md)\n\n## Security\n\n- No API key is required for the default Auto Translate flow.\n- Do not store secrets in locale files, `.i18ntk-config`, or protection files.\n- Project-specific brand/product terms should be configured by the user, not hardcoded into the package.\n- Report security issues using [SECURITY.md](./SECURITY.md).\n\n## Community\n\n- [Contributing](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Funding](./FUNDING.md)\n\n## Related Tools\n\n| Tool                 | Purpose                                                                                           |\n| -------------------- | ------------------------------------------------------------------------------------------------- |\n| **i18ntk**           | Zero-dependency i18n toolkit for scanning, validation, translation, reports, and runtime loading. |\n| **i18ntk Workbench** | Full VS Code localization health dashboard powered by i18ntk.                                     |\n| **i18ntk Lens**      | Lightweight inline translation hovers, diagnostics, and key navigation.                           |\n| **PublishGuard**     | Pre-publish safety scanner for npm packages and VS Code extensions.                               |\n| **ContextKit**       | AI coding context manager for AGENTS.md, Claude, Cursor, Copilot, Roo, and Codex files.           |\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n"
 }

package/utils/config-helper.js

@@ -169,7 +169,7 @@ async function getUnifiedConfig(scriptName, cliArgs = {}) {
       uiLanguage: cliArgs.uiLanguage || cfg.uiLanguage || 'en',
       notTranslatedMarker: markerList[0],
       notTranslatedMarkers: markerList,
-      supportedExtensions: cfg.supportedExtensions || cfg.processing?.supportedExtensions || ['.json', '.js', '.ts'],
+      supportedExtensions: cfg.supportedExtensions || cfg.processing?.supportedExtensions || ['.json', '.js', '.jsx', '.ts', '.tsx'],
       excludeFiles: cfg.excludeFiles || cfg.processing?.excludeFiles || ['.DS_Store', 'Thumbs.db'],
       excludeDirs: cfg.excludeDirs || cfg.processing?.excludeDirs || ['node_modules', '.next', '.git', 'dist', 'build'],
       strictMode: cliArgs.strictMode || cfg.strictMode || false,