i18ntk 4.1.0 → 4.2.1

package/CHANGELOG.md

@@ -3,11 +3,70 @@
 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.1.0] - 2026-05-21
-
-### Fixed
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [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`.

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v4.1.0
+# i18ntk v4.2.1
 
 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.1.0)](https://socket.dev/npm/package/i18ntk/overview/4.1.0)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.2.1)](https://socket.dev/npm/package/i18ntk/overview/4.2.1)
 
 ## Install
 
@@ -30,6 +30,15 @@ Requirements:
 - npm `>=8.0.0`
 - No runtime dependencies
 
+## What's New in 4.2.1
+
+- **AUTO TRANSLATE**: Existing target values like `[AR] What We Offer` 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.
+- **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.2.1 command surface.
+
 ## 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.
@@ -100,7 +109,6 @@ i18ntk --command=sizing
 i18ntk --command=complete
 i18ntk --command=translate
 i18ntk --command=summary
-i18ntk --command=debug
 ```
 
 Standalone executables:
@@ -119,12 +127,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>`
@@ -132,9 +157,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
@@ -147,7 +173,7 @@ Interactive manager flow:
 
 ```bash
 i18ntk
-# choose "Auto Translate (Beta)"
+# choose "Auto Translate"
 ```
 
 Direct CLI examples:
@@ -190,6 +216,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:
@@ -201,6 +229,9 @@ Auto Translate detects common placeholders such as:
 - `:id`
 - `%{name}`
 - `${value}`
+- `{count, plural, one {# item} other {# items}}`
+- `$t(common.save)`
+- `%(total).2f`
 
 Useful flags:
 
@@ -208,6 +239,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
 
@@ -247,7 +282,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.
 
@@ -255,7 +290,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
@@ -324,7 +359,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)
@@ -417,6 +452,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.
@@ -439,6 +484,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
@@ -449,23 +503,27 @@ Example:
 
 ```json
 {
-  "version": "4.1.0",
+  "version": "4.2.1",
   "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,
@@ -507,9 +565,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.1](./docs/migration-guide-v4.2.1.md)
 
 ## Security
 

package/SECURITY.md

@@ -4,7 +4,7 @@
 
 The supported production line is `4.x`.
 
-Versions earlier than `4.1.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, incremental backup hash-chain verification, and post-4.0.0 critical bug fixes for runtime staleness, backup verification, and CLI flag parsing.
+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,13 +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; 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.
+- **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
 
@@ -68,7 +74,7 @@ Security reports are reviewed privately first. Confirmed issues should receive:
 
 ## User Guidance
 
-- Keep i18ntk updated to `4.1.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);

package/main/i18ntk-backup.js

@@ -57,14 +57,35 @@ function computeFileHash(filePath) {
   }
 }
 
-function computeContentHash(content) {
+function computeContentHash(content) {
   if (typeof content === 'object' && content !== null) {
     const normalized = JSON.stringify(content);
     return crypto.createHash('sha256').update(normalized).digest('hex');
   }
   const str = String(content);
-  return crypto.createHash('sha256').update(str).digest('hex');
-}
+  return crypto.createHash('sha256').update(str).digest('hex');
+}
+
+async function collectJsonFiles(rootDir, currentDir = rootDir) {
+  const entries = await fsp.readdir(currentDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectJsonFiles(rootDir, fullPath));
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith('.json')) {
+      continue;
+    }
+
+    const relativePath = path.relative(rootDir, fullPath).split(path.sep).join('/');
+    files.push({ relativePath, fullPath });
+  }
+
+  return files;
+}
 
 async function findMostRecentBackup(backupDirPath) {
   try {
@@ -140,6 +161,51 @@ function readBackupData(backupPath, baseDir) {
   return JSON.parse(raw);
 }
 
+function validateBackupEntryName(fileName) {
+  if (!fileName || typeof fileName !== 'string') {
+    throw new Error('Invalid backup entry name');
+  }
+  if (fileName === '_meta') {
+    return null;
+  }
+  if (fileName.includes('\0') || /^[a-zA-Z]:/.test(fileName)) {
+    throw new Error(`Unsafe backup entry name: ${fileName}`);
+  }
+
+  const normalizedSeparators = fileName.replace(/\\/g, '/');
+  const rawSegments = normalizedSeparators.split('/');
+  const normalized = path.posix.normalize(normalizedSeparators);
+  const segments = normalized.split('/');
+
+  if (
+    path.posix.isAbsolute(normalizedSeparators) ||
+    rawSegments.some(segment => !segment || segment === '.' || segment === '..') ||
+    normalized === '.' ||
+    normalized === '..' ||
+    normalized.startsWith('../') ||
+    !normalized.endsWith('.json') ||
+    segments.some(segment => !segment || segment === '.' || segment === '..')
+  ) {
+    throw new Error(`Unsafe backup entry name: ${fileName}`);
+  }
+
+  return normalized;
+}
+
+function restoreBackupEntry(outputDir, fileName, content) {
+  const safeName = validateBackupEntryName(fileName);
+  if (!safeName) return false;
+
+  const filePath = SecurityUtils.safeJoin(outputDir, safeName);
+  if (!filePath) {
+    throw new Error(`Backup entry escapes restore directory: ${fileName}`);
+  }
+  if (!SecurityUtils.safeWriteFileSync(filePath, JSON.stringify(content, null, 2), outputDir, 'utf8')) {
+    throw new Error(`Unable to restore backup entry: ${fileName}`);
+  }
+  return true;
+}
+
 function collectProtectedChainNames(backupDirPath, keptFiles) {
   const protectedNames = new Set();
   const byName = new Map();
@@ -327,31 +393,29 @@ async function handleCreate(args) {
 
   logger.info('\nCreating backup...');
 
-  const files = (await fsp.readdir(sourceDir, { withFileTypes: true }))
-    .filter(dirent => dirent.isFile() && dirent.name.endsWith('.json'))
-    .map(dirent => dirent.name);
-
-  if (files.length === 0) {
-    logger.warn('No JSON files found in the specified directory');
-    process.exit(0);
-  }
-
-  const translations = {};
-  const hashes = {};
-  for (const file of files) {
-    const filePath = path.join(sourceDir, file);
-    try {
-      const rawContent = SecurityUtils.safeReadFileSync(filePath, path.dirname(filePath), 'utf8');
-      if (rawContent === null) {
-        logger.error(`Could not read file ${file}`);
-        continue;
-      }
-      translations[file] = JSON.parse(rawContent);
-      hashes[file] = computeFileHash(filePath);
-    } catch (error) {
-      logger.error(`Could not read file ${file}: ${error.message}`);
-    }
-  }
+  const files = await collectJsonFiles(sourceDir);
+
+  if (files.length === 0) {
+    logger.warn('No JSON files found in the specified directory');
+    process.exit(0);
+  }
+
+  const translations = {};
+  const hashes = {};
+  for (const file of files) {
+    const filePath = file.fullPath;
+    try {
+      const rawContent = SecurityUtils.safeReadFileSync(filePath, path.dirname(filePath), 'utf8');
+      if (rawContent === null) {
+        logger.error(`Could not read file ${file.relativePath}`);
+        continue;
+      }
+      translations[file.relativePath] = JSON.parse(rawContent);
+      hashes[file.relativePath] = computeFileHash(filePath);
+    } catch (error) {
+      logger.error(`Could not read file ${file.relativePath}: ${error.message}`);
+    }
+  }
 
   let meta = {
     type: 'full',
@@ -437,28 +501,26 @@ async function handleRestore(args) {
       const chain = await buildRestoreChain(backupPath, backupData);
       await fsp.mkdir(outputDir, { recursive: true });
 
-      const restoredFiles = new Set();
-      for (const entry of chain) {
-        for (const [file, content] of Object.entries(entry.data)) {
-          if (file === '_meta') continue;
-          const filePath = path.join(outputDir, file);
-          SecurityUtils.safeWriteFileSync(filePath, JSON.stringify(content, null, 2), path.dirname(filePath), 'utf8');
-          restoredFiles.add(file);
-        }
-      }
+      const restoredFiles = new Set();
+      for (const entry of chain) {
+        for (const [file, content] of Object.entries(entry.data)) {
+          if (restoreBackupEntry(outputDir, file, content)) {
+            restoredFiles.add(file);
+          }
+        }
+      }
 
       logger.success('Incremental backup restored successfully');
       logger.info(`  ${restoredFiles.size} files restored across ${chain.length} backup(s) to: ${outputDir}`);
     } else {
       await fsp.mkdir(outputDir, { recursive: true });
 
-      let count = 0;
-      for (const [file, content] of Object.entries(backupData)) {
-        if (file === '_meta') continue;
-        const filePath = path.join(outputDir, file);
-        SecurityUtils.safeWriteFileSync(filePath, JSON.stringify(content, null, 2), path.dirname(filePath), 'utf8');
-        count++;
-      }
+      let count = 0;
+      for (const [file, content] of Object.entries(backupData)) {
+        if (restoreBackupEntry(outputDir, file, content)) {
+          count++;
+        }
+      }
 
       logger.success('Backup restored successfully');
       logger.info(`  Restored ${count} files to: ${outputDir}`);