i18ntk 3.3.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18ntk",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "i18n Tool Kit - Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, auto translation, fixing, reporting, and runtime translation loading.",
   "readmeFilename": "README.md",
   "keywords": [
@@ -161,5 +161,5 @@
     "access": "public"
   },
   "preferGlobal": true,
-  "readme": "# i18ntk v3.3.0\n\nA 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.\n\n![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)\n\n[![npm version](https://img.shields.io/npm/v/i18ntk.svg?color=brightgreen)](https://www.npmjs.com/package/i18ntk)\n[![npm downloads](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)\n[![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)\n[![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)\n[![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![socket](https://socket.dev/api/badge/npm/package/i18ntk/3.3.0)](https://socket.dev/npm/package/i18ntk/overview/3.3.0)\n\n## Install\n\n```bash\n# global CLI use\nnpm install -g i18ntk\n\n# local project use\nnpm install --save-dev i18ntk\n\n# one-off execution\nnpx i18ntk --help\n```\n\nRequirements:\n\n- Node.js `>=16.0.0`\n- npm `>=8.0.0`\n- No runtime dependencies\n\n## What's New in 3.3.0\n\n- **SECURITY**: Eliminated all 21 dynamic `require()` calls flagged by Socket.dev; 20 converted to static string literals, 1 gated with `SecurityUtils.validatePath`.\n- **AUTO TRANSLATE**: Added provider selection for Google, DeepL, and LibreTranslate.\n- **FIX**: `i18ntk-complete` now fills missing target-language keys from English values with language prefixes instead of `NOT_TRANSLATED`.\n- **DOCS**: SECURITY.md updated with Socket.dev analysis disclaimer explaining expected alerts for a CLI/i18n toolkit.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for more release details.\n\n## Quick Start\n\nInitialize a project:\n\n```bash\ni18ntk\n# or with explicit command\ni18ntk --command=init\n```\n\nRun common checks:\n\n```bash\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk --command=sizing\ni18ntk --command=summary\n```\n\nComplete or fix translation files:\n\n```bash\ni18ntk --command=complete\ni18ntk-fixer --help\n```\n\nAuto-translate locale JSON:\n\n```bash\ni18ntk --command=translate\n# or\ni18ntk-translate locales/en/common.json de --report-stdout\n```\n\nThe full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).\n\n## Main Commands\n\nPrimary CLI:\n\n```bash\ni18ntk\ni18ntk --help\ni18ntk --command=init\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk --command=scanner\ni18ntk --command=sizing\ni18ntk --command=complete\ni18ntk --command=translate\ni18ntk --command=summary\ni18ntk --command=debug\n```\n\nStandalone executables:\n\n```bash\ni18ntk-init\ni18ntk-analyze\ni18ntk-validate\ni18ntk-usage\ni18ntk-scanner\ni18ntk-sizing\ni18ntk-complete\ni18ntk-summary\ni18ntk-doctor\ni18ntk-fixer\ni18ntk-backup\ni18ntk-translate\n```\n`n\nNote: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` (or legacy `i18ntk-backup`) directly for backup operations.\n\n## Common Options\n\nMost commands support:\n\n- `--source-dir <path>`\n- `--i18n-dir <path>`\n- `--output-dir <path>`\n- `--source-language <code>`\n- `--ui-language <code>`\n- `--no-prompt`\n- `--dry-run`\n- `--help`\n\nExample:\n\n```bash\ni18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports\n```\n\n## Auto Translate\n\nInteractive manager flow:\n\n```bash\ni18ntk\n# choose \"Auto Translate (Beta)\"\n```\n\nDirect CLI examples:\n\n```bash\ni18ntk-translate locales/en/common.json de\ni18ntk-translate locales/en/common.json fr --dry-run --report-stdout\ni18ntk-translate locales/en es --source-dir locales/en --files \"*.json\" --no-confirm --preserve-placeholders\n```\n\nProvider examples:\n\n```bash\nexport DEEPL_API_KEY=\"your-deepl-api-key\"\ni18ntk-translate locales/en/common.json de --provider deepl --no-confirm --preserve-placeholders\n\nexport LIBRETRANSLATE_URL=\"https://libretranslate.com/translate\"\nexport LIBRETRANSLATE_API_KEY=\"optional-api-key\"\ni18ntk-translate locales/en/common.json es --provider libretranslate --no-confirm --preserve-placeholders\n```\n\n`google` remains the default provider. You can also set `I18NTK_TRANSLATE_PROVIDER=deepl` or `I18NTK_TRANSLATE_PROVIDER=libretranslate`.\n\nProvider requests are HTTPS-only and response-size limited, and security logs redact provider query strings and response bodies. DeepL is pinned to official DeepL hosts by default; set `I18NTK_ALLOW_CUSTOM_TRANSLATE_HOSTS=1` only for a trusted DeepL-compatible proxy. Custom LibreTranslate URLs are blocked for localhost/private IP ranges unless `I18NTK_ALLOW_PRIVATE_TRANSLATE_URLS=1` is set for trusted local testing. Keep provider API keys in environment variables or a secret manager.\n\nThe manager flow asks for:\n\n- source locale directory, either the folder with JSON files or a locale root such as `./locales`\n- source language code\n- one or more target languages, or `all`\n- one JSON file or all JSON files in the source directory\n\nIf you select a locale root such as `./locales` and choose source language `en`, the manager automatically uses `./locales/en` when that folder contains the source JSON files.\n\nBefore writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:\n\n```text\nlocales/en/common.json\nlocales/de/common.json\nlocales/fr/common.json\n```\n\n### Placeholder Handling\n\nAuto Translate detects common placeholders such as:\n\n- `{name}`\n- `{{count}}`\n- `%s`\n- `%d`\n- `:id`\n- `%{name}`\n- `${value}`\n\nUseful flags:\n\n- `--preserve-placeholders`: translate text around placeholders and reinsert original tokens\n- `--skip-placeholders`: copy placeholder-bearing strings unchanged\n- `--send-placeholders`: send placeholder-bearing strings through translation after masking\n- `--custom-regex <regex>`: add project-specific placeholder detection\n\n### Protected Terms and Keys\n\nAuto Translate can create and use a project-local protection file:\n\n```bash\ni18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json\n```\n\nExample `i18ntk-auto-translate.json`:\n\n```json\n{\n  \"version\": 1,\n  \"terms\": [\"BrandName\", \"PRODUCT_CODE\", \"API\"],\n  \"keys\": [\"app.brandName\", \"legal.companyName\", \"product.*.symbol\"],\n  \"values\": [\"BrandName Ltd\", \"support@example.com\"],\n  \"patterns\": [\"[A-Z]{2,}-\\\\d+\"]\n}\n```\n\n- `terms` are masked before translation and restored exactly afterward.\n- `keys` are exact key paths or `*` wildcard paths copied unchanged.\n- `values` are exact source values copied unchanged.\n- `patterns` are JavaScript regex strings for advanced protected substrings.\n\nUseful flags:\n\n- `--protection-file <path>`\n- `--create-protection-file`\n- `--no-protection`\n\nOpen Settings and choose `Auto Translate 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.\n\nSee [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.\n\n## Validation\n\nValidation checks locale structure, completeness, placeholders, and content risks.\n\nIn 3.1.2, warning types are more specific:\n\n- `Potential risky content`: URL, email address, or secret-like value\n- `Possible untranslated English content`: target-language value appears to contain too much English\n\nEnglish-content warnings include:\n\n- detected English percentage\n- configured threshold\n- matched word count\n- sample matched words\n\nTune warnings in `.i18ntk-config`:\n\n```json\n{\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"]\n}\n```\n\n## Sizing Analysis\n\n`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.\n\n```bash\ni18ntk-sizing --source-dir ./locales --format table\ni18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports\n```\n\nUse `--detailed` to print per-file rows in the terminal.\n\n## Runtime API\n\nUse `i18ntk/runtime` when an application needs to read locale JSON files at runtime.\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nruntime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  fallbackLanguage: 'en',\n  keySeparator: '.',\n  preload: true\n});\n\nconsole.log(runtime.t('common.hello'));\nruntime.setLanguage('fr');\nconsole.log(runtime.getLanguage());\nconsole.log(runtime.getAvailableLanguages());\nruntime.refresh('fr');\n```\n\nSee [docs/runtime.md](./docs/runtime.md) for runtime details.\n\n## Configuration\n\ni18ntk uses a project-local `.i18ntk-config` file.\n\nExample:\n\n```json\n{\n  \"version\": \"3.3.0\",\n  \"sourceDir\": \"./locales\",\n  \"i18nDir\": \"./locales\",\n  \"outputDir\": \"./i18ntk-reports\",\n  \"sourceLanguage\": \"en\",\n  \"defaultLanguages\": [\"de\", \"es\", \"fr\", \"ru\"],\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"],\n  \"autoTranslate\": {\n    \"placeholderMode\": \"preserve\",\n    \"concurrency\": 6,\n    \"batchSize\": 100,\n    \"progressInterval\": 25,\n    \"retryCount\": 3,\n    \"retryDelay\": 1000,\n    \"timeout\": 15000,\n    \"dryRunFirst\": true,\n    \"reportStdout\": true,\n    \"bom\": false,\n    \"protectionEnabled\": true,\n    \"protectionFile\": \"./i18ntk-auto-translate.json\",\n    \"promptProtectionSetup\": true,\n    \"promptProtectionUpdate\": true\n  },\n  \"setup\": {\n    \"completed\": true\n  }\n}\n```\n\nSee [docs/api/CONFIGURATION.md](./docs/api/CONFIGURATION.md) for the full configuration model.\n\n## Public Package Contents\n\nThe public package intentionally ships runtime and CLI files only. The publish staging script excludes development-only content such as tests, scripts, docs, release staging folders, local config files, and generated protection files.\n\nThe package includes:\n\n- CLI entry points under `main/`\n- manager commands and services\n- runtime API files under `runtime/`\n- settings UI files required at runtime\n- bundled internal UI locales\n- shared utilities required by the shipped commands\n- `README.md`, `CHANGELOG.md`, `LICENSE`, and policy files\n\nThe public package manifest includes `readmeFilename: \"README.md\"`, and the release staging script fails if `README.md` is missing or empty.\n\n## Documentation\n\n- [Documentation Index](./docs/README.md)\n- [Getting Started](./docs/getting-started.md)\n- [API Reference](./docs/api/API_REFERENCE.md)\n- [Configuration Guide](./docs/api/CONFIGURATION.md)\n- [Runtime API Guide](./docs/runtime.md)\n- [Auto Translate Guide](./docs/auto-translate.md)\n- [Scanner Guide](./docs/scanner-guide.md)\n- [Environment Variables](./docs/environment-variables.md)\n- [Migration Guide v3.2.0](./docs/migration-guide-v3.2.0.md)\n- [Migration Guide v3.1.1](./docs/migration-guide-v3.1.1.md)\n- [Migration Guide v3.0.0](./docs/migration-guide-v3.0.0.md)\n\n## Security\n\n- No API key is required for the default Auto Translate flow.\n- Do not store secrets in locale files, `.i18ntk-config`, or protection files.\n- Project-specific brand/product terms should be configured by the user, not hardcoded into the package.\n- Report security issues using [SECURITY.md](./SECURITY.md).\n\n## Community\n\n- [Contributing](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Funding](./FUNDING.md)\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n"
+  "readme": "# i18ntk v4.0.0\n\nA 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.\n\n![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)\n\n[![npm version](https://img.shields.io/npm/v/i18ntk.svg?color=brightgreen)](https://www.npmjs.com/package/i18ntk)\n[![npm downloads](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)\n[![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)\n[![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)\n[![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.0.0)](https://socket.dev/npm/package/i18ntk/overview/4.0.0)\n\n## Install\n\n```bash\n# global CLI use\nnpm install -g i18ntk\n\n# local project use\nnpm install --save-dev i18ntk\n\n# one-off execution\nnpx i18ntk --help\n```\n\nRequirements:\n\n- Node.js `>=16.0.0`\n- npm `>=8.0.0`\n- No runtime dependencies\n\n## What's New in 4.0.0\n\n- **SIZING**: `--predict-expansion` flag computes per-key expansion ratios across languages with Safe/Warning/Critical risk tiers for UI layout planning.\n- **WATCH**: `watchLocales()` now returns an EventEmitter-compatible watcher with debounced `change`/`add`/`unlink`/`error` events and SHA-256 hash tracking.\n- **USAGE**: `--cleanup` and `--dry-run-delete` flags identify dead translation keys with confidence scores.\n- **VALIDATOR**: `--enforce-key-style` enforces dot.notation, snake_case, camelCase, kebab-case, or flat naming conventions.\n- **SCANNER**: `--source-language` supports multi-language hardcoded text detection with 12+ language profiles.\n- **BACKUP**: `--incremental` flag creates differential backups with SHA-256 hashing and chained restores.\n- **RUNTIME**: `lazy: true` option defers locale file loading until first key access for lower memory usage.\n- **PROTECTION**: Context-aware rules (`after:word`, `before:word`, `standalone`, `surrounded:left,right`) for precise term masking.\n- **FIX**: `initRuntime()` now returns independent instances with isolated language and cache state.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for more release details.\n\n## Quick Start\n\nInitialize a project:\n\n```bash\ni18ntk\n# or with explicit command\ni18ntk --command=init\n```\n\nRun common checks:\n\n```bash\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk --command=sizing\ni18ntk --command=summary\n```\n\nComplete or fix translation files:\n\n```bash\ni18ntk --command=complete\ni18ntk-fixer --help\n```\n\nAuto-translate locale JSON:\n\n```bash\ni18ntk --command=translate\n# or\ni18ntk-translate locales/en/common.json de --report-stdout\n```\n\nThe full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).\n\n## Main Commands\n\nPrimary CLI:\n\n```bash\ni18ntk\ni18ntk --help\ni18ntk --command=init\ni18ntk --command=analyze\ni18ntk --command=validate\ni18ntk --command=usage\ni18ntk --command=scanner\ni18ntk --command=sizing\ni18ntk --command=complete\ni18ntk --command=translate\ni18ntk --command=summary\ni18ntk --command=debug\n```\n\nStandalone executables:\n\n```bash\ni18ntk-init\ni18ntk-analyze\ni18ntk-validate\ni18ntk-usage\ni18ntk-scanner\ni18ntk-sizing\ni18ntk-complete\ni18ntk-summary\ni18ntk-doctor\ni18ntk-fixer\ni18ntk-backup\ni18ntk-translate\n```\n`n\nNote: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` (or legacy `i18ntk-backup`) directly for backup operations.\n\n## Common Options\n\nMost commands support:\n\n- `--source-dir <path>`\n- `--i18n-dir <path>`\n- `--output-dir <path>`\n- `--source-language <code>`\n- `--ui-language <code>`\n- `--no-prompt`\n- `--dry-run`\n- `--help`\n\nExample:\n\n```bash\ni18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports\n```\n\n## Auto Translate\n\nInteractive manager flow:\n\n```bash\ni18ntk\n# choose \"Auto Translate (Beta)\"\n```\n\nDirect CLI examples:\n\n```bash\ni18ntk-translate locales/en/common.json de\ni18ntk-translate locales/en/common.json fr --dry-run --report-stdout\ni18ntk-translate locales/en es --source-dir locales/en --files \"*.json\" --no-confirm --preserve-placeholders\n```\n\nProvider examples:\n\n```bash\nexport DEEPL_API_KEY=\"your-deepl-api-key\"\ni18ntk-translate locales/en/common.json de --provider deepl --no-confirm --preserve-placeholders\n\nexport LIBRETRANSLATE_URL=\"https://libretranslate.com/translate\"\nexport LIBRETRANSLATE_API_KEY=\"optional-api-key\"\ni18ntk-translate locales/en/common.json es --provider libretranslate --no-confirm --preserve-placeholders\n```\n\n`google` remains the default provider. You can also set `I18NTK_TRANSLATE_PROVIDER=deepl` or `I18NTK_TRANSLATE_PROVIDER=libretranslate`.\n\nProvider requests are HTTPS-only and response-size limited, and security logs redact provider query strings and response bodies. DeepL is pinned to official DeepL hosts by default; set `I18NTK_ALLOW_CUSTOM_TRANSLATE_HOSTS=1` only for a trusted DeepL-compatible proxy. Custom LibreTranslate URLs are blocked for localhost/private IP ranges unless `I18NTK_ALLOW_PRIVATE_TRANSLATE_URLS=1` is set for trusted local testing. Keep provider API keys in environment variables or a secret manager.\n\nThe manager flow asks for:\n\n- source locale directory, either the folder with JSON files or a locale root such as `./locales`\n- source language code\n- one or more target languages, or `all`\n- one JSON file or all JSON files in the source directory\n\nIf you select a locale root such as `./locales` and choose source language `en`, the manager automatically uses `./locales/en` when that folder contains the source JSON files.\n\nBefore writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:\n\n```text\nlocales/en/common.json\nlocales/de/common.json\nlocales/fr/common.json\n```\n\n### Placeholder Handling\n\nAuto Translate detects common placeholders such as:\n\n- `{name}`\n- `{{count}}`\n- `%s`\n- `%d`\n- `:id`\n- `%{name}`\n- `${value}`\n\nUseful flags:\n\n- `--preserve-placeholders`: translate text around placeholders and reinsert original tokens\n- `--skip-placeholders`: copy placeholder-bearing strings unchanged\n- `--send-placeholders`: send placeholder-bearing strings through translation after masking\n- `--custom-regex <regex>`: add project-specific placeholder detection\n\n### Protected Terms and Keys\n\nAuto Translate can create and use a project-local protection file:\n\n```bash\ni18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json\n```\n\nExample `i18ntk-auto-translate.json`:\n\n```json\n{\n  \"version\": 1,\n  \"terms\": [\n    \"BrandName\",\n    \"PRODUCT_CODE\",\n    { \"value\": \"OK\", \"context\": \"after:Click|Press|Tap\" },\n    { \"value\": \"API\", \"context\": \"standalone\" }\n  ],\n  \"keys\": [\"app.brandName\", \"legal.companyName\", \"product.*.symbol\"],\n  \"values\": [\"BrandName Ltd\", \"support@example.com\"],\n  \"patterns\": [\"[A-Z]{2,}-\\\\d+\"]\n}\n```\n\n- `terms` are masked before translation and restored exactly afterward.\n  - **Plain strings**: masked everywhere (backward compatible).\n  - **Context objects**: masked only in specific contexts (`after:word`, `before:word`, `standalone`, `surrounded:left,right`).\n- `keys` are exact key paths or `*` wildcard paths copied unchanged.\n- `values` are exact source values copied unchanged.\n- `patterns` are JavaScript regex strings for advanced protected substrings.\n\nUseful flags:\n\n- `--protection-file <path>`\n- `--create-protection-file`\n- `--no-protection`\n\nOpen Settings and choose `Auto Translate 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.\n\nSee [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.\n\n## Validation\n\nValidation checks locale structure, completeness, placeholders, and content risks.\n\nIn 3.1.2, warning types are more specific:\n\n- `Potential risky content`: URL, email address, or secret-like value\n- `Possible untranslated English content`: target-language value appears to contain too much English\n\nEnglish-content warnings include:\n\n- detected English percentage\n- configured threshold\n- matched word count\n- sample matched words\n\nTune warnings in `.i18ntk-config`:\n\n```json\n{\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"]\n}\n```\n\n## Sizing Analysis\n\n`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.\n\n```bash\ni18ntk-sizing --source-dir ./locales --format table\ni18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports\n```\n\nUse `--detailed` to print per-file rows in the terminal.\n\n### Expansion Prediction (New in 4.0.0)\n\nPredict UI layout overflow risk by analyzing per-key character-count expansion across languages:\n\n```bash\ni18ntk-sizing --source-dir ./locales --predict-expansion --output-report\n```\n\nExpansion ratios are classified into risk tiers:\n\n- **Safe** (<30% expansion): no UI impact expected\n- **Warning** (30–50%): may overflow in tight layouts — test on target languages\n- **Critical** (>50%): high risk of truncation — review UI element sizing\n\nThe report includes a built-in language-pair expansion reference table (EN→DE +35%, EN→RU +50%, EN→JA −40%, etc.) and lists the top-30 most-expanded keys.\n\n## Scanner: Multi-Language Detection (New in 4.0.0)\n\n`i18ntk-scanner` now supports detecting hardcoded text in multiple source languages beyond English:\n\n```bash\ni18ntk-scanner --source-dir ./src --source-language de\ni18ntk-scanner --source-dir ./src --source-language ja --output-report\n```\n\nSupported language profiles (12+): English, German, French, Spanish, Japanese, Chinese, Russian, Korean, Arabic, Hindi, and more. Each profile includes language-specific character ranges, stopword lists for false-positive filtering, and transliteration rules for key generation.\n\n## Usage: Dead Key Detection (New in 4.0.0)\n\n`i18ntk-usage` can identify translation keys that are defined but never referenced in source code:\n\n```bash\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup\ni18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup --dry-run-delete\n```\n\nEach dead key receives a confidence score (0.0–1.0) factoring:\n- Dynamic key patterns (e.g., `` t(`prefix.${dynamic}`) ``) — lower score\n- Key appears in source code comments or JSDoc — medium score\n- Parent file recently modified (<30 days) — medium score\n- No references found anywhere — high score (>0.8)\n\nThe `--dry-run-delete` flag writes a `.dead-keys.json` report for review before any destructive action.\n\n## Validator: Key Naming Conventions (New in 4.0.0)\n\nEnforce consistent translation key naming across your project:\n\n```bash\ni18ntk-validate --enforce-key-style\n```\n\nConfigure the expected style in `.i18ntk-config`:\n\n```json\n{\n  \"keyStyle\": \"dot.notation\"\n}\n```\n\nSupported styles: `dot.notation`, `snake_case`, `camelCase`, `kebab-case`, `flat`. Violations are reported as warnings with suggested canonical forms.\n\n## Watch: Hot Reload (New in 4.0.0)\n\n`utils/watch-locales.js` now provides debounced file watching with EventEmitter support:\n\n```js\nconst watchLocales = require('i18ntk/utils/watch-locales');\nconst watcher = watchLocales('./locales');\n\nwatcher.on('change', (filePath) => {\n  console.log('Locale changed:', filePath);\n});\n\nwatcher.on('add', (filePath) => {\n  console.log('Locale added:', filePath);\n});\n\n// Later:\nwatcher.stop();\n```\n\nFeatures: 300ms debounce (configurable), SHA-256 hash tracking to skip no-change saves, and a maximum of 50 watched directories.\n\n### Migration\n\nThe `watchLocales` return value gained EventEmitter methods in v4.0.0. Existing stop-function usage still works:\n\n```js\nconst stop = watchLocales('./locales', onChange);\n```\n\nCan be updated to:\n\n```js\nconst watcher = watchLocales('./locales');\nwatcher.on('change', onChange);\nwatcher.stop();\n```\n\nPassing a callback as the second argument is still supported — it auto-subscribes to `change` and `add` events.\n\n## Backup: Incremental Mode (New in 4.0.0)\n\nCreate differential backups that only include changed files:\n\n```bash\ni18ntk-backup create ./locales --incremental\n```\n\nIncremental backups store SHA-256 hashes per file and a parent-chain reference. Restoring an incremental backup automatically chains from the oldest full backup through each incremental diff in order. Chain depth is capped at 10 increments. Use `verify` to validate the hash chain.\n\n## Runtime: Lazy Loading (New in 4.0.0)\n\nReduce memory usage by deferring locale file loads until first key access:\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  lazy: true\n});\n\nconsole.log(i18n.t('common.hello')); // loads common.json on first access\n```\n\nWhen `lazy: true`, the runtime builds a key-to-file manifest on first access and loads individual files on demand. Files are loaded once and cached. If the manifest is missing or incomplete, the runtime falls back to full eager loading for that language. Manifest size is capped at 100KB with path containment validation.\n\n## Runtime API\n\nUse `i18ntk/runtime` when an application needs to read locale JSON files at runtime.\n\n```js\nconst runtime = require('i18ntk/runtime');\n\nconst i18n = runtime.initRuntime({\n  baseDir: './locales',\n  language: 'en',\n  fallbackLanguage: 'en',\n  keySeparator: '.',\n  preload: true\n});\n\nconsole.log(i18n.t('common.hello'));\ni18n.setLanguage('fr');\nconsole.log(i18n.getLanguage());\nconsole.log(i18n.getAvailableLanguages());\ni18n.refresh('fr');\n```\n\nSee [docs/runtime.md](./docs/runtime.md) for runtime details.\n\n## Configuration\n\ni18ntk uses a project-local `.i18ntk-config` file.\n\nExample:\n\n```json\n{\n  \"version\": \"4.0.0\",\n  \"sourceDir\": \"./locales\",\n  \"i18nDir\": \"./locales\",\n  \"outputDir\": \"./i18ntk-reports\",\n  \"sourceLanguage\": \"en\",\n  \"defaultLanguages\": [\"de\", \"es\", \"fr\", \"ru\"],\n  \"englishContentThresholdPercent\": 10,\n  \"allowedEnglishTerms\": [\"BrandName\", \"PRODUCT_CODE\"],\n  \"autoTranslate\": {\n    \"placeholderMode\": \"preserve\",\n    \"concurrency\": 6,\n    \"batchSize\": 100,\n    \"progressInterval\": 25,\n    \"retryCount\": 3,\n    \"retryDelay\": 1000,\n    \"timeout\": 15000,\n    \"dryRunFirst\": true,\n    \"reportStdout\": true,\n    \"bom\": false,\n    \"protectionEnabled\": true,\n    \"protectionFile\": \"./i18ntk-auto-translate.json\",\n    \"promptProtectionSetup\": true,\n    \"promptProtectionUpdate\": true\n  },\n  \"setup\": {\n    \"completed\": true\n  }\n}\n```\n\nSee [docs/api/CONFIGURATION.md](./docs/api/CONFIGURATION.md) for the full configuration model.\n\n## Public Package Contents\n\nThe public package intentionally ships runtime and CLI files only. The publish staging script excludes development-only content such as tests, scripts, docs, release staging folders, local config files, and generated protection files.\n\nThe package includes:\n\n- CLI entry points under `main/`\n- manager commands and services\n- runtime API files under `runtime/`\n- settings UI files required at runtime\n- bundled internal UI locales\n- shared utilities required by the shipped commands\n- `README.md`, `CHANGELOG.md`, `LICENSE`, and policy files\n\nThe public package manifest includes `readmeFilename: \"README.md\"`, and the release staging script fails if `README.md` is missing or empty.\n\n## Documentation\n\n- [Documentation Index](./docs/README.md)\n- [Getting Started](./docs/getting-started.md)\n- [API Reference](./docs/api/API_REFERENCE.md)\n- [Configuration Guide](./docs/api/CONFIGURATION.md)\n- [Runtime API Guide](./docs/runtime.md)\n- [Auto Translate Guide](./docs/auto-translate.md)\n- [Scanner Guide](./docs/scanner-guide.md)\n- [Environment Variables](./docs/environment-variables.md)\n- [Migration Guide v3.2.0](./docs/migration-guide-v3.2.0.md)\n- [Migration Guide v3.1.1](./docs/migration-guide-v3.1.1.md)\n- [Migration Guide v3.0.0](./docs/migration-guide-v3.0.0.md)\n\n## Security\n\n- No API key is required for the default Auto Translate flow.\n- Do not store secrets in locale files, `.i18ntk-config`, or protection files.\n- Project-specific brand/product terms should be configured by the user, not hardcoded into the package.\n- Report security issues using [SECURITY.md](./SECURITY.md).\n\n## Community\n\n- [Contributing](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Funding](./FUNDING.md)\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n"
 }

package/runtime/i18ntk.d.ts

@@ -471,11 +471,11 @@ export interface BasicI18nRuntime {
    */
   getAvailableLanguages(): string[];
   
-  /**
-   * Refresh translations
-   */
-  refresh(): void;
-}
+  /**
+   * Refresh translations
+   */
+  refresh(language?: string): void;
+}
 
 /**
  * Initialize the enhanced i18ntk runtime (async, returns full I18nRuntime)
@@ -486,16 +486,22 @@ export declare function initI18nRuntime(config: I18nConfig): Promise<I18nRuntime
  * Initialize the basic lightweight runtime (synchronous)
  * This is the default export from 'i18ntk/runtime'
  */
-export declare function initRuntime(options: {
-  baseDir: string;
-  language?: string;
-  fallbackLanguage?: string;
-  keySeparator?: string;
-  preload?: boolean;
-}): BasicI18nRuntime;
-
-/**
- * Type guards (runtime checks, not exported by actual code)
+export declare function initRuntime(options: {
+  baseDir: string;
+  language?: string;
+  fallbackLanguage?: string;
+  keySeparator?: string;
+  preload?: boolean;
+  lazy?: boolean;
+}): BasicI18nRuntime;
+
+/**
+ * Build the lightweight runtime lazy-loading key manifest for a locale path.
+ */
+export declare function loadKeyManifest(baseDir?: string): Map<string, string>;
+
+/**
+ * Type guards (runtime checks, not exported by actual code)
  */
 export declare function isI18nRuntime(obj: any): obj is I18nRuntime;
 export declare function isBasicI18nRuntime(obj: any): obj is BasicI18nRuntime;
@@ -538,4 +544,4 @@ declare global {
 /**
  * Export all interfaces and types
  */
-export * from './enhanced';
+export * from './enhanced';

package/runtime/index.d.ts

@@ -4,10 +4,11 @@
 export interface InitOptions {
   baseDir?: string;
   language?: string;
-  fallbackLanguage?: string;
-  keySeparator?: string;
-  preload?: boolean;
-}
+  fallbackLanguage?: string;
+  keySeparator?: string;
+  preload?: boolean;
+  lazy?: boolean;
+}
 
 export type TranslateParams = Record<string, unknown>;
 
@@ -24,6 +25,7 @@ export function initRuntime(options?: InitOptions): {
 };
 
 export function setLanguage(lang: string): void;
-export function getLanguage(): string;
-export function getAvailableLanguages(): string[];
-export function refresh(lang?: string): void;
+export function getLanguage(): string;
+export function getAvailableLanguages(): string[];
+export function refresh(lang?: string): void;
+export function loadKeyManifest(baseDir?: string): Map<string, string>;

package/runtime/index.js

@@ -11,13 +11,32 @@ const { envManager } = require('../utils/env-manager');
 let configManager = null;
 try { configManager = require('../utils/config-manager'); } catch (_) { /* optional */ }
 
-const state = {
+function createState(options = {}) {
+  return {
+    baseDir: resolveBaseDir(options.baseDir),
+    language: options.language || 'en',
+    fallbackLanguage: options.fallbackLanguage || 'en',
+    keySeparator: options.keySeparator || '.',
+    cache: new Map(),
+    lazy: options.lazy === true,
+    keyManifest: new Map(),
+    loadedFiles: new Set(),
+    eagerLoadedLanguages: new Set(),
+  };
+}
+
+const singletonState = {
   baseDir: null,                // absolute path to locales dir (e.g., ./locales)
   language: 'en',
   fallbackLanguage: 'en',
-  keySeparator: '.',
-  cache: new Map(),             // lang -> merged translations object
-};
+  keySeparator: '.',
+  cache: new Map(),             // lang -> merged translations object
+  lazy: false,
+  keyManifest: new Map(),       // lang -> Map: keyName -> filePath
+  loadedFiles: new Set(),       // tracks loaded files in lazy mode
+  eagerLoadedLanguages: new Set(),
+};
+let singletonInitialized = false;
 
 // --- Utilities ---
 function stripBOMAndComments(s) {
@@ -98,12 +117,12 @@ function resolveBaseDir(explicitBaseDir) {
   }
 }
 
-function listJsonFilesRecursively(dir) {
+function listJsonFilesRecursively(dir, baseDir = dir) {
   const results = [];
   const stack = [dir];
   while (stack.length) {
     const d = stack.pop();
-    if (!SecurityUtils.safeExistsSync(d)) continue;
+    if (!SecurityUtils.safeExistsSync(d, baseDir)) continue;
     try {
       for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
         const full = path.join(d, entry.name);
@@ -120,6 +139,86 @@ function listJsonFilesRecursively(dir) {
   return results;
 }
 
+function loadKeyManifestFromDir(baseDir) {
+  const validatedBase = SecurityUtils.validatePath(baseDir, path.dirname(baseDir));
+  const baseStat = SecurityUtils.safeStatSync(validatedBase, path.dirname(validatedBase));
+  const baseRoot = baseStat && baseStat.isFile() ? path.dirname(validatedBase) : validatedBase;
+  const files = baseStat && baseStat.isFile() ? [validatedBase] : listJsonFilesRecursively(validatedBase, validatedBase);
+  const manifest = new Map();
+  const MAX_SIZE = 100 * 1024;
+  let currentSize = 0;
+
+  for (const file of files) {
+    let validated;
+    try { validated = SecurityUtils.validatePath(file, baseRoot); } catch (_) { continue; }
+    const rel = path.relative(baseRoot, validated);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) continue;
+
+    try {
+      const data = readJsonSafe(validated);
+      if (!data || typeof data !== 'object') continue;
+
+      for (const key of Object.keys(data)) {
+        if (manifest.has(key)) continue;
+
+        const entrySize = JSON.stringify(key).length + JSON.stringify(validated).length + 5;
+        if (currentSize + entrySize > MAX_SIZE) break;
+
+        manifest.set(key, validated);
+        currentSize += entrySize;
+      }
+    } catch (_) { continue; }
+
+    if (currentSize >= MAX_SIZE) break;
+  }
+
+  return manifest;
+}
+
+function getLanguagePath(baseDir, lang) {
+  const langDir = path.join(baseDir, lang);
+  const langFile = path.join(baseDir, `${lang}.json`);
+  const langDirStat = SecurityUtils.safeStatSync(langDir, path.dirname(langDir));
+  if (langDirStat && langDirStat.isDirectory()) return langDir;
+  const langFileStat = SecurityUtils.safeStatSync(langFile, path.dirname(langFile));
+  if (langFileStat && langFileStat.isFile()) return langFile;
+  return null;
+}
+
+function getManifestForLanguage(runtimeState, lang) {
+  if (!runtimeState.keyManifest) runtimeState.keyManifest = new Map();
+  if (runtimeState.keyManifest.has(lang)) return runtimeState.keyManifest.get(lang);
+
+  const languagePath = getLanguagePath(runtimeState.baseDir, lang);
+  const manifest = languagePath ? loadKeyManifestFromDir(languagePath) : new Map();
+  runtimeState.keyManifest.set(lang, manifest);
+  return manifest;
+}
+
+function loadFileLazy(runtimeState, filePath, lang) {
+  const baseDir = runtimeState.baseDir;
+  if (!baseDir) throw new Error('baseDir not initialized');
+
+  let validatedPath;
+  try { validatedPath = SecurityUtils.validatePath(filePath, baseDir); } catch (e) {
+    throw new Error(`Invalid file path for lazy load: ${e.message}`);
+  }
+
+  const rel = path.relative(baseDir, validatedPath);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`File outside base directory: ${filePath}`);
+  }
+
+  const data = readJsonSafe(validatedPath);
+  if (data && typeof data === 'object') {
+    let cacheEntry = runtimeState.cache.get(lang);
+    if (!cacheEntry) cacheEntry = {};
+    deepMerge(cacheEntry, data);
+    runtimeState.cache.set(lang, cacheEntry);
+  }
+  return data;
+}
+
 function readLanguageFromBase(baseDir, lang) {
   const merged = {};
   const langFile = path.join(baseDir, `${lang}.json`);
@@ -128,7 +227,7 @@ function readLanguageFromBase(baseDir, lang) {
   // Prefer folder if exists, otherwise single file
   const langDirStat = SecurityUtils.safeStatSync(langDir, path.dirname(langDir));
   if (langDirStat && langDirStat.isDirectory()) {
-    const files = listJsonFilesRecursively(langDir);
+    const files = listJsonFilesRecursively(langDir, langDir);
     for (const file of files) {
       try {
         const data = readJsonSafe(file);
@@ -150,10 +249,19 @@ function readLanguageFromBase(baseDir, lang) {
   return merged;
 }
 
-function getTranslations(lang) {
-  if (state.cache.has(lang)) return state.cache.get(lang);
-  const data = readLanguageFromBase(state.baseDir, lang);
-  state.cache.set(lang, data);
+function getTranslationsForState(runtimeState, lang) {
+  if (!runtimeState.baseDir) runtimeState.baseDir = resolveBaseDir();
+
+  if (runtimeState.lazy) {
+    if (runtimeState.cache.has(lang)) return runtimeState.cache.get(lang);
+    runtimeState.cache.set(lang, {});
+    getManifestForLanguage(runtimeState, lang);
+    return runtimeState.cache.get(lang);
+  }
+
+  if (runtimeState.cache.has(lang)) return runtimeState.cache.get(lang);
+  const data = readLanguageFromBase(runtimeState.baseDir, lang);
+  runtimeState.cache.set(lang, data);
   return data;
 }
 
@@ -165,15 +273,38 @@ function interpolate(template, params) {
 }
 
 // Resolve a dotted key path from an object
-function resolveKey(obj, key, sep = '.') {
-  if (!obj || typeof obj !== 'object') return undefined;
-  if (!key || typeof key !== 'string') return undefined;
+function resolveKey(obj, key, sep = '.', runtimeState = null, lang = null) {
+  if (!obj || typeof obj !== 'object') return undefined;
+  if (!key || typeof key !== 'string') return undefined;
   const parts = key.split(sep);
   let cur = obj;
   for (const p of parts) {
     if (cur && Object.prototype.hasOwnProperty.call(cur, p)) {
       cur = cur[p];
     } else {
+      if (runtimeState && lang && runtimeState.lazy) {
+        const manifest = getManifestForLanguage(runtimeState, lang);
+        for (let i = parts.length; i > 0; i--) {
+          const prefix = parts.slice(0, i).join(sep);
+          const filePath = manifest.get(prefix);
+          const loadedFileKey = `${lang}\0${filePath}`;
+          if (filePath && !runtimeState.loadedFiles.has(loadedFileKey)) {
+            loadFileLazy(runtimeState, filePath, lang);
+            runtimeState.loadedFiles.add(loadedFileKey);
+            const langData = runtimeState.cache.get(lang);
+            return resolveKey(langData, key, sep, runtimeState, lang);
+          }
+        }
+        if (!runtimeState.eagerLoadedLanguages.has(lang)) {
+          const fullData = readLanguageFromBase(runtimeState.baseDir, lang);
+          const langData = runtimeState.cache.get(lang) || {};
+          deepMerge(langData, fullData);
+          runtimeState.cache.set(lang, langData);
+          runtimeState.eagerLoadedLanguages.add(lang);
+          return resolveKey(langData, key, sep, runtimeState, lang);
+        }
+        return undefined;
+      }
       return undefined;
     }
   }
@@ -182,62 +313,110 @@ function resolveKey(obj, key, sep = '.') {
 
 // --- Public API ---
 function initRuntime(options = {}) {
-  state.baseDir = resolveBaseDir(options.baseDir);
-  state.language = options.language || state.language || 'en';
-  state.fallbackLanguage = options.fallbackLanguage || state.fallbackLanguage || 'en';
-  state.keySeparator = options.keySeparator || state.keySeparator || '.';
-  // Optional prewarm caches
-  state.cache.clear();
-  if (options.preload === true) {
-    getTranslations(state.language);
-    if (state.fallbackLanguage && state.fallbackLanguage !== state.language) {
-      getTranslations(state.fallbackLanguage);
+  const runtimeState = createState(options);
+  preload(runtimeState, options.preload);
+
+  if (!singletonInitialized) {
+    singletonState.baseDir = runtimeState.baseDir;
+    singletonState.language = runtimeState.language;
+    singletonState.fallbackLanguage = runtimeState.fallbackLanguage;
+    singletonState.keySeparator = runtimeState.keySeparator;
+    singletonState.lazy = runtimeState.lazy;
+    singletonState.keyManifest = new Map();
+    singletonState.loadedFiles = new Set();
+    singletonState.eagerLoadedLanguages = new Set();
+    singletonState.cache.clear();
+    preload(singletonState, options.preload);
+    singletonInitialized = true;
+  }
+
+  return createRuntime(runtimeState);
+}
+
+function preload(runtimeState, shouldPreload) {
+  if (shouldPreload === true) {
+    if (runtimeState.lazy) {
+      getManifestForLanguage(runtimeState, runtimeState.language);
+      if (!runtimeState.cache.has(runtimeState.language)) {
+        runtimeState.cache.set(runtimeState.language, {});
+      }
+      if (runtimeState.fallbackLanguage && runtimeState.fallbackLanguage !== runtimeState.language) {
+        getManifestForLanguage(runtimeState, runtimeState.fallbackLanguage);
+        if (!runtimeState.cache.has(runtimeState.fallbackLanguage)) {
+          runtimeState.cache.set(runtimeState.fallbackLanguage, {});
+        }
+      }
+    } else {
+      getTranslationsForState(runtimeState, runtimeState.language);
+      if (runtimeState.fallbackLanguage && runtimeState.fallbackLanguage !== runtimeState.language) {
+        getTranslationsForState(runtimeState, runtimeState.fallbackLanguage);
+      }
     }
   }
+}
+
+function createRuntime(runtimeState) {
+  const runtimeTranslate = (key, params) => translateWithState(runtimeState, key, params);
   return {
-    t: translate,
-    translate,
-    setLanguage,
-    getLanguage,
-    getAvailableLanguages,
-    refresh,
+    t: runtimeTranslate,
+    translate: runtimeTranslate,
+    setLanguage: (lang) => setLanguageForState(runtimeState, lang),
+    getLanguage: () => getLanguageForState(runtimeState),
+    getAvailableLanguages: () => getAvailableLanguagesForState(runtimeState),
+    refresh: (lang) => refreshForState(runtimeState, lang),
   };
 }
 
 function translate(key, params = {}) {
-  const langData = getTranslations(state.language);
-  let value = resolveKey(langData, key, state.keySeparator);
+  return translateWithState(singletonState, key, params);
+}
 
-  if (typeof value === 'undefined' && state.fallbackLanguage) {
-    const fbData = getTranslations(state.fallbackLanguage);
-    value = resolveKey(fbData, key, state.keySeparator);
-  }
+function translateWithState(runtimeState, key, params = {}) {
+  const langData = getTranslationsForState(runtimeState, runtimeState.language);
+  let value = resolveKey(langData, key, runtimeState.keySeparator, runtimeState, runtimeState.language);
+
+  if (typeof value === 'undefined' && runtimeState.fallbackLanguage) {
+    const fbData = getTranslationsForState(runtimeState, runtimeState.fallbackLanguage);
+    value = resolveKey(fbData, key, runtimeState.keySeparator, runtimeState, runtimeState.fallbackLanguage);
+  }
 
   if (typeof value === 'string') return interpolate(value, params);
   return typeof value === 'undefined' ? key : value;
 }
 
 function setLanguage(lang) {
+  setLanguageForState(singletonState, lang);
+}
+
+function setLanguageForState(runtimeState, lang) {
   if (!lang || typeof lang !== 'string') return;
-  state.language = lang;
+  runtimeState.language = lang;
 }
 
 function getLanguage() {
-  return state.language;
+  return getLanguageForState(singletonState);
+}
+
+function getLanguageForState(runtimeState) {
+  return runtimeState.language;
 }
 
 function getAvailableLanguages() {
+  return getAvailableLanguagesForState(singletonState);
+}
+
+function getAvailableLanguagesForState(runtimeState) {
   const langs = new Set();
-  if (!state.baseDir) state.baseDir = resolveBaseDir();
-  if (!SecurityUtils.safeExistsSync(state.baseDir)) return ['en'];
+  if (!runtimeState.baseDir) runtimeState.baseDir = resolveBaseDir();
+  if (!SecurityUtils.safeExistsSync(runtimeState.baseDir, path.dirname(runtimeState.baseDir))) return ['en'];
   try {
-    for (const entry of fs.readdirSync(state.baseDir, { withFileTypes: true })) {
+    for (const entry of fs.readdirSync(runtimeState.baseDir, { withFileTypes: true })) {
       if (entry.isFile() && entry.name.toLowerCase().endsWith('.json')) {
         langs.add(entry.name.replace(/\.json$/i, ''));
       } else if (entry.isDirectory()) {
         const lang = entry.name;
-        const idx = path.join(state.baseDir, lang, `${lang}.json`);
-        if (SecurityUtils.safeExistsSync(idx)) langs.add(lang);
+        const idx = path.join(runtimeState.baseDir, lang, `${lang}.json`);
+        if (SecurityUtils.safeExistsSync(idx, path.dirname(idx))) langs.add(lang);
         else langs.add(lang); // be permissive
       }
     }
@@ -248,13 +427,23 @@ function getAvailableLanguages() {
   return Array.from(langs.size ? langs : new Set(['en']));
 }
 
-function refresh(lang = state.language) {
-  if (state.cache.has(lang)) state.cache.delete(lang);
-  if (lang !== state.fallbackLanguage && state.cache.has(state.fallbackLanguage)) {
-    // do nothing; keep or clear on demand
-  }
+function refresh(lang) {
+  refreshForState(singletonState, lang);
 }
 
+function refreshForState(runtimeState, lang = runtimeState.language) {
+  if (runtimeState.cache.has(lang)) runtimeState.cache.delete(lang);
+  if (runtimeState.eagerLoadedLanguages) runtimeState.eagerLoadedLanguages.delete(lang);
+  if (runtimeState.loadedFiles) {
+    for (const fileKey of Array.from(runtimeState.loadedFiles)) {
+      if (fileKey.startsWith(`${lang}\0`)) runtimeState.loadedFiles.delete(fileKey);
+    }
+  }
+  if (lang !== runtimeState.fallbackLanguage && runtimeState.cache.has(runtimeState.fallbackLanguage)) {
+    // do nothing; keep or clear on demand
+  }
+}
+
 module.exports = {
   initRuntime,
   translate,
@@ -262,5 +451,6 @@ module.exports = {
   setLanguage,
   getLanguage,
   getAvailableLanguages,
-  refresh,
-};
+  refresh,
+  loadKeyManifest: (baseDir) => loadKeyManifestFromDir(baseDir || singletonState.baseDir),
+};

package/ui-locales/en.json

@@ -1209,7 +1209,7 @@
   },
   "operations": {
     "completed": "✅ Operation completed successfully!",
-    "deleteReportsTitle": "🗑️ Delete Reports & Logs",
+    "deleteReportsTitle": "🗑️ Delete Reports, Logs & Cache",
     "scanningForFiles": "🔍 Scanning for files to delete...",
     "noFilesFoundToDelete": "✅ No files found to delete.",
     "availableDirectories": "📁 Available directories:",