i18ntk 4.3.3 → 4.4.2

package/CHANGELOG.md

@@ -5,99 +5,162 @@ 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.3.3] - 2026-06-01
+## [4.4.2] - 2026-06-02
 
 ### 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.
-- Usage documentation now treats unused-key reports as advisory; do not bulk-delete keys from an unused report without manual verification or a more precise usage scan.
+- 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.
 
-## [4.3.2] - 2026-05-31
+### Added
+- Added regression coverage for relative source paths, protected product terms, broken target values, placeholder handling, and managed Auto Translate residual checks.
 
-### 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.4.1] - 2026-06-02
 
-## [4.3.1] - 2026-05-31
-
-### Fixed
+### 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.
+- **HIGH**: `config-helper` dual-path resolution (when both `--source-dir` and `--i18n-dir` are explicit) now wraps each resolved path in `SecurityUtils.validatePath()`.
+- **MEDIUM**: JSON parsing now enforces maximum depth (1000) and maximum size (50 MB) limits in `safeParseJSON` to prevent denial-of-service via deeply nested or oversized JSON files.
+- **MEDIUM**: LibreTranslate custom URL (`LIBRETRANSLATE_URL`) now requires `I18NTK_ALLOW_CUSTOM_LIBRETRANSLATE_HOST=1` env flag to add arbitrary hosts to the allowed list, bringing parity with DeepL's gated approach.
+- **MEDIUM**: `sanitizeInput` default character whitelist tightened — removed `\\`, `{`, `}` characters that could enable path traversal or template injection.
+- **MEDIUM**: VSCode Workbench `workspaceScanner.ts` now validates auto-translate report paths with `normalizeWithinRoot()` and rejects JSON content > 50 MB.
+- **MEDIUM**: VSCode Workbench `localeFileService.ts` now validates `addKey()` write paths via `isPathWithinRoot()` and rejects locale files > 10 MB before parsing.
+- **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%).
+- `--strict-unused` flag: only reports high-confidence confirmed unused keys.
+- `--json` flag: outputs structured JSON report for automation and CI/CD.
+- `--prune` / `--prune-keep` flags: removes stale report files, keeping N most recent.
+- Mojibake detection: replacement-character artifacts like `Abwicklungspr?fung` and `L?ser` detected during translation analysis.
+- Client-boundary warnings: flags `"use client"` files that import locale JSON, which bypasses i18ntk runtime and increases bundle size.
+- Copy-formatter detection: identifies local `const tx = ...` functions that do not call known translation runtimes.
+- Wrapper configuration: `.i18ntk-config` now supports `usage.translationFunctions`, `usage.serverWrappers`, and `usage.copyFormatters`.
+- Next.js App Router detection: identifies `"use server"` / `"use client"` directives and reports component type.
+- VSCode `i18ntk.clearDiagnostics` command. Stale diagnostics now cleared at scan start.
+- VSCode new diagnostic codes: `i18ntk.clientBoundary` (warning), `i18ntk.copyFormatter` (warning).
+- Lens scanner: `detectSuspectedCopyFormatters()` and `findClientBoundaryLocaleImports()` exported.
+- Auto Translate now writes `i18ntk-reports/auto-translate/latest.json` when residual untranslated values remain after the final targeted retry, so follow-up tooling can retry only unresolved keys.
+- 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()`.
+- 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.
+- Locale JSON import detection properly deduplicates namespace prefix (e.g., `leaderboard.error` not `leaderboard.leaderboard.error`).
+- Literal key matching no longer credits telemetry/event call strings (e.g., `trackEvent("leaderboard.view")`) as translation usage, preventing CLI false negatives on genuinely unused keys.
+- 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.
+- Usage documentation now treats unused-key reports as advisory; do not bulk-delete keys from an unused report without manual verification or a more precise usage scan.
+
+## [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`.
 
