i18ntk 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -5,6 +5,101 @@ 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).
 
+## [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.
+- Backup restore now rejects backup entry names containing path separators, absolute paths, traversal, or non-JSON names before writing restored files.
+- Runtime locale loading now validates language identifiers before resolving single-file or directory locale paths, blocking `../` language names from reading JSON outside `baseDir`.
+- 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.
+- Usage analysis now expands simple dynamic templates backed by literal constants, bounded literal arrays, object maps, and ternaries to exact available keys before falling back to unresolved dynamic-expression reporting.
+- Usage reports now list unresolved dynamic key expressions separately instead of treating broad wildcard prefixes as proof that every matching key is used.
+- Usage reports now include namespace/file naming recommendations such as preferring `shop.*` keys and `shop.json` for `/shop` page or route files.
+- Usage reports now list likely hardcoded user-facing text with suggested translation keys, and prefer an existing source key when the inline text matches a source translation value.
+- Translation analysis and init reports now default to Markdown for readable output, with `reports.format` supporting `markdown`, `json`, or `text` through settings and config.
+- Init default target languages now include English (`en`) before `de`, `es`, `fr`, and `ru` when the UI is running in another language.
+- Confirmation prompts now accept localized native yes/no input for supported UI languages while retaining English fallback tokens.
+- Auto Translate has moved out of beta in menus and documentation, and its settings are exposed with localized labels.
+- Auto Translate now keeps existing translated target values by default and only translates missing, marker, source-copy, or likely English target strings; use `--translate-all` to force a full re-translation.
+- Auto Translate now treats visibly corrupt target strings such as `?????`, Unicode replacement characters, and common mojibake as needing retranslation from the source language.
+- Auto Translate now defaults to 12 concurrent provider requests and allows Google concurrency up to 100 instead of the old 25-request cap; DeepL and LibreTranslate remain capped lower to avoid provider/account throttling.
+- Auto Translate progress output now separates string translation from placeholder-safe text-segment translation and shows the active key path during progress updates.
+- Placeholder detection now covers ICU plural/select blocks, i18next nested `$t(...)` references, and wider named printf formats such as `%(total).2f`.
+- Manager menu output is now grouped with clearer spacing and aligned option numbers.
+- Documentation now consolidates migration guidance around `4.2.0` and removes stale old per-version migration guides from the working docs tree.
+- Removed stale duplicate development artifacts `main/manage/index-fixed.js` and `utils/security-fixed.js` to reduce audit drift and prevent accidental reuse.
+- 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.
+- Init backup prompts, completion summaries, report prompts, and report status text now use bundled UI locale keys instead of hard-coded English.
+- Bundled UI locales were regenerated from `ui-locales/en.json` for newly added, source-copy, and corrupt target strings.
+- JSON report output is now pretty-printed object JSON instead of a single JSON string containing escaped newlines.
+- The managed Auto Translate command no longer forces UI translations back to English after the user has selected another UI language.
+- Manager validation output no longer prints duplicate source/i18n/output directory blocks before the validator summary.
+- `i18ntk-setup --help` now exits after printing help instead of running setup and writing project files.
+- `npm run languages:list` and `npm run languages:status` now produce non-interactive output instead of opening the settings menu.
+- `i18ntk-backup create locales` now recursively backs up modular locale layouts such as `locales/en/common.json`, and restore safely recreates nested JSON paths without allowing traversal.
+- Removed a stale bundled `locales/es/navigation.json` fixture that made `i18ntk-doctor` report a dangling namespace after setup/init tests.
+
+## [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`.
+- Backup: `handleVerify` hash-chain verification rewritten for incremental backups — rebuilds full state oldest→newest before per-entry hash comparison; no longer reports false "Missing file" errors for unchanged files.
+- Backup: `cleanupOldBackups` and `handleCleanup` now preserve parent backups of incremental chains by scanning kept backups for `_meta.parent` references before deletion.
+- Backup: `--incremental=false` is now correctly parsed as falsy (string-to-boolean conversion fixed).
+- Backup: `buildRestoreChain` detects circular parent references via visited-set traversal.
+- Sizing: `this.adminAuth` undefined crash in `run()` fixed — changed to correct `adminAuth` local variable.
+- Sizing: duplicate `analyze()` method removed; format-based display logic (`--format=json` vs table) restored to the surviving method.
+- Sizing: setup-check IIFE now guarded with `require.main === module`, preventing unexpected `process.exit()` on `require()`.
+- Scanner: `frameworks.vanilla` key added to `getFrameworkSpecific` — no longer returns `undefined` for vanilla projects.
+- Scanner: `--source-language` CLI flag now correctly propagates through config chain to `scanFile` and `generateSuggestion` (camelCase vs hyphen key mismatch fixed).
+- Scanner: `isTextInLanguage` now always validates character ratio unconditionally even for no-stopword language profiles.
+- Watch: `{ onChange: fn }` object-format callbacks are now properly subscribed to change/add/unlink events.
+- 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: `--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.
+- Validator: missing `try` block in `run()` added so errors are caught by the existing `catch(error)` handler.
+- Validator: `--enforce-key-style=true/false` now correctly parsed (previously silently ignored due to `!includes('=')` guard).
+- Validator: `flat` style no longer produces false positives for nested keys — validates only the leaf segment (last `.`-delimited part).
+- Validator: `suggestKeyFix` for `flat` style now returns `segments.map(s => s.toLowerCase()).join('')` instead of camelCase.
+- Validator: `getLanguageFiles` no longer crashes when `excludeFiles` config property is undefined.
+- Validator: `enforceKeyStyle` now correctly propagated from CLI args to `this.config.enforceKeyStyle` in `run()`.
+- Protection: `standalone` mode boundary check now handles opening/closing punctuation (`(`, `[`, `{`, `"`, `'`, `-`, `–`, `—`) and CJK marks (`。`, `、`, `」`).
+- Protection: `\b` word-boundary assertions replaced with Unicode-aware `(^|[\s\p{P}])` / `([\s\p{P}]|$)` patterns with `u` flag for non-ASCII language support.
+- Protection: `surrounded` context rule parser now uses `indexOf(',')` split instead of greedy `(.+,.+)` regex to correctly parse multi-word right-side expressions.
+- Protection: `hasProtectionRules` no longer throws `TypeError` when `terms` property is undefined.
+- Protection: `shouldPreserveWholeValue` now respects context rules by only matching `type === 'global'` entries.
+- Manager option 7 ("Fix placeholder translations") now interpolates fixer status values correctly instead of printing raw `{languages}`, `{sourceDir}`, `{skipped}`, or `{totalIssues}` placeholders.
+- Delete Reports settings now include cache cleanup targets.
+- 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.
+- Sizing: adminAuth variable reference corrected; require()-time `process.exit()` guarded.
+- Scanner: vanilla framework key prevents `undefined` return; stopword-less validRatio enforced.
+- Usage: O(n+m) comment scanning prevents DoS via large codebase with many dead keys; `toBool()` prevents flag injection.
+- Validator: try/catch pairing restored; `flat` leaf-segment prevents false-positive flood.
+- Protection: Unicode-aware punctuation boundaries for CJK/Cyrillic/Arabic; standalone boundaries include the expanded punctuation set.
+
 ## [4.0.0] - 2026-05-21
 
 ### Added
@@ -17,32 +112,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Runtime Lazy Loading**: `runtime/index.js` adds `lazy: true` option to `initRuntime()`. Defers locale file loading until the first key access, guided by an auto-generated key-to-file manifest. Falls back to eager loading if manifest is missing. Manifest capped at 100KB with path containment validation.
 - **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.
-- Manager option 7 ("Fix placeholder translations") now interpolates fixer status values correctly instead of printing raw `{languages}`, `{sourceDir}`, `{skipped}`, or `{totalIssues}` placeholders.
+### 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.
+### 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.
 
-### Security
-- All new features reuse existing `SecurityUtils.safe*` wrappers for file I/O, path validation, and input sanitization.
-- Watch module validates all directory paths against project root with containment checks and caps at 50 directories.
-- Runtime lazy-loading manifest entries validated for path containment and size-limited to 100KB.
-- Protection context rules parsed from constrained DSL — never accepts raw user-controlled regex from config.
-- Backup incremental chain depth capped at 10 to prevent resource exhaustion; hash chain verified before restore.
-
-## [3.3.0] - 2026-05-20
+## [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.
+### 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.
@@ -54,18 +141,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Socket.dev Analysis Disclaimer
 
-This package is a developer CLI and runtime helper that performs file I/O, network access (translation provider APIs on user request), and environment variable access. As such, Socket.dev will flag the following alerts that are **expected and by design**:
+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. |
+| 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
+| 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`.

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v4.0.0
+# i18ntk v4.2.0
 
 A i18n toolkit - A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
 
@@ -9,7 +9,7 @@ A i18n toolkit - A zero-dependency internationalization toolkit for setup, scann
 [![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.0.0)](https://socket.dev/npm/package/i18ntk/overview/4.0.0)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.2.0)](https://socket.dev/npm/package/i18ntk/overview/4.2.0)
 
 ## Install
 
@@ -30,6 +30,25 @@ Requirements:
 - npm `>=8.0.0`
 - No runtime dependencies
 
+## What's New in 4.2.0
+
+- **SECURITY**: Hardened path containment for restore and shared filesystem helpers, including artifact-like filenames, environment-added internal prefixes, and Windows cross-drive paths.
+- **SECURITY**: Runtime locale loading now rejects unsafe language identifiers before resolving locale files, preventing `../` language names from reading JSON outside the configured locale base.
+- **SECURITY**: Auto Translate provider URL checks now block IPv4-mapped IPv6 private/loopback hosts.
+- **REPORTS**: Init and analysis reports now default to readable Markdown. Set `reports.format` to `markdown`, `json`, or `text` in Settings or `.i18ntk-config`.
+- **USAGE**: Usage analysis no longer scans the project root when locales are also configured as the source directory, avoiding inflated missing-key counts.
+- **I18N UX**: Init backup prompts, completion summaries, report prompts, default target languages, and native yes/no confirmations are now localized.
+- **AUTO TRANSLATE**: Auto Translate is out of beta, keeps existing translated target values by default, and only sends missing/source-copy/likely-English strings unless `--translate-all` is used.
+- **AUTO TRANSLATE**: Google Auto Translate concurrency now defaults to 12 and can be raised up to 100 for larger locale sets.
+- **AUTO TRANSLATE**: Corrupt target strings such as `?????`, replacement characters, and common mojibake are now repaired from the English source, and progress output distinguishes key translation from placeholder-safe text-segment translation.
+- **CLI UX**: Manager menu spacing is grouped and aligned, and validation no longer prints duplicate source/i18n/output directory blocks.
+- **DOCS**: Versioned docs and migration guidance now reflect the current 4.2.0 command surface.
+- **CLEANUP**: Removed stale duplicate fixed artifacts from the development tree to reduce audit and supply-chain drift.
+
+## What's New in 4.1.0
+
+- **FIX**: Critical and high-impact bugs resolved across the v4.0.0 feature set — runtime staleness crashes, backup hash-chain verification, sizing adminAuth crash, scanner `--source-language` propagation, watch callback subscriptions, dead key detection performance, validator key style enforcement, and protection Unicode boundary handling. See [CHANGELOG.md](./CHANGELOG.md) for complete details.
+
 ## What's New in 4.0.0
 
 - **SIZING**: `--predict-expansion` flag computes per-key expansion ratios across languages with Safe/Warning/Critical risk tiers for UI layout planning.
@@ -40,7 +59,6 @@ Requirements:
 - **BACKUP**: `--incremental` flag creates differential backups with SHA-256 hashing and chained restores.
 - **RUNTIME**: `lazy: true` option defers locale file loading until first key access for lower memory usage.
 - **PROTECTION**: Context-aware rules (`after:word`, `before:word`, `standalone`, `surrounded:left,right`) for precise term masking.
-- **FIX**: `initRuntime()` now returns independent instances with isolated language and cache state.
 
 See [CHANGELOG.md](./CHANGELOG.md) for more release details.
 
@@ -97,7 +115,6 @@ i18ntk --command=sizing
 i18ntk --command=complete
 i18ntk --command=translate
 i18ntk --command=summary
-i18ntk --command=debug
 ```
 
 Standalone executables:
@@ -116,12 +133,29 @@ i18ntk-fixer
 i18ntk-backup
 i18ntk-translate
 ```
-`n
-Note: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` (or legacy `i18ntk-backup`) directly for backup operations.
+
+Note: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` directly for backup operations.
+
+## Command Reference
+
+| Command | What it does | Looks for | Writes or changes |
+| --- | --- | --- | --- |
+| `i18ntk` | Opens the interactive management menu. | Project config, setup state, available commands. | Only changes files after you choose a command that writes. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `i18ntk --command=summary` / `i18ntk-summary` | Shows project translation status. | Configured locales, reports, completeness status. | Console/report output only. |
+| `i18ntk-fixer` | Fixes placeholder and missing-marker issues. | Placeholder corruption, missing translation markers, configured language files. | Locale JSON files when fixes are applied. Use dry-run options where available before bulk edits. |
+| `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. |
 
 ## Common Options
 
-Most commands support:
+Many commands support:
 
 - `--source-dir <path>`
 - `--i18n-dir <path>`
@@ -129,9 +163,10 @@ Most commands support:
 - `--source-language <code>`
 - `--ui-language <code>`
 - `--no-prompt`
-- `--dry-run`
 - `--help`
 
+Command-specific tools add their own flags such as `--dry-run`, `--output-report`, `--cleanup`, `--predict-expansion`, or Auto Translate provider options.
+
 Example:
 
 ```bash
@@ -144,7 +179,7 @@ Interactive manager flow:
 
 ```bash
 i18ntk
-# choose "Auto Translate (Beta)"
+# choose "Auto Translate"
 ```
 
 Direct CLI examples:
@@ -187,6 +222,8 @@ locales/de/common.json
 locales/fr/common.json
 ```
 
+Auto 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.
+
 ### Placeholder Handling
 
 Auto Translate detects common placeholders such as:
@@ -198,6 +235,9 @@ Auto Translate detects common placeholders such as:
 - `:id`
 - `%{name}`
 - `${value}`
+- `{count, plural, one {# item} other {# items}}`
+- `$t(common.save)`
+- `%(total).2f`
 
 Useful flags:
 
@@ -205,6 +245,10 @@ Useful flags:
 - `--skip-placeholders`: copy placeholder-bearing strings unchanged
 - `--send-placeholders`: send placeholder-bearing strings through translation after masking
 - `--custom-regex <regex>`: add project-specific placeholder detection
+- `--only-missing`: keep existing translated target values and translate only missing/source-copy/likely English values (default)
+- `--translate-all`: re-translate every source string
+
+Progress 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.
 
 ### Protected Terms and Keys
 
@@ -244,7 +288,7 @@ Useful flags:
 - `--create-protection-file`
 - `--no-protection`
 
-Open Settings and choose `Auto Translate Beta` to edit defaults for placeholder mode, concurrency, batch size, retry settings, report output, BOM output, protection file path, first-run setup prompt, and update prompt.
+Open 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.
 
 See [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.
 
@@ -252,7 +296,7 @@ See [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Transla
 
 Validation checks locale structure, completeness, placeholders, and content risks.
 
-In 3.1.2, warning types are more specific:
+Validation warning types are specific:
 
 - `Potential risky content`: URL, email address, or secret-like value
 - `Possible untranslated English content`: target-language value appears to contain too much English
@@ -321,7 +365,7 @@ i18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup --dry-run-delete
 ```
 
 Each dead key receives a confidence score (0.0–1.0) factoring:
-- Dynamic key patterns (e.g., `` t(`prefix.${dynamic}`) ``) — lower score
+- 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
 - Key appears in source code comments or JSDoc — medium score
 - Parent file recently modified (<30 days) — medium score
 - No references found anywhere — high score (>0.8)
@@ -414,6 +458,16 @@ console.log(i18n.t('common.hello')); // loads common.json on first access
 
 When `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.
 
+Production guidance:
+
+- Prefer the object returned from `initRuntime()` instead of module-level `runtime.t()` in apps with multiple tenants, projects, or locale roots.
+- Use `lazy: true` for large modular locale folders where lower steady-state memory matters more than a small first-key lookup cost.
+- Use `preload: true` without `lazy` for small locale sets or latency-sensitive startup paths.
+- Call `refresh(language)` after deploying or writing changed locale files so cached data and lazy manifests are rebuilt.
+- Use per-call language overrides when rendering one-off alternate-language strings: `i18n.t('common.hello', {}, { language: 'de' })`.
+- Use `translateBatch()` for small groups of labels and `clearCache()` / `getCacheInfo()` for cache maintenance and diagnostics.
+- `i18ntk/runtime/enhanced` remains available for compatibility with existing async/encryption users, but new production integrations should start with `i18ntk/runtime`.
+
 ## Runtime API
 
 Use `i18ntk/runtime` when an application needs to read locale JSON files at runtime.
@@ -436,6 +490,15 @@ console.log(i18n.getAvailableLanguages());
 i18n.refresh('fr');
 ```
 
+Useful production helpers:
+
+```js
+i18n.t('common.hello', {}, { language: 'de' }); // per-call language override
+i18n.translateBatch(['menu.home', 'menu.settings']);
+i18n.clearCache('fr');
+console.log(i18n.getCacheInfo());
+```
+
 See [docs/runtime.md](./docs/runtime.md) for runtime details.
 
 ## Configuration
@@ -446,23 +509,27 @@ Example:
 
 ```json
 {
-  "version": "4.0.0",
+  "version": "4.2.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
   "sourceLanguage": "en",
-  "defaultLanguages": ["de", "es", "fr", "ru"],
+  "defaultLanguages": ["en", "de", "es", "fr", "ru"],
+  "reports": {
+    "format": "markdown"
+  },
   "englishContentThresholdPercent": 10,
   "allowedEnglishTerms": ["BrandName", "PRODUCT_CODE"],
   "autoTranslate": {
     "placeholderMode": "preserve",
-    "concurrency": 6,
+    "concurrency": 12,
     "batchSize": 100,
     "progressInterval": 25,
     "retryCount": 3,
     "retryDelay": 1000,
     "timeout": 15000,
     "dryRunFirst": true,
+    "onlyMissingOrEnglish": true,
     "reportStdout": true,
     "bom": false,
     "protectionEnabled": true,
@@ -504,9 +571,7 @@ The public package manifest includes `readmeFilename: "README.md"`, and the rele
 - [Auto Translate Guide](./docs/auto-translate.md)
 - [Scanner Guide](./docs/scanner-guide.md)
 - [Environment Variables](./docs/environment-variables.md)
-- [Migration Guide v3.2.0](./docs/migration-guide-v3.2.0.md)
-- [Migration Guide v3.1.1](./docs/migration-guide-v3.1.1.md)
-- [Migration Guide v3.0.0](./docs/migration-guide-v3.0.0.md)
+- [Migration Guide v4.2.0](./docs/migration-guide-v4.2.0.md)
 
 ## Security
 

package/SECURITY.md

@@ -4,7 +4,7 @@
 
 The supported production line is `4.x`.
 
-Versions earlier than `4.0.0` are not recommended for production use because later releases include Auto Translate provider hardening, dynamic-require elimination, path-validation hardening, lazy loading with manifest validation, and incremental backup hash-chain verification.
+Versions earlier than `4.2.0` are not recommended for production use because later releases include Auto Translate provider hardening, dynamic-require elimination, path-validation hardening, runtime language validation, lazy loading with manifest validation, incremental backup hash-chain verification, and post-4.0.0 critical bug fixes for runtime staleness, backup verification, and CLI flag parsing.
 
 ## Security Model
 
@@ -38,11 +38,19 @@ Socket.dev scans the published npm package and may flag the following alerts. Th
 The v3.3.0 release **resolved** the previously actionable Socket.dev alert:
 - **Dynamic require** — all 21 instances eliminated (20 converted to static string literals, 1 gated with `SecurityUtils.validatePath`).
 
-The v4.0.0 release adds the following security hardening:
+The v4.0.0 release adds the following security hardening:
 - **Watch module**: all watched directories validated against project root with containment checks; capped at 50 directories.
 - **Runtime lazy loading**: key-to-file manifest entries validated for path containment; manifest size capped at 100KB.
-- **Incremental backups**: hash-chain verification before restore; chain depth capped at 10 increments.
-- **Protection context rules**: DSL-parsed context rules — never raw user-controlled regex from config; bounded at 200 chars per rule, 100 rules total.
+- **Incremental backups**: hash-chain verification before restore; chain depth capped at 10 increments; circular parent references detected.
+- **Protection context rules**: DSL-parsed context rules — never raw user-controlled regex from config; bounded at 200 chars per rule, 100 rules total; Unicode-aware `\p{P}` word boundaries for non-ASCII language support.
+- **Scanner multi-language detection**: source-language propagation fixed; stopword-less language profiles now still enforce valid-character ratios.
+- **Usage dead key detection**: optimized O(n+m) comment scanning instead of O(n*m); all CLI boolean flags validated with strict `toBool()` conversion.
+
+The v4.2.0 release adds the following security hardening:
+- **Shared path validation**: artifact-like filenames no longer bypass base containment; cross-drive absolute paths and environment-added internal prefixes are constrained.
+- **Backup restore**: backup entry names must be plain `.json` filenames and are restored through stable output-directory containment.
+- **Runtime locale loading**: language identifiers are validated before locale path resolution.
+- **Auto Translate networking**: IPv4-mapped IPv6 loopback/private hosts are blocked by provider URL validation.
 
 ## Reporting Vulnerabilities
 
@@ -66,7 +74,7 @@ Security reports are reviewed privately first. Confirmed issues should receive:
 
 ## User Guidance
 
-- Keep i18ntk updated to `4.0.0` or newer.
+- Keep i18ntk updated to `4.2.0` or newer.
 - Do not commit `.i18ntk-config`, admin PIN files, backup directories, generated reports, logs, npm credentials, or secret material.
 - Run i18ntk only in project directories you trust.
 - Review generated translation changes before committing them.

package/main/i18ntk-analyze.js

@@ -13,9 +13,11 @@ const { loadTranslations, t } = require('../utils/i18n-helper');
 const { getUnifiedConfig, parseCommonArgs, displayHelp } = require('../utils/config-helper');
 const SecurityUtils = require('../utils/security');
 const AdminCLI = require('../utils/admin-cli');
-const watchLocales = require('../utils/watch-locales');
-const JsonOutput = require('../utils/json-output');
-const SetupEnforcer = require('../utils/setup-enforcer');
+const watchLocales = require('../utils/watch-locales');
+const JsonOutput = require('../utils/json-output');
+const SetupEnforcer = require('../utils/setup-enforcer');
+const configManager = require('../utils/config-manager');
+const { normalizeReportFormat, writeReportFile } = require('../utils/report-writer');
 
 // Ensure setup is complete before running
 (async () => {
@@ -696,23 +698,11 @@ try {
         return null;
       }
       
-      // Create a safe filename
-      const safeLanguage = language.replace(/[^\w-]/g, '_');
-      const reportPath = path.resolve(validatedOutputDir, `translation-report-${safeLanguage}.json`);
-      
-      // Ensure the final path is still within the output directory
-      if (!reportPath.startsWith(validatedOutputDir)) {
-        console.error('Invalid report path detected, potential directory traversal attack');
-        return null;
-      }
-      
-      // Use safeWriteFile for secure file writing
-      const success = await SecurityUtils.safeWriteFile(reportPath, JSON.stringify(report, null, 2), process.cwd(), 'utf8');
-      if (!success) {
-        throw new Error(t('analyze.failedToWriteReportFile') || 'Failed to write report file securely');
-      }
-      
-      return reportPath;
+      const safeLanguage = language.replace(/[^\w-]/g, '_');
+      const settings = configManager.getConfig ? configManager.getConfig() : {};
+      const format = normalizeReportFormat(this.config?.reports?.format || settings.reports?.format || this.config?.reportFormat || 'markdown');
+      const reportPath = await writeReportFile(validatedOutputDir, `translation-report-${safeLanguage}`, report, { format, title: `Translation Report ${safeLanguage.toUpperCase()}` });
+      return reportPath;
       
     } catch (error) {
       console.error(`Failed to save report for ${language}:`, error.message);