i18ntk 2.6.0 → 3.1.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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
+
+### Added
+- **Placeholder-preserve translation mode**: Translates text segments around dynamic placeholders and reinserts the original tokens exactly.
+- **Auto Translate beta settings**: Added settings for placeholder mode, concurrency, batch size, progress interval, retry count, retry delay, timeout, dry-run preview, report output, and BOM output.
+- **Large-file tuning flags**: Added `--batch-size` and `--progress-interval` to `i18ntk-translate`.
+- **Short-lived placeholder manifest**: Mirrors placeholder maps to an OS temp file during processing and removes it after each file completes.
+- **Validation content-risk helper**: Added structured detection for URLs, email addresses, secret-like values, and likely untranslated English content.
+- **Sizing file-set analysis**: Added per-language file counts, per-file sizing statistics, and missing/extra file comparison across locale folders.
+
+### Changed
+- Automated and manager Auto Translate flows now default to placeholder `preserve` mode instead of skipping placeholder-bearing strings.
+- `i18ntk-translate` can now be imported and run in-process by other package modules.
+- Source JSON reads tolerate UTF-8 BOM-prefixed files.
+- Validation warnings now report specific issue types and reasons instead of the vague `Risky content` message.
+- English-content validation now reports an English percentage and only warns above a 10% threshold with at least three detected English words.
+- Sizing reports now include folder-level file counts and per-file key/character breakdowns for each language.
+
+### Fixed
+- Fixed false-positive validation warnings for normal product copy terms.
+- Fixed validator handling so ordinary explanatory uses of words like `token` or `secret` are not treated as leaked credentials.
+- Fixed distorted `i18ntk-sizing` table output by rendering aligned columns from measured values instead of fixed localized spacing.
+- Fixed sizing language comparison output so it uses analyzed languages and the configured source language baseline.
+
+### Security
+- Removed production `child_process` usage from `main/manage/commands/TranslateCommand.js` by replacing the spawned CLI process with an in-process translator call.
+
+## [3.0.0] - 2026-05-05
+
+### Added
+- **`i18ntk-translate`**: Zero-dependency CLI tool that converts English source JSON locale files into any target language via Google's free Translate API.
+- **Placeholder protection**: Intelligent detection, masking, and unmasking of dynamic placeholder tokens (`{name}`, `{{count}}`, `%d`, `%s`, `:param`, `{{variable}}`, `%{name}`, `${var}`, etc.) to prevent corruption during translation.
+- **Custom regex support**: `--custom-regex` flag to define additional placeholder patterns for detection and protection.
+- **Interactive control flow**: Two-level user controls — global choice (skip all / send all / ask per key) and per-key interactive mode where each affected key can be individually flagged.
+- **Fully automated CLI mode**: `--no-confirm --skip-placeholders` or `--no-confirm --send-placeholders` flags for unattended CI/CD use.
+- **Post-translation report**: Comprehensive report (stdout, file, or both) listing every skipped key with its original value and a reminder for manual translation.
+- **Multi-file batch processing**: `--source-dir` and `--files` flags support translating all JSON files in a directory at once.
+- **Dry-run mode**: `--dry-run` flag previews which keys would be skipped without making API calls.
+- **UTF-8 BOM output**: `--bom` flag for output files with UTF-8 byte order mark.
+- **Custom translation function**: `--translate-fn` flag to inject an alternative translation API while maintaining the placeholder safety workflow.
+- **Rate-limit handling**: Exponential backoff/retry logic for Google Translate API rate limits and network errors.
+- **Deep JSON traversal**: Full support for nested objects and arrays, preserving data types, null values, and non-string leaf values.
+
+### Changed
+- Version bumped to 3.0.0 (major release with new translation tool feature).
+
 ## [2.6.0] - 2026-05-03
 
 ### Security
@@ -44,22 +90,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Scripts
 - Fixed `scripts/build-public-package.js` and `scripts/reset-release-state.js` `npm_execpath` fallback for missing env var.