-## [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.
-- Auto Translate no longer fails a run when a provider legitimately returns a short all-caps acronym or code unchanged, such as `XP`.
-- Manager option 7 and `i18ntk-fixer --check-placeholders` now run an English source placeholder audit, reporting any `[LANG] ...` values left in English locale files; a clean project reports `0` placeholders.
-- The management command router no longer prints a generic operation-success message when a command returns `{ success: false }`.
-
-## [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.
-- Validation summary reports now include warning and error details, including content-risk warning payloads, instead of only totals.
-
-## [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
+## [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.
+- Auto Translate no longer fails a run when a provider legitimately returns a short all-caps acronym or code unchanged, such as `XP`.
+- Manager option 7 and `i18ntk-fixer --check-placeholders` now run an English source placeholder audit, reporting any `[LANG] ...` values left in English locale files; a clean project reports `0` placeholders.
+- The management command router no longer prints a generic operation-success message when a command returns `{ success: false }`.
+
+## [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.
+- Validation summary reports now include warning and error details, including content-risk warning payloads, instead of only totals.
+
+## [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`.
@@ -135,20 +198,20 @@ 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.
+- 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.
+- Protection: Unicode-aware punctuation boundaries for CJK/Cyrillic/Arabic; standalone boundaries include the expanded punctuation set.
 
 ## [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()`.
+- **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.
 - **Validator Key Naming Convention**: `i18ntk-validate` adds `--enforce-key-style` flag and `keyStyle` config setting supporting `dot.notation`, `snake_case`, `camelCase`, `kebab-case`, and `flat` conventions. Reports all violating keys with suggested canonical forms.
 - **Scanner Multi-Language Detection**: `i18ntk-scanner` adds `--source-language` flag with character-class profiles for 12+ languages (English, German, French, Spanish, Japanese, Chinese, Russian, Korean, Arabic, Hindi, etc.). Language-specific stopword lists and key generation with transliteration for non-Latin scripts.
@@ -159,7 +222,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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
+### 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.
 

package/README.md

@@ -1,6 +1,6 @@
-# i18ntk v4.3.3
+# i18ntk v4.4.2
 
-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.
+A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
 
 ![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)
 
