i18ntk 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -3,9 +3,34 @@
 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).
-
-## [3.1.0] - 2026-05-07
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.1.2] - 2026-05-07
+
+### Fixed
+- Auto Translate now resolves locale roots such as `./locales` to the selected source-language folder such as `./locales/en` when JSON files are stored under language folders.
+- Public package staging now verifies root `package.json` and `package.public.json` release metadata are synchronized before pack or publish.
+- Added a safe `publish:public:dry-run` path for validating the exact staged npm publish flow.
+
+### Changed
+- Updated release docs, npm README metadata, and package manifests for v3.1.2.
+- Kept generated backups, temporary benchmark datasets, local setup state, and debug repair files out of future public repo commits through `.gitignore`.
+
+## [3.1.1] - 2026-05-07
+
+### Added
+- **Auto Translate protection file workflow**: Added user-editable `i18ntk-auto-translate.json` support for protected terms, key paths, exact values, and regex patterns.
+- **Public package README guard**: Public package staging now verifies `README.md` is included and non-empty before publish.
+
+### Changed
+- Updated README and release documentation for the current Auto Translate protection workflow and public package contents.
+- Removed project-specific hardcoded validation examples so users configure their own brand and domain terms.
+
+### Fixed
+- Removed provider-shaped fake secret fixtures from tests to avoid GitHub push protection false positives.
+- Ensured public package metadata includes `readmeFilename: "README.md"` so npm can render the package README.
+
+## [3.1.0] - 2026-05-07
 
 ### Added
 - **Placeholder-preserve translation mode**: Translates text segments around dynamic placeholders and reinserts the original tokens exactly.

package/README.md

@@ -1,6 +1,6 @@
-# i18ntk v3.1.0
+# i18ntk v3.1.2
 
-Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic locale translation, and runtime translation loading.
+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,40 +9,7 @@ Zero-dependency internationalization toolkit for setup, scanning, analysis, vali
 [![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/3.1.0)](https://socket.dev/npm/package/i18ntk/overview/3.1.0)
-
-## Upgrade Notice
-
-Versions earlier than `3.1.0` may contain known stability and security issues.
-They are considered unsupported for production use. Upgrade to `3.1.0` or newer.
-
-## v3.1.0 - Auto Translate Hardening and Validation Warning Tuning
-
-v3.1.0 improves automatic JSON locale translation through the management menu and the standalone `i18ntk-translate` command. It also reduces noisy validation warnings and added a dedicated settings module for the auto translator.
-
-For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migration notes, see [docs/migration-guide-v3.1.0.md](./docs/migration-guide-v3.1.0.md).
-
-## What i18ntk Does
-
-- Zero runtime dependencies
-- Interactive and non-interactive project setup
-- Translation completeness analysis and usage tracking
-- Validation, sizing, and summary reporting
-- Missing-key completion and fixer workflows
-- Automatic translation of JSON locale files
-- Runtime translation helpers for application code
-- Support for JS/TS, React, Vue, Angular, and generic projects
-
-## Getting Started
-
-1. Install the package.
-2. Run `i18ntk` or `i18ntk --command=init` to initialize the project.
-3. Confirm the source language and locale directories.
-4. Run `i18ntk --command=analyze` or `i18ntk --command=validate` to inspect translation coverage.
-5. Use `i18ntk --command=complete` to fill missing keys when needed.
-6. Use `i18ntk --command=translate` or menu option 14 to auto-translate source JSON files.
-
-The full onboarding flow is documented in [docs/getting-started.md](docs/getting-started.md).
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/3.1.2)](https://socket.dev/npm/package/i18ntk/overview/3.1.2)
 
 ## Install
 
@@ -57,11 +24,31 @@ npm install --save-dev i18ntk
 npx i18ntk --help
 ```
 
-## Setup
+Requirements:
+
+- Node.js `>=16.0.0`
+- npm `>=8.0.0`
+- No runtime dependencies
 
-The toolkit stores project configuration in `.i18ntk-config` at the project root.
+## What's New in 3.1.2
 
-Recommended setup flow:
+- Auto Translate can translate strings that contain placeholders by translating text around the placeholders and reinserting the original tokens.
+- Auto Translate supports user-editable protection rules in `i18ntk-auto-translate.json` for brand names, product terms, exact values, key paths, and regex patterns.
+- The manager Auto Translate flow runs in-process, avoiding production `child_process` usage for that command.
+- The target-language prompt supports `all` to translate into every configured target language while excluding the source language.
+- Source-directory prompts are clearer and accept absolute paths or project-relative paths.
+- Validation warnings now distinguish URLs, email addresses, secret-like values, and likely untranslated English content.
+- Sizing reports now include per-language file counts, file-set mismatches, and per-file key/character statistics.
+- Internal UI locale coverage is enforced against the English UI locale.
+- Public package staging verifies `README.md` is present before publish.
+- Auto Translate now resolves locale roots such as `./locales` to the selected source-language folder such as `./locales/en` when needed.
+- Public package staging now fails when root `package.json` and `package.public.json` release metadata drift.
+
+See [CHANGELOG.md](./CHANGELOG.md) and [docs/migration-guide-v3.1.2.md](./docs/migration-guide-v3.1.2.md) for release details.
+
+## Quick Start
+
+Initialize a project:
 
 ```bash
 i18ntk
@@ -69,24 +56,41 @@ i18ntk
 i18ntk --command=init
 ```
 
-During setup, you can define:
+Run common checks:
+
+```bash
+i18ntk --command=analyze
+i18ntk --command=validate
+i18ntk --command=usage
+i18ntk --command=sizing
+i18ntk --command=summary
+```
+
+Complete or fix translation files:
 
-- source directory
-- source language
-- UI language
-- framework preference
-- output directory
-- backup behavior
+```bash
+i18ntk --command=complete
+i18ntk-fixer --help
+```
 
-If you run in CI or a non-interactive shell, use:
+Auto-translate locale JSON:
 
 ```bash
-i18ntk --command=init --no-prompt
+i18ntk --command=translate
+# or
+i18ntk-translate locales/en/common.json de --report-stdout
 ```
 
-## Daily Use
+The full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).
+
+## Main Commands
+
+Primary CLI:
 
 ```bash
+i18ntk
+i18ntk --help
+i18ntk --command=init
 i18ntk --command=analyze
 i18ntk --command=validate
 i18ntk --command=usage
@@ -95,9 +99,10 @@ i18ntk --command=sizing
 i18ntk --command=complete
 i18ntk --command=translate
 i18ntk --command=summary
+i18ntk --command=debug
 ```
 
-Standalone commands are also available:
+Standalone executables:
 
 ```bash
 i18ntk-init
@@ -114,10 +119,11 @@ i18ntk-backup
 i18ntk-translate
 ```
 
-Note: `i18ntk --command=backup` in the manager flow is disabled in current builds.
-Use the standalone `i18ntk-backup` executable when backup operations are required.
+Note: manager route `i18ntk --command=backup` is disabled in current builds. Use `i18ntk-backup` directly for backup operations.
+
+## Common Options
 
-## Common Flags
+Most commands support:
 
 - `--source-dir <path>`
 - `--i18n-dir <path>`
@@ -128,18 +134,6 @@ Use the standalone `i18ntk-backup` executable when backup operations are require
 - `--dry-run`
 - `--help`
 
-Auto Translate also supports:
-
-- `--source-lang <code>`
-- `--files <pattern>`
-- `--preserve-placeholders`
-- `--skip-placeholders`
-- `--send-placeholders`
-- `--batch-size <n>`
-- `--progress-interval <n>`
-- `--report-file <path>`
-- `--report-stdout`
-
 Example:
 
 ```bash
@@ -148,7 +142,7 @@ i18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./
 
 ## Auto Translate
 
-Interactive menu flow:
+Interactive manager flow:
 
 ```bash
 i18ntk
@@ -160,16 +154,119 @@ Direct CLI examples:
 ```bash
 i18ntk-translate locales/en/common.json de
 i18ntk-translate locales/en/common.json fr --dry-run --report-stdout
-i18ntk-translate locales/en es --files "*.json" --no-confirm --preserve-placeholders
+i18ntk-translate locales/en es --source-dir locales/en --files "*.json" --no-confirm --preserve-placeholders
+```
+
+The manager flow asks for:
+
+- source locale directory, either the folder with JSON files or a locale root such as `./locales`
+- source language code
+- one or more target languages, or `all`
+- one JSON file or all JSON files in the source directory
+
+If 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.
+
+Before writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:
+
+```text
+locales/en/common.json
+locales/de/common.json
+locales/fr/common.json
+```
+
+### Placeholder Handling
+
+Auto Translate detects common placeholders such as:
+
+- `{name}`
+- `{{count}}`
+- `%s`
+- `%d`
+- `:id`
+- `%{name}`
+- `${value}`
+
+Useful flags:
+
+- `--preserve-placeholders`: translate text around placeholders and reinsert original tokens
+- `--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
+
+### Protected Terms and Keys
+
+Auto Translate can create and use a project-local protection file:
+
+```bash
+i18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json
+```
+
+Example `i18ntk-auto-translate.json`:
+
+```json
+{
+  "version": 1,
+  "terms": ["BrandName", "PRODUCT_CODE", "API"],
+  "keys": ["app.brandName", "legal.companyName", "product.*.symbol"],
+  "values": ["BrandName Ltd", "support@example.com"],
+  "patterns": ["[A-Z]{2,}-\\d+"]
+}
+```
+
+- `terms` are masked before translation and restored exactly afterward.
+- `keys` are exact key paths or `*` wildcard paths copied unchanged.
+- `values` are exact source values copied unchanged.
+- `patterns` are JavaScript regex strings for advanced protected substrings.
+
+Useful flags:
+
+- `--protection-file <path>`
+- `--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.
+
+See [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.
+
+## Validation
+
+Validation checks locale structure, completeness, placeholders, and content risks.
+
+In 3.1.2, warning types are more specific:
+
+- `Potential risky content`: URL, email address, or secret-like value
+- `Possible untranslated English content`: target-language value appears to contain too much English
+
+English-content warnings include:
+
+- detected English percentage
+- configured threshold
+- matched word count
+- sample matched words
+
+Tune warnings in `.i18ntk-config`:
+
+```json
+{
+  "englishContentThresholdPercent": 10,
+  "allowedEnglishTerms": ["BrandName", "PRODUCT_CODE"]
+}
 ```
 
-The manager flow accepts comma- or space-separated target language codes, or `all` for every configured target language. It previews the first target language with a dry run when enabled, asks for confirmation, then writes translated files under matching target-language directories such as `locales/de/common.json`. By default it preserves placeholders while translating the surrounding text.
+## Sizing Analysis
+
+`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.
+
+```bash
+i18ntk-sizing --source-dir ./locales --format table
+i18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports
+```
 
-See [docs/auto-translate.md](docs/auto-translate.md) for full usage details.
+Use `--detailed` to print per-file rows in the terminal.
 
 ## Runtime API
 
-Use `i18ntk/runtime` when your application needs to read locale JSON files at runtime.
+Use `i18ntk/runtime` when an application needs to read locale JSON files at runtime.
 
 ```js
 const runtime = require('i18ntk/runtime');
@@ -189,15 +286,17 @@ console.log(runtime.getAvailableLanguages());
 runtime.refresh('fr');
 ```
 
-For a deeper walkthrough, see [docs/runtime.md](docs/runtime.md).
+See [docs/runtime.md](./docs/runtime.md) for runtime details.
 
 ## Configuration
 
-Example `.i18ntk-config`:
+i18ntk uses a project-local `.i18ntk-config` file.
+
+Example:
 
 ```json
 {
-  "version": "3.1.0",
+  "version": "3.1.2",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -206,8 +305,20 @@ Example `.i18ntk-config`:
   "englishContentThresholdPercent": 10,
   "allowedEnglishTerms": ["BrandName", "PRODUCT_CODE"],
   "autoTranslate": {
+    "placeholderMode": "preserve",
+    "concurrency": 6,
+    "batchSize": 100,
+    "progressInterval": 25,
+    "retryCount": 3,
+    "retryDelay": 1000,
+    "timeout": 15000,
+    "dryRunFirst": true,
+    "reportStdout": true,
+    "bom": false,
     "protectionEnabled": true,
-    "protectionFile": "./i18ntk-auto-translate.json"
+    "protectionFile": "./i18ntk-auto-translate.json",
+    "promptProtectionSetup": true,
+    "promptProtectionUpdate": true
   },
   "setup": {
     "completed": true
@@ -215,34 +326,53 @@ Example `.i18ntk-config`:
 }
 ```
 
-See [docs/api/CONFIGURATION.md](docs/api/CONFIGURATION.md) for the full configuration model.
+See [docs/api/CONFIGURATION.md](./docs/api/CONFIGURATION.md) for the full configuration model.
 
-## Docs
+## Public Package Contents
 
-- [Documentation Index](https://github.com/vladnoskv/i18ntk/blob/main/docs/README.md)
-- [Getting Started](https://github.com/vladnoskv/i18ntk/blob/main/docs/getting-started.md)
-- [API Reference](https://github.com/vladnoskv/i18ntk/blob/main/docs/api/API_REFERENCE.md)
-- [Configuration Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/api/CONFIGURATION.md)
-- [Runtime API Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/runtime.md)
-- [Auto Translate Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/auto-translate.md)
-- [Scanner Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/scanner-guide.md)
-- [Environment Variables](https://github.com/vladnoskv/i18ntk/blob/main/docs/environment-variables.md)
-- [Migration Guide v3.1.0](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v3.1.0.md)
-- [Migration Guide v3.0.0](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v3.0.0.md)
-- [Migration Guide v2.6.0](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v2.6.0.md)
-- [Migration Guide v2.5.1](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v2.5.1.md)
+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.
 
-## Community
+The package includes:
+
+- CLI entry points under `main/`
+- manager commands and services
+- runtime API files under `runtime/`
+- settings UI files required at runtime
+- bundled internal UI locales
+- shared utilities required by the shipped commands
+- `README.md`, `CHANGELOG.md`, `LICENSE`, and policy files
 
-- [Contributing](CONTRIBUTING.md)
-- [Code of Conduct](CODE_OF_CONDUCT.md)
-- [Security Policy](SECURITY.md)
-- [Funding](FUNDING.md)
+The public package manifest includes `readmeFilename: "README.md"`, and the release staging script fails if `README.md` is missing or empty.
 
-## Code of Conduct
+## Documentation
+
+- [Documentation Index](./docs/README.md)
+- [Getting Started](./docs/getting-started.md)
+- [API Reference](./docs/api/API_REFERENCE.md)
+- [Configuration Guide](./docs/api/CONFIGURATION.md)
+- [Runtime API Guide](./docs/runtime.md)
+- [Auto Translate Guide](./docs/auto-translate.md)
+- [Scanner Guide](./docs/scanner-guide.md)
+- [Environment Variables](./docs/environment-variables.md)
+- [Migration Guide v3.1.2](./docs/migration-guide-v3.1.2.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 v2.6.0](./docs/migration-guide-v2.6.0.md)
+- [Migration Guide v2.5.1](./docs/migration-guide-v2.5.1.md)
+
+## Security
+
+- No API key is required for the default Auto Translate flow.
+- Do not store secrets in locale files, `.i18ntk-config`, or protection files.
+- Project-specific brand/product terms should be configured by the user, not hardcoded into the package.
+- Report security issues using [SECURITY.md](./SECURITY.md).
+
+## Community
 
-We are committed to providing a friendly, safe and welcoming environment for all. Please read and respect our [Code of Conduct](CODE_OF_CONDUCT.md).
+- [Contributing](./CONTRIBUTING.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Funding](./FUNDING.md)
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT. See [LICENSE](./LICENSE).

package/main/manage/commands/TranslateCommand.js

@@ -71,7 +71,14 @@ class TranslateCommand {
                 console.error(`Source locale directory not found: ${this.sourceDir}`);
                 return { success: false, error: 'Source directory not found' };
             }
-            const jsonFiles = SecurityUtils.safeReaddirSync(this.sourceDir, path.dirname(this.sourceDir)).filter(f => f.endsWith('.json')).sort();
+            const resolvedSource = this.resolveSourceDirectoryForLanguage(this.sourceDir, this.sourceLang);
+            if (!resolvedSource.ok) {
+                console.error(resolvedSource.message);
+                return { success: false, error: 'No source files found' };
+            }
+            this.sourceDir = resolvedSource.sourceDir;
+            this.configuredTargetLangs = this.getConfiguredTargetLanguages(unified, this.sourceDir);
+            const jsonFiles = resolvedSource.jsonFiles;
             return await this.nonInteractiveFlow(jsonFiles);
         }
 
@@ -84,18 +91,16 @@ class TranslateCommand {
         // Step 2: Choose source language
         this.sourceLang = await this.promptSourceLang(ask);
         if (!this.sourceLang) return { success: false, error: 'No source language selected' };
-        this.configuredTargetLangs = this.getConfiguredTargetLanguages(unified, this.sourceDir);
-
-        const jsonFiles = SecurityUtils.safeReaddirSync(this.sourceDir, path.dirname(this.sourceDir))
-            .filter(f => f.endsWith('.json'))
-            .sort();
 
-        if (jsonFiles.length === 0) {
-            console.error(`No JSON files found in: ${this.sourceDir}`);
+        const resolvedSource = this.resolveSourceDirectoryForLanguage(this.sourceDir, this.sourceLang);
+        if (!resolvedSource.ok) {
+            console.error(resolvedSource.message);
             return { success: false, error: 'No source files found' };
         }
+        this.sourceDir = resolvedSource.sourceDir;
+        this.configuredTargetLangs = this.getConfiguredTargetLanguages(unified, this.sourceDir);
 
-        return await this.interactiveFlow(jsonFiles, ask);
+        return await this.interactiveFlow(resolvedSource.jsonFiles, ask);
     }
 
     async promptSourceDir(ask, defaultDir) {
@@ -106,8 +111,9 @@ class TranslateCommand {
             console.log('  Accepted: an absolute path, or a path relative to the current project.');
             console.log('  Examples:');
             console.log('    ./locales/en');
+            console.log('    ./locales  (then choose source language: en)');
             console.log(`    ${defaultDir}`);
-            console.log('  The folder must contain the source JSON files to translate.');
+            console.log('  The folder can contain JSON files directly, or language folders such as ./locales/en.');
             console.log('  Press Enter to use the default.');
             const input = await ask('  > ');
 
@@ -251,6 +257,42 @@ class TranslateCommand {
         return { success: false, error: 'Non-interactive mode not supported from menu' };
     }
 
+    getJsonFiles(sourceDir) {
+        return SecurityUtils.safeReaddirSync(sourceDir, path.dirname(sourceDir))
+            .filter(f => f.endsWith('.json'))
+            .sort();
+    }
+
+    resolveSourceDirectoryForLanguage(selectedDir, sourceLang, options = {}) {
+        const shouldLog = options.log !== false;
+        const jsonFiles = this.getJsonFiles(selectedDir);
+        if (jsonFiles.length > 0) {
+            return { ok: true, sourceDir: selectedDir, jsonFiles };
+        }
+
+        const cleanLang = String(sourceLang || '').trim().toLowerCase();
+        if (cleanLang) {
+            const languageDir = path.join(selectedDir, cleanLang);
+            const languageStats = SecurityUtils.safeStatSync(languageDir, path.dirname(languageDir));
+            if (languageStats && languageStats.isDirectory()) {
+                const languageJsonFiles = this.getJsonFiles(languageDir);
+                if (languageJsonFiles.length > 0) {
+                    if (shouldLog) {
+                        console.log(`  No JSON files found directly in: ${selectedDir}`);
+                        console.log(`  Using source language folder: ${languageDir}`);
+                    }
+                    return { ok: true, sourceDir: languageDir, jsonFiles: languageJsonFiles };
+                }
+            }
+        }
+
+        const checkedLanguageDir = cleanLang ? path.join(selectedDir, cleanLang) : null;
+        const message = checkedLanguageDir
+            ? `No JSON files found in: ${selectedDir}\nAlso checked source language folder: ${checkedLanguageDir}`
+            : `No JSON files found in: ${selectedDir}`;
+        return { ok: false, sourceDir: selectedDir, jsonFiles: [], message };
+    }
+
     getConfiguredTargetLanguages(config = {}, sourceDir = this.sourceDir) {
         const candidates = []
             .concat(config.defaultLanguages || [])

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "i18ntk",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, auto translation, fixing, reporting, and runtime translation loading.",
+  "readmeFilename": "README.md",
   "keywords": [
     "i18n",
     "internationalization",
@@ -157,5 +158,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "preferGlobal": true
+  "preferGlobal": true,
+  "readme": "# i18ntk v3.1.2\n\nZero-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.1.2)](https://socket.dev/npm/package/i18ntk/overview/3.1.2)\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.1.2\n\n- Auto Translate can translate strings that contain placeholders by translating text around the placeholders and reinserting the original tokens.\n- Auto Translate supports user-editable protection rules in `i18ntk-auto-translate.json` for brand names, product terms, exact values, key paths, and regex patterns.\n- The manager Auto Translate flow runs in-process, avoiding production `child_process` usage for that command.\n- The target-language prompt supports `all` to translate into every configured target language while excluding the source language.\n- Source-directory prompts are clearer and accept absolute paths or project-relative paths.\n- Validation warnings now distinguish URLs, email addresses, secret-like values, and likely untranslated English content.\n- Sizing reports now include per-language file counts, file-set mismatches, and per-file key/character statistics.\n- Internal UI locale coverage is enforced against the English UI locale.\n- Public package staging verifies `README.md` is present before publish.\n- Auto Translate now resolves locale roots such as `./locales` to the selected source-language folder such as `./locales/en` when needed.\n- Public package staging now fails when root `package.json` and `package.public.json` release metadata drift.\n\nSee [CHANGELOG.md](./CHANGELOG.md) and [docs/migration-guide-v3.1.2.md](./docs/migration-guide-v3.1.2.md) for release details.\n\n## Quick Start\n\nInitialize a project:\n\n```bash\ni18ntk\n# or\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\nNote: manager route `i18ntk --command=backup` is disabled in current builds. Use `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\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.1.2\",\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.1.2](./docs/migration-guide-v3.1.2.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- [Migration Guide v2.6.0](./docs/migration-guide-v2.6.0.md)\n- [Migration Guide v2.5.1](./docs/migration-guide-v2.5.1.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/ui-locales/de.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "version": "3.1.0",
+    "version": "3.1.2",
     "updated": "2026-05-07"
   },
   "common": {
@@ -1105,18 +1105,18 @@
     "warningProceedingWithoutFramework": "Fortfahren ohne erkanntes i18n-Framework."
   },
   "language": {
-      "title": "🌍 Sprache ändern",
-      "separator": "============================================================",
-      "current": "Aktuelle Sprache: {language}",
-      "available": "Verfügbare Sprachen:",
-      "languageOption": "{index}. {displayName}{current}",
-      "backToMainMenu": "Zurück zum Hauptmenü",
-      "prompt": "Wähle eine Sprache (0–8):",
-      "cancelled": "Sprachwechsel abgebrochen.",
-      "invalid": "Ungültige Auswahl. Bitte erneut versuchen.",
-      "changed": "Sprache geändert zu: {language}",
-      "changeFailed": "Sprachwechsel fehlgeschlagen: {error}",
-      "pressEnterToContinue": "Drücke Enter, um fortzufahren..."
+    "title": "🌍 Sprache ändern",
+    "separator": "============================================================",
+    "current": "Aktuelle Sprache: {language}",
+    "available": "Verfügbare Sprachen:",
+    "languageOption": "{index}. {displayName}{current}",
+    "backToMainMenu": "Zurück zum Hauptmenü",
+    "prompt": "Wähle eine Sprache (0–8):",
+    "cancelled": "Sprachwechsel abgebrochen.",
+    "invalid": "Ungültige Auswahl. Bitte erneut versuchen.",
+    "changed": "Sprache geändert zu: {language}",
+    "changeFailed": "Sprachwechsel fehlgeschlagen: {error}",
+    "pressEnterToContinue": "Drücke Enter, um fortzufahren..."
   },
   "maintainLanguagePurity": {
     "workflow_title": "🚀 Workflow zur Wahrung der Sprachreinheit",

package/ui-locales/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "version": "3.1.0",
+    "version": "3.1.2",
     "updated": "2026-05-07"
   },
   "common": {
@@ -1105,18 +1105,18 @@
     "warningProceedingWithoutFramework": "Proceeding without detected i18n framework."
   },
   "language": {
-      "title": "🌍 Change Language",
-      "separator": "============================================================",
-      "current": "Current language: {language}",
-      "available": "Available Languages:",
-      "languageOption": "{index}. {displayName}{current}",
-      "backToMainMenu": "Back to Main Menu",
-      "prompt": "Select a language (0-8):",
-      "cancelled": "Language change cancelled.",
-      "invalid": "Invalid choice. Please try again.",
-      "changed": "Language changed to: {language}",
-      "changeFailed": "Failed to change language: {error}",
-      "pressEnterToContinue": "Press Enter to continue..."
+    "title": "🌍 Change Language",
+    "separator": "============================================================",
+    "current": "Current language: {language}",
+    "available": "Available Languages:",
+    "languageOption": "{index}. {displayName}{current}",
+    "backToMainMenu": "Back to Main Menu",
+    "prompt": "Select a language (0-8):",
+    "cancelled": "Language change cancelled.",
+    "invalid": "Invalid choice. Please try again.",
+    "changed": "Language changed to: {language}",
+    "changeFailed": "Failed to change language: {error}",
+    "pressEnterToContinue": "Press Enter to continue..."
   },
   "maintainLanguagePurity": {
     "workflow_title": "🚀 Language Purity Maintenance Workflow",

package/ui-locales/es.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "version": "3.1.0",
+    "version": "3.1.2",
     "updated": "2026-05-07"
   },
   "common": {
@@ -1105,18 +1105,18 @@
     "warningProceedingWithoutFramework": "Procediendo sin marco i18n detectado."
   },
   "language": {
-      "title": "🌍 Cambiar Idioma",
-      "separator": "============================================================",
-      "current": "Idioma actual: {language}",
-      "available": "Idiomas Disponibles:",
-      "languageOption": "{index}. {displayName}{current}",
-      "backToMainMenu": "Volver al Menú Principal",
-      "prompt": "Selecciona un idioma (0-8):",
-      "cancelled": "Cambio de idioma cancelado.",
-      "invalid": "Opción inválida. Por favor intenta de nuevo.",
-      "changed": "Idioma cambiado a: {language}",
-      "changeFailed": "Error al cambiar el idioma: {error}",
-      "pressEnterToContinue": "Presiona Enter para continuar..."
+    "title": "🌍 Cambiar Idioma",
+    "separator": "============================================================",
+    "current": "Idioma actual: {language}",
+    "available": "Idiomas Disponibles:",
+    "languageOption": "{index}. {displayName}{current}",
+    "backToMainMenu": "Volver al Menú Principal",
+    "prompt": "Selecciona un idioma (0-8):",
+    "cancelled": "Cambio de idioma cancelado.",
+    "invalid": "Opción inválida. Por favor intenta de nuevo.",
+    "changed": "Idioma cambiado a: {language}",
+    "changeFailed": "Error al cambiar el idioma: {error}",
+    "pressEnterToContinue": "Presiona Enter para continuar..."
   },
   "maintainLanguagePurity": {
     "workflow_title": "🚀 Flujo de Trabajo de Mantenimiento de Pureza de Idioma",

package/ui-locales/fr.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "version": "3.1.0",
+    "version": "3.1.2",
     "updated": "2026-05-07"
   },
   "common": {
@@ -1105,18 +1105,18 @@
     "warningProceedingWithoutFramework": "Poursuite sans framework i18n détecté."
   },
   "language": {
-      "title": "🌍 Changer la langue",
-      "separator": "============================================================",
-      "current": "Langue actuelle : {language}",
-      "available": "Langues disponibles :",
-      "languageOption": "{index}. {displayName}{current}",
-      "backToMainMenu": "Retour au menu principal",
-      "prompt": "Sélectionnez une langue (0-8) :",
-      "cancelled": "Changement de langue annulé.",
-      "invalid": "Choix invalide. Veuillez réessayer.",
-      "changed": "Langue changée en : {language}",
-      "changeFailed": "Échec du changement de langue : {error}",
-      "pressEnterToContinue": "Appuyez sur Entrée pour continuer…"
+    "title": "🌍 Changer la langue",
+    "separator": "============================================================",
+    "current": "Langue actuelle : {language}",
+    "available": "Langues disponibles :",
+    "languageOption": "{index}. {displayName}{current}",
+    "backToMainMenu": "Retour au menu principal",
+    "prompt": "Sélectionnez une langue (0-8) :",
+    "cancelled": "Changement de langue annulé.",
+    "invalid": "Choix invalide. Veuillez réessayer.",
+    "changed": "Langue changée en : {language}",
+    "changeFailed": "Échec du changement de langue : {error}",
+    "pressEnterToContinue": "Appuyez sur Entrée pour continuer…"
   },
   "maintainLanguagePurity": {
     "workflow_title": "🚀 Flux de maintenance de la pureté linguistique",

package/ui-locales/ja.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "version": "3.1.0",
+    "version": "3.1.2",
     "updated": "2026-05-07"
   },
   "common": {
@@ -1105,18 +1105,18 @@
     "warningProceedingWithoutFramework": "i18n フレームワークが検出されないまま続行します。"
   },
   "language": {
-      "title": "🌍 言語を変更",
-      "separator": "============================================================",
-      "current": "現在の言語: {language}",
-      "available": "利用可能な言語:",
-      "languageOption": "{index}。 {displayName}{current}",
-      "backToMainMenu": "メインメニューに戻る",
-      "prompt": "言語を選択してください (0-8):",
-      "cancelled": "言語変更がキャンセルされました。",
-      "invalid": "無効な選択です。もう一度お試しください。",
-      "changed": "言語が {language} に変更されました",
-      "changeFailed": "言語の変更に失敗しました: {error}",
-      "pressEnterToContinue": "続行するにはEnterキーを押してください…"
+    "title": "🌍 言語を変更",
+    "separator": "============================================================",
+    "current": "現在の言語: {language}",
+    "available": "利用可能な言語:",
+    "languageOption": "{index}。 {displayName}{current}",
+    "backToMainMenu": "メインメニューに戻る",
+    "prompt": "言語を選択してください (0-8):",
+    "cancelled": "言語変更がキャンセルされました。",
+    "invalid": "無効な選択です。もう一度お試しください。",
+    "changed": "言語が {language} に変更されました",
+    "changeFailed": "言語の変更に失敗しました: {error}",
+    "pressEnterToContinue": "続行するにはEnterキーを押してください…"
   },
   "maintainLanguagePurity": {
     "workflow_title": "🚀 言語純度維持ワークフロー",

package/ui-locales/ru.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "version": "3.1.0",
+    "version": "3.1.2",
     "updated": "2026-05-07"
   },
   "common": {
@@ -1105,18 +1105,18 @@
     "warningProceedingWithoutFramework": "Продолжаем без обнаружения платформы i18n."
   },
   "language": {
-      "title": "🌍 Сменить язык",
-      "separator": "============================================================",
-      "current": "Текущий язык: {language}",
-      "available": "Доступные языки:",
-      "languageOption": "{index}. {displayName}{current}",
-      "backToMainMenu": "Вернуться в главное меню",
-      "prompt": "Выберите язык (0-8):",
-      "cancelled": "Смена языка отменена.",
-      "invalid": "Неверный выбор. Пожалуйста, попробуйте снова.",
-      "changed": "Язык изменён на: {language}",
-      "changeFailed": "Не удалось сменить язык: {error}",
-      "pressEnterToContinue": "Нажмите Enter для продолжения..."
+    "title": "🌍 Сменить язык",
+    "separator": "============================================================",
+    "current": "Текущий язык: {language}",
+    "available": "Доступные языки:",
+    "languageOption": "{index}. {displayName}{current}",
+    "backToMainMenu": "Вернуться в главное меню",
+    "prompt": "Выберите язык (0-8):",
+    "cancelled": "Смена языка отменена.",
+    "invalid": "Неверный выбор. Пожалуйста, попробуйте снова.",
+    "changed": "Язык изменён на: {language}",
+    "changeFailed": "Не удалось сменить язык: {error}",
+    "pressEnterToContinue": "Нажмите Enter для продолжения..."
   },
   "maintainLanguagePurity": {
     "workflow_title": "🚀 Рабочий процесс поддержания чистоты языков",
@@ -2112,8 +2112,8 @@
       "sizingCommand": "Оценка команды",
       "completeCommand": "Завершение команды",
       "summaryCommand": "Сводка команды",
-    "scannerCommand": "scanner   - 🔍 Сканирование проблем i18n",
-    "translateCommand": "translate - Автоперевод (Бета)",
+      "scannerCommand": "scanner   - 🔍 Сканирование проблем i18n",
+      "translateCommand": "translate - Автоперевод (Бета)",
       "debugCommand": "Отладка команды"
     },
     "test_complete_system": {

package/ui-locales/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "version": "3.1.0",
+    "version": "3.1.2",
     "updated": "2026-05-07"
   },
   "common": {
@@ -1105,18 +1105,18 @@
     "warningProceedingWithoutFramework": "未检测到 i18n 框架即可继续。"
   },
   "language": {
-      "title": "🌍 切换语言",
-      "separator": "============================================================",
-      "current": "当前语言：{language}",
-      "available": "可用语言：",
-      "languageOption": "{index}。 {displayName}{current}",
-      "backToMainMenu": "返回主菜单",
-      "prompt": "请选择语言（0-8）：",
-      "cancelled": "已取消语言切换。",
-      "invalid": "无效选择，请重试。",
-      "changed": "语言已切换为：{language}",
-      "changeFailed": "切换语言失败：{error}",
-      "pressEnterToContinue": "按 Enter 继续..."
+    "title": "🌍 切换语言",
+    "separator": "============================================================",
+    "current": "当前语言：{language}",
+    "available": "可用语言：",
+    "languageOption": "{index}。 {displayName}{current}",
+    "backToMainMenu": "返回主菜单",
+    "prompt": "请选择语言（0-8）：",
+    "cancelled": "已取消语言切换。",
+    "invalid": "无效选择，请重试。",
+    "changed": "语言已切换为：{language}",
+    "changeFailed": "切换语言失败：{error}",
+    "pressEnterToContinue": "按 Enter 继续..."
   },
   "maintainLanguagePurity": {
     "workflow_title": "🚀 语言纯洁度维护工作流",

package/utils/config-manager.js

@@ -380,9 +380,13 @@ async function acquireConfigLock(timeoutMs = CONFIG_LOCK_TIMEOUT_MS) {
   };
 }
 
-function isAutosaveDisabled() {
-  return envManager.getBoolean('I18NTK_DISABLE_AUTOSAVE');
-}
+function isAutosaveDisabled() {
+  const raw = process.env.I18NTK_DISABLE_AUTOSAVE;
+  if (raw !== undefined && raw !== null && raw !== '') {
+    return ['true', '1', 'yes'].includes(String(raw).trim().toLowerCase());
+  }
+  return envManager.getBoolean('I18NTK_DISABLE_AUTOSAVE');
+}
 
 function clone(obj) {
    return JSON.parse(JSON.stringify(obj));