-- Fixed `scripts/lint-locales.js` BOM handling and try-catch for `fs.readdirSync`.
-
-## [2.5.1] - 2026-04-29
-
-### Security
-- Fixed `AdminAuth.verifyPin()` to fail closed when admin config is missing, disabled, or malformed instead of returning success.
-- Fixed auth-required checks to fail closed when settings require admin PIN protection but the admin config is unusable.
-- Normalized admin session expiry handling by storing both `expires` and `expiresAt` and cleaning up both formats consistently.
-
-### Added
-- Added regression tests for admin PIN fail-closed behavior and session expiry cleanup.
-
-### Changed
-- Documented the public npm package staging flow introduced after `2.5.0`.
-
-## [2.5.0] - 2026-04-29
+- Fixed `scripts/lint-locales.js` BOM handling and try-catch for `fs.readdirSync`.
+
+## [2.5.1] - 2026-04-29
+
+### Security
+- Fixed `AdminAuth.verifyPin()` to fail closed when admin config is missing, disabled, or malformed instead of returning success.
+- Fixed auth-required checks to fail closed when settings require admin PIN protection but the admin config is unusable.
+- Normalized admin session expiry handling by storing both `expires` and `expiresAt` and cleaning up both formats consistently.
+
+### Added
+- Added regression tests for admin PIN fail-closed behavior and session expiry cleanup.
+
+### Changed
+- Documented the public npm package staging flow introduced after `2.5.0`.
+
+## [2.5.0] - 2026-04-29
 
 ### Security
 - Centralized environment-variable access behind the `utils/env-manager.js` allowlist.

package/README.md

@@ -1,6 +1,6 @@
-# i18ntk v2.6.0
+# i18ntk v3.1.0
 
-Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, and translation completion.
+Zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic locale translation, and runtime translation loading.
 
 ![i18ntk Logo](https://raw.githubusercontent.com/vladnoskv/i18ntk/main/docs/screenshots/i18ntk-logo-public.PNG)
 
@@ -9,27 +9,18 @@ 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/2.6.0)](https://socket.dev/npm/package/i18ntk/overview/2.6.0)
+[![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 `2.6.0` may contain known stability and security issues.
-They are considered unsupported for production use. Upgrade to `2.6.0` or newer.
+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.
 
-## v2.6.0 — Deep-Code Audit Release
+## v3.1.0 - Auto Translate Hardening and Validation Warning Tuning
 
-v2.6.0 is a comprehensive hardening release from a two-pass code audit fixing 35+ bugs and security issues across 18 files. Highlights:
+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.
 
-- **Critical**: Fixed silent-write failures where `safeWriteFileSync` was called incorrectly across 4 modules.
-- **Security**: Replaced all remaining raw `fs` calls with validated `SecurityUtils` wrappers.
-- **Security**: Fixed path traversal bypass in the fallback `SecurityUtils` implementation.
-- **Security**: Fixed Windows path traversal false negatives (fragile `path.sep` comparison).
-- **Security**: Added `safeUnlinkSync` and `safeRmdirSync` for validated file/directory deletion.
-- **Runtime**: Fixed process event handler leak, missing `setInterval.unref()`, and JSON parse error handling.
-- **TypeScript**: Fixed `BasicI18nRuntime.translate/t` return type from `Promise<string>` to `string`.
-- **Scripts**: Fixed `npm_execpath` fallback in build/release scripts.
-
-For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migration notes, see [docs/migration-guide-v2.6.0.md](./docs/migration-guide-v2.6.0.md).
+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
 
@@ -38,6 +29,7 @@ For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migrati
 - 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
 
@@ -48,6 +40,7 @@ For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migrati
 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).
 
@@ -100,6 +93,7 @@ i18ntk --command=usage
 i18ntk --command=scanner
 i18ntk --command=sizing
 i18ntk --command=complete
+i18ntk --command=translate
 i18ntk --command=summary
 ```
 
@@ -117,6 +111,7 @@ i18ntk-summary
 i18ntk-doctor
 i18ntk-fixer
 i18ntk-backup
+i18ntk-translate
 ```
 
 Note: `i18ntk --command=backup` in the manager flow is disabled in current builds.
@@ -133,12 +128,45 @@ 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
 i18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports
 ```
 
+## Auto Translate
+
+Interactive menu flow:
+
+```bash
+i18ntk
+# choose "Auto Translate (Beta)"
+```
+
+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
+```
+
+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.
+
+See [docs/auto-translate.md](docs/auto-translate.md) for full usage details.
+
 ## Runtime API
 
 Use `i18ntk/runtime` when your application needs to read locale JSON files at runtime.
@@ -169,12 +197,18 @@ Example `.i18ntk-config`:
 
 ```json
 {
-  "version": "2.6.0",
+  "version": "3.1.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
   "sourceLanguage": "en",
   "defaultLanguages": ["de", "es", "fr", "ru"],
+  "englishContentThresholdPercent": 10,
+  "allowedEnglishTerms": ["BrandName", "PRODUCT_CODE"],
+  "autoTranslate": {
+    "protectionEnabled": true,
+    "protectionFile": "./i18ntk-auto-translate.json"
+  },
   "setup": {
     "completed": true
   }
@@ -190,11 +224,13 @@ See [docs/api/CONFIGURATION.md](docs/api/CONFIGURATION.md) for the full configur
 - [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)
-- [Migration Guide v2.5.0](https://github.com/vladnoskv/i18ntk/blob/main/docs/migration-guide-v2.5.0.md)
 
 ## Community