@@ -9,19 +9,11 @@ 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.3.3)](https://socket.dev/npm/package/i18ntk/overview/4.3.3)
-## VS Code Extensions
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.4.2)](https://socket.dev/npm/package/i18ntk/overview/4.4.2)
 
 [![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)
 
-Official VS Code extensions powered by i18ntk:
-
-- **i18ntk Workbench**: setup, scanning, validation, usage checks, reports, key management, and CLI-backed Auto Translate inside VS Code.
-- **i18ntk Lens**: lightweight inline hovers, CodeLens, missing-key warnings, unused-key diagnostics, key navigation, and settings.
-
-Install both when you want the full sidebar plus inline editor feedback.
-
 ## Install
 
 ```bash
@@ -35,59 +27,72 @@ npm install --save-dev i18ntk
 npx i18ntk --help
 ```
 
-Requirements:
-
-- Node.js `>=16.0.0`
-- npm `>=8.0.0`
-- No runtime dependencies
+## i18ntk Summary
 
-## What's New in 4.3.3
+**What it does**
 
-- **USAGE FIX**: Usage extraction no longer treats ordinary method calls such as `get("next")`, `headers.get("etag")`, `set(...)`, or `setItem(...)` as translation calls.
-- **USAGE FIX**: Local `tx(...)` wrappers and bounded dynamic `tx` template usages are resolved so real keys are less likely to appear unused.
-- **KEY STYLE**: Hybrid dot-path plus snake_case segment keys are valid, for example `namespace.section.snake_case_leaf`; malformed separators and uppercase segments are still reported.
-- **SAFETY**: Unused-key reports are advisory. Do not bulk-delete keys from an unused report without manual verification or a precise usage scan.
+- Manages locale files from the command line.
+- Finds missing, unused, risky, and inconsistent translation keys.
+- Produces validation and summary reports.
+- Supports framework-aware i18n workflows.
+- Provides a lightweight runtime translation toolkit.
 
-## What's New in 4.3.2
+**What it does not do**
 
-- **DOCS**: README, API docs, and migration guidance now reflect the current 4.3.2 package version.
-- **RELEASE**: 4.3.0 is marked for npm deprecation because its npm tarball is unavailable; install 4.3.1 or newer.
+- It is not a translation management SaaS.
+- It does not replace human translation review.
+- It does not force you to replace i18next, react-i18next, vue-i18n, or another runtime.
 
-## What's New in 4.3.1
+**Why not i18next?**
 
-- **FIX**: Published tarball now includes `utils/english-placeholder-checker.js`, resolving `MODULE_NOT_FOUND` at startup for `i18ntk-fixer --check-placeholders` and manager option 7.
-- **FIX**: Language-specific CLI entry points (`i18ntk-go`, `i18ntk-java`, `i18ntk-js`, `i18ntk-php`, `i18ntk-py`) and their shared `utils/mini-commander.js` dependency are now included in the published package.
-- **FIX**: Removed inconsistent `.js` extension suffixes from require paths in `main/i18ntk-js.js`.
+i18next 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.
 
-## What's New in 4.3.0
+| Need | i18ntk | i18next |
+| --- | --- | --- |
+| Runtime translation | Basic toolkit | Mature runtime |
+| Locale file scanning | Yes | No |
+| Missing key detection | Yes | No |
+| Unused key detection | Yes | No |
+| Validation reports | Yes | Limited |
+| Auto-translation workflow | Yes | External tooling |
 
-- **AUTO TRANSLATE**: Existing target values like `[AR] What We Offer`, `[AR] Email`, `[zh] Email`, and `[TR] Password` are now treated as untranslated placeholders for the matching target language and are translated from the source text.
-- **AUTO TRANSLATE**: Before writing each output file, Auto Translate now performs a final leftover check and retries any placeholder-prefixed or source-copy values once.
-- **AUTO TRANSLATE**: If leftovers remain after the final retry, the command warns, includes them in the report, recommends rerunning Auto Translate, and exits with validation failure instead of reporting a clean completion.
-- **AUTO TRANSLATE**: Managed Auto Translate now checks every selected source file for a target language before reporting leftovers, so one failed file does not prevent the rest from being audited.
-- **AUTO TRANSLATE**: Short all-caps acronyms and codes such as `XP` are allowed to remain unchanged instead of failing the final leftover check.
-- **FIX PLACEHOLDERS**: Menu option 7 now runs an English source placeholder audit and reports how many `[LANG] ...` values remain in English locale files. A clean project reports `0`.
-- **SIZING/USAGE**: Usage analysis no longer writes its inferred app source fallback back into the shared locale config, so running usage before sizing no longer makes sizing analyze the wrong directory.
-- **VALIDATION REPORTS**: Validation summary files now include warning and error details, including English-content warning payloads, instead of only totals.
-- **DOCS**: Versioned docs and migration guidance now reflect the current 4.3.0 command surface.
+## What's New in 4.4.2
 
-## What's New in 4.1.0
+- **AUTO TRANSLATE RELATIVE PATHS**: Programmatic `processFile()` calls now accept project-relative source paths, matching CLI source resolution.
+- **PROTECTED TERMS IN ONLY-MISSING MODE**: Existing translations that intentionally keep protected product terms such as `i18ntk` are no longer treated as English leftovers.
+- **BROKEN TARGET RETRIES**: Auto Translate now detects and retries more visibly broken target values, including mojibake, replacement characters, repeated question marks, and target-language prefix leftovers.
+- **REGRESSION COVERAGE**: Added focused tests for relative paths, protected product terms, broken values, placeholder handling, and residual checks.
 
-- **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.4.1
 
-## What's New in 4.0.0
+- **DEAD-KEY DETECTION**: Dead-key confidence 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.
+- **LOCALE JSON IMPORT DETECTION**: `import en from '../../locales/en/foo.json'` is now detected and property accesses are tracked as key usages, closing the gap between CLI and VSCode scanners.
+- **CONFIDENCE-SPLIT REPORTS**: Unused keys are now reported by confidence tier — confirmed (≥80%), likely (40-80%), possibly used (<40%) — instead of a flat list.
+- **NEW CLI FLAGS**: `--strict-unused` (only high-confidence keys), `--json` (structured JSON output for CI), `--prune` / `--prune-keep` (stale report cleanup).
+- **MOJIBAKE DETECTION**: Replacement-character artifacts like `Abwicklungspr?fung` and `L?ser` are detected during translation analysis.
+- **CLIENT-BOUNDARY WARNINGS**: `"use client"` files importing locale JSON are flagged — this bypasses the runtime and increases bundle size.
+- **COPY-FORMATTER DETECTION**: Local `const tx = ...` functions that don't call a translation runtime are identified as likely copy formatters, reducing false positive key noise.
+- **CONFIG FIX**: `--source-dir` and `--i18n-dir` are no longer forced equal when both are explicitly passed via CLI.
+- **Next.js DETECTION**: App Router files with `"use server"` / `"use client"` directives are now detected and reported by component type.
+- **VSCode DIAGNOSTICS**: New `i18ntk.clearDiagnostics` command. Stale diagnostics are now cleared at scan start. New diagnostic codes: `i18ntk.clientBoundary`, `i18ntk.copyFormatter`.
+- **AUTO TRANSLATE RESUME REPORTS**: If a provider still returns untranslated values after the final targeted retry, Auto Translate writes `i18ntk-reports/auto-translate/latest.json` so tooling can identify and retry only unresolved keys.
+- **VS CODE RESIDUAL PICKUP**: i18ntk Workbench and Lens read Auto Translate residual reports, show the affected locale JSON key in the editor, and can add intentionally unchanged keys to Auto Translate protection.
+- **WRAPPER CONFIG**: `.i18ntk-config` now supports `usage.translationFunctions`, `usage.serverWrappers`, and `usage.copyFormatters` for fine-grained control.
+- **TELEMETRY/EVENT STRING FILTERING**: String literals inside `trackEvent()`, `emitDomainEvent()`, `analytics.track()` and similar calls are classified as telemetry literals and no longer falsely counted as translation usage.
+- **OBJECT-METHOD KEY DETECTION**: input.tx("key"), helper.tx("key"), and .tx(\`dynamic.${var}\`) patterns are now recognized as translation calls alongside standalone `tx()` calls.
 
-- **SIZING**: `--predict-expansion` flag computes per-key expansion ratios across languages with Safe/Warning/Critical risk tiers for UI layout planning.
-- **WATCH**: `watchLocales()` now returns an EventEmitter-compatible watcher with debounced `change`/`add`/`unlink`/`error` events and SHA-256 hash tracking.
-- **USAGE**: `--cleanup` and `--dry-run-delete` flags identify dead translation keys with confidence scores.
-- **VALIDATOR**: `--enforce-key-style` enforces dot.notation, snake_case, camelCase, kebab-case, or flat naming conventions.
-- **SCANNER**: `--source-language` supports multi-language hardcoded text detection with 12+ language profiles.
-- **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.
+- **LOCAL WRAPPER RESOLUTION**: Functions like `const text = (key, fallback) => tx(key)` that internally call the translation runtime are detected, and their string-literal invocations are automatically resolved to actual keys.
 
 See [CHANGELOG.md](./CHANGELOG.md) for more release details.
 
+## Security hardening in 4.4.1
+
+- **PATH TRAVERSAL HARDENED**: Backup, complete, and config-helper commands now validate all user-supplied paths through `SecurityUtils.validatePath()`, blocking writes outside project boundaries.
+- **JSON DoS PREVENTED**: `safeParseJSON` enforces maximum depth (1000) and maximum size (50 MB) before parsing, preventing denial-of-service via deeply nested or oversized JSON.
+- **INPUT SANITIZATION TIGHTENED**: `sanitizeInput` default whitelist no longer allows backslashes or curly braces that could enable path traversal or template injection.
+
+- **LIBRETRANSLATE URL GATED**: Custom LibreTranslate host now requires `I18NTK_ALLOW_CUSTOM_LIBRETRANSLATE_HOST=1` env flag (parity with DeepL).
+
 ## Quick Start
 
 Initialize a project:
@@ -173,7 +178,7 @@ Note: manager route `i18ntk --command=backup` is disabled in current builds. Use
 | `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=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. |
 | `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, 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. |
@@ -573,7 +578,7 @@ See [docs/api/CONFIGURATION.md](./docs/api/CONFIGURATION.md) for the full config
 
 ## Public Package Contents
 
-The public package intentionally ships runtime and CLI files only. The publish staging script excludes development-only content such as tests, scripts, docs, release staging folders, local config files, and generated protection files.
+The public package intentionally ships runtime and CLI files only.
 
 The package includes: