i18ntk 2.5.1 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,385 @@
+# CHANGELOG
+
+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.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
+- **CRITICAL**: Fixed 8+ silent-write failures where `safeWriteFileSync` was called without basePath parameter across `utils/config.js`, `utils/config-helper.js`, `utils/secure-errors.js`, and `main/i18ntk-scanner.js`.
+- Replaced all raw `fs` calls (`readdirSync`, `statSync`, `mkdirSync`, `unlinkSync`, `rmSync`) with `SecurityUtils` wrappers in `main/i18ntk-validate.js`, `main/i18ntk-scanner.js`, `main/manage/commands/FixerCommand.js`, and `utils/secure-errors.js`.
+- Fixed path traversal checks in `security.js` and `config-manager.js` — replaced fragile `path.sep`-based comparison with robust `startsWith('..')` prefix check.
+- Hardened `utils/i18n-helper.js` fallback `SecurityUtils` implementation with path containment checks.
+- Fixed `SecurityUtils.safeParseJSON` reference leak — deep-clones objects instead of returning caller's reference.
+
+### Fixed
+- Fixed `main/i18ntk-analyze.js` `this.adminAuth` reference error (local variable was not assigned to instance property).
+- Fixed `main/i18ntk-validate.js` `ExitCodes.CONFIG_ERROR` referenced before declaration.
+- Fixed `main/i18ntk-scanner.js` `fs.readdirSync(projectRoot, { recursive: true })` removed (unsupported in older Node.js).
+- Fixed `main/i18ntk-scanner.js` raw `fs.readdirSync`/`fs.statSync`/`fs.mkdirSync` in `scanDirectory` and `generateReport`.
+- Fixed `main/i18ntk-validate.js` raw `fs.readdirSync`/`fs.mkdirSync`/`fs.unlinkSync` in `getAvailableLanguages`, `getLanguageFiles`, and validation report cleanup.
+- Fixed `utils/secure-errors.js` `safeWriteFileSync` missing basePath and raw `fs.mkdirSync`.
+- Fixed `main/manage/commands/FixerCommand.js` `cleanupOldBackups` using raw `fs.rmSync` without path validation.
+- Fixed `runtime/enhanced.js` process event handler leak (multiple instances) and missing `setInterval.unref()`.
+- Fixed `utils/setup-enforcer.js` async Promise executor anti-pattern.
+- Fixed `utils/config-manager.js` stale `process.cwd()` capture at module load time.
+- Fixed `utils/config-manager.js` `ensureProjectSettingsDir` being a no-op.
+- Fixed `utils/config-helper.js` 7 `safeWriteFileSync` calls missing basePath in `initializeSourceFiles`.
+- Fixed `utils/env-manager.js` `getBoolean` comparison against non-boolean values.
+- Fixed `utils/admin-auth.js` `uncaughtException` handler wrong parameter format.
+
+### Added
+- `SecurityUtils.safeUnlinkSync(filePath, basePath)` — safely delete a file.
+- `SecurityUtils.safeRmdirSync(dirPath, basePath)` — safely remove a directory.
+
+### Changed
+- `configManager.resolvePaths`, `configManager.toRelative`, and config lock path now dynamically resolve via `getUserProjectRoot()`/`getProjectConfigPath()`.
+- `configManager.CONFIG_PATH` is now a getter that dynamically returns the project config path.
+- `configManager.migrateLegacyIfNeeded` exported for testability.
+
+### TypeScript
+- Fixed `runtime/i18ntk.d.ts` `BasicI18nRuntime.translate` and `t` return types from `Promise<string>` to `string`.
+
+### 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
+
+### Security
+- Centralized environment-variable access behind the `utils/env-manager.js` allowlist.
+- Hardened `SecurityUtils.safeJoin()` and path validation against sibling-prefix containment bypasses.
+- Switched admin PIN hash verification to timing-safe comparison.
+- Fixed expired admin session cleanup and unref'd the cleanup timer so it does not keep CLI processes alive.
+- Expanded the release security scanner to inspect nested production source files.
+
+### Fixed
+- Fixed the manager fixer command so applied fixes are written to the same parsed object that is saved.
+- Fixed fixer writes for absolute source directories outside the current working directory.
+- Fixed debug-menu file reads to use `SecurityUtils` wrappers.
+- Fixed `secure-errors` to import its `SecurityUtils` dependency explicitly.
+
+### Changed
+- Updated package and documentation metadata to `2.5.0`.
+
+## [2.4.0] - 2026-04-16
+
+### Changed
+- Disabled npm registry update-check behavior in CLI startup paths.
+- Disabled manager-route backup execution (`i18ntk --command=backup`); standalone `i18ntk-backup` remains available.
+- Disabled setup prerequisite command probing via `PATH` inspection.
+- Updated README/docs/migration guides/environment variable documentation to reflect the above behavior.
+
+## [2.3.8] - 2026-04-13
+
+### Added
+- Added centralized structured logger with standardized prefixes and configurable levels (`error`, `warn`, `info`, `debug`).
+- Added opt-in JSON log output for CI/build pipelines via `JSON_LOG=true`.
+- Added missing-translation-key cache TTL (5 minutes) to prevent repeated key-miss spam.
+- Added build/worker logging utilities for percentage progress and pooled worker activity summaries.
+- Added test coverage for logger timing/progress/worker aggregation behavior.
+
+### Fixed
+- Fixed repeated default-configuration fallback output by emitting a single fallback notice per process.
+- Fixed recursive security/i18n logging interactions that could trigger repeated warning cascades.
+- Fixed false-positive security warnings for internal package/project absolute paths through internal root whitelisting.
+
+### Changed
+- Logging is now silent by default for non-critical output in production-like builds unless `DEBUG_MODE=true`.
+- Security warning reasons now use specific detection details instead of generic "dangerous patterns".
+- Updated package/docs/version metadata to `2.3.8`.
+
+## [2.3.7] - 2026-04-12
+
+### Fixed
+- Removed false-positive path traversal warnings for safe absolute project paths during framework builds.
+- Reduced repeated default-configuration console noise in multi-worker build environments.
+
+### Changed
+- Security event console logging is now fully opt-in via `I18NTK_ENABLE_SECURITY_LOGS=true` (or debug envs).
+- Config-manager diagnostic console logging is now fully opt-in via `I18NTK_ENABLE_LOGS=true` (or debug envs).
+- Updated docs to reflect new default-silent logging behavior and troubleshooting toggles.
+
+## [2.3.6] - 2026-04-12
+
+### Security
+- **Fixed path traversal vulnerability** in temporary file creation
+- **Added `safeJoin` function** for secure path construction
+- **Improved path validation** throughout the codebase
+
+### Fixed
+- Hardened settings reset and backup cleanup paths to reduce risk of broad/deep unintended file deletion.
+- Hardened backup command path handling to keep source/output/restore operations inside project boundaries by default.
+- Fixed backup-class async file operations to consistently use `fs.promises` APIs.
+
+### Changed
+- **Silent security logging by default**: Info-level messages suppressed, warnings/errors shown
+- **Debug mode**: Enable verbose logging with `I18N_DEBUG=true`
+- **Centralized security logging**: All security events use `SecurityUtils.logSecurityEvent()`
+- Made npm registry update checks explicit opt-in via `I18NTK_ENABLE_UPDATE_CHECK`.
+- Updated package/docs/version metadata to `2.3.6`.
+
+## [2.3.4] - 2026-04-12
+
+### Fixed
+- Fixed runtime autosave behavior so configuration write failures no longer hard-throw through request/render paths.
+- Fixed config save race resilience by combining queued writes, cross-process lock files, and unique temp filenames per write.
+
+### Added
+- Added `I18NTK_DISABLE_AUTOSAVE` support to skip disk persistence and keep in-memory config in server/runtime environments.
+- Added config-manager concurrency regression test covering parallel `saveConfig` calls.
+
+### Changed
+- Updated package/docs/version metadata to `2.3.4`.
+- Updated support policy guidance to recommend upgrading from versions below `2.3.4`.
+
+## [2.3.3] - 2026-04-12
+
+### Fixed
+- Fixed production config persistence race across multiple Node processes by adding cross-process file locking for `.i18ntk-config` writes.
+- Fixed intermittent `ENOENT` during atomic config rename operations under concurrent production traffic.
+
+### Changed
+- Updated package/docs/version metadata to `2.3.3`.
+- Updated support policy guidance to recommend upgrading from versions below `2.3.3`.
+
+## [2.3.2] - 2026-04-12
+
+### Added
+- Added startup npm-registry version checks that warn when the installed CLI is behind the latest published `i18ntk` release.
+- Added support for checking all published semver versions up to the current latest tag to improve outdated-version detection reliability.
+
+### Fixed
+- Fixed fatal analyze-command startup failure in manager command flow caused by missing `validateSourceDir` import.
+
+### Changed
+- Updated package/docs/version metadata to `2.3.2`.
+- Updated support policy guidance to recommend upgrading from versions below `2.3.2`.
+
+## [2.3.1] - 2026-04-12
+
+### Fixed
+- Fixed package export-path fallback in `utils/i18n-helper` that could trigger build warnings in production bundlers (`i18ntk/resources/i18n/ui-locales/en.json` not exported).
+
+### Changed
+- Updated package/docs/version metadata to `2.3.1`.
+- Updated support policy guidance to recommend upgrading from versions below `2.3.1`.
+
+## [2.3.0] - 2026-04-12
+
+### Added
+- Added validation summary report output after validation runs.
+- Added init-time backup configuration prompt (default disabled, optional enable).
+
+### Fixed
+- Fixed backup recursion/pollution risk by moving automated fixer backups to a dedicated backup root.
+- Fixed backup retention behavior to keep 1 by default with enforced bounds up to 3.
+- Fixed language discovery in validate/fixer flows to ignore backup/report directories.
+
+### Changed
+- Updated package/docs/version metadata to `2.3.0`.
+- Updated support policy guidance to recommend upgrading from versions below `2.3.0`.
+
+## [2.2.0] - 2026-04-12
+
+### Added
+- Added an explicit upgrade/support notice in docs recommending upgrade from pre-`2.2.0` versions.
+- Added migration guide for `v2.2.0`.
+
+### Fixed
+- Fixed critical sizing workflow regressions.
+- Fixed critical usage-analysis workflow regressions.
+- Fixed runtime locale optimizer dependency path after publish-surface cleanup.
+
+### Changed
+- Reduced publish surface by excluding internal development scripts from npm package artifacts.
+- Excluded legacy fixed artifacts from package output (`main/manage/index-fixed.js`, `utils/security-fixed.js`).
+- Updated package/docs/version metadata to `2.2.0`.
+
+## [2.1.1] - 2026-04-11
+
+### Added
+- Version bump to 2.1.1 for release.
+- Added `SecurityUtils.debugLog` function for consistent debugging.
+
+### Fixed
+- Fixed `SecurityUtils.logSecurityEvent` calls missing `level` parameter in `i18ntk-usage` and `UsageService`.
+- Fixed `level.toLowerCase is not a function` error in usage analysis.
+- Fixed `SecurityUtils.debugLog is not a function` error in sizing analysis.
+
+### Changed
+- Updated package and release metadata to `2.1.1`.
+- Removed legacy `resources/i18n/ui-locales` path references (use `ui-locales/` instead).
+- Updated all UI locale loading to use `ui-locales/` directory.
+
+## [2.1.0] - 2026-04-11
+
+### Added
+- Added a v2.1.0 migration guide and updated release runbook references.
+- Added stricter language-directory filtering in analysis paths to ignore backup/report folders.
+
+### Fixed
+- Fixed interactive menu command flow so it reliably returns to the main menu after command completion.
+- Fixed analysis progress output to report the correct processed-language count.
+- Fixed duplicate report-save output lines during analysis.
+- Fixed framework detection behavior to treat setup-complete projects as internally configured i18ntk projects.
+- Fixed false-positive security warnings for valid configuration fields like `dateFormat`, `timeFormat`, and `reportLanguage`.
+- Fixed locale-loading path fallback behavior to avoid noisy startup errors in global installs.
+
+### Changed
+- Synchronized and normalized UI locale keys across `resources/i18n/ui-locales` and `ui-locales`.
+- Updated package/release metadata to `2.1.0`.
+
+## [2.0.0] - 2026-01-01
+
+### Added
+- Added missing runtime translation keys across `init`, `fixer`, `sizing`, `summary`, `usage`, and settings import/export flows.
+- Added `SecurityUtils.safeParseJSON`, `SecurityUtils.safeReadFile`, and `SecurityUtils.safeWriteFile` compatibility APIs used by v2 command paths.
+- Added source-locale bootstrap behavior during `init` when the source language directory exists but has no translation files.
+
+### Fixed
+- Fixed initialization state detection to use project `.i18ntk-config` setup metadata as the v2 source of truth.
+- Fixed false setup-invalid states caused by BOM-encoded config files during setup checks.
+- Fixed config persistence risk by using atomic writes in `config-manager` save flow.
+- Fixed self-dependency metadata so the package remains zero-dependency in v2.
+
+### Changed
+- Updated package release metadata for the v2 line (`versionInfo`, deprecations, nextVersion).
+
+## [1.10.2] - 2025-08-23
+
+### 🚨 Critical Fix
+- **Fixed projectRoot default path**: Resetting settings now correctly restores `projectRoot` to `/` instead of `./`, ensuring fresh installs work out-of-the-box
+
+### 🆕 New Features
+- **Centralized Environment Variable Management**: Added comprehensive environment variable support with validation and security controls
+- **Enhanced Debug Logging**: Improved debug logging with environment variable support for better troubleshooting
+- **Secure Plugin Loading**: Added path sanitization for module loading to prevent security issues
+
+### 🔒 Security Enhancements
+- **Enhanced Path Validation**: Strengthened path validation and file operations security
+- **Secure Module Loading**: Added path sanitization for all plugin/module loading operations
+- **Environment Variable Security**: Implemented centralized environment variable management with security filtering
+
+### 🛠️ Improvements
+- **Refactored Configuration Handling**: Updated config system with integrated environment variable support
+- **Enhanced Logging System**: Improved debug logging capabilities with environment variable integration
+- **Better Error Handling**: Enhanced error messages and debugging information
+
+### 📚 Documentation
+- **Environment Variables Guide**: Added comprehensive documentation for all supported environment variables
+- **Migration Notes**: Added clear migration guidance for projectRoot path changes
+
+### 🔧 Technical Changes
+- **Package Version**: Updated to v1.10.2 across all files
+- **Security Patches**: Applied security improvements to path handling and file operations
+
+## [1.10.1] - 2025-08-22
+
+### Added
+- **New Terminal-Icons Utility**: Added `terminal-icons` utility for better emoji support in terminal output
+- **Enhanced UI Text Processing**: Improved text processing with terminal-safe fallbacks for special characters
+
+### Fixed
+- Fixed infinite setup loop issue (Hotfix)
+- Resolved version string update inconsistencies
+
+### Changed
+- Update version strings across all files from 1.9.1 to 1.10.1
+- Remove outdated package-lock.json and backup config
+
+## [1.10.0] - 2025-08-22
+
+### Added
+- **Enhanced Runtime API**: Improved framework-agnostic translation runtime with better TypeScript support
+- **Framework Detection**: Enhanced support for Next.js, Nuxt.js, and SvelteKit projects
+- **Reset Script**: Added `reset-for-publish.js` for clean package publishing
+- **Documentation**: Comprehensive updates for new features and improvements
+- **Configuration Persistence**: Fixed configuration changes not being saved to disk
+- **Caching System**: Added configuration caching to prevent redundant initialization
+
+### Fixed
+- **DNR Functionality**: Fixed persistence of "Do Not Remind" settings across version updates
+- **Settings Management**: Improved error handling and logging for settings operations
+- **TypeScript Definitions**: Enhanced type safety and autocomplete for better developer experience
+- **Performance**: Optimized translation lookups with reduced memory footprint
+- **Shell Security**: Verified zero shell access vulnerabilities in setup-enforcer.js
+- **Configuration Loading**: Fixed multiple "Initializing with default configuration" messages
+- **Path Resolution**: Fixed source directory path handling for CLI arguments
+
+### Security
+- **Settings Persistence**: Secure handling of user preferences and framework settings
+- **Error Handling**: Improved error reporting for configuration issues
+- **Dependencies**: Maintained zero runtime dependencies for maximum security
+- **Shell Access**: Confirmed no child_process usage in setup-enforcer.js
+- **Input Validation**: Enhanced path validation for source and output directories
+
+
+
+## [1.9.1] - 2025-08-14
+
+### Added
+- **Python Support**: Full support for Python frameworks including Django, Flask, FastAPI, and generic Python projects
+- **Enhanced Framework Detection**: Improved accuracy for all supported frameworks with new Python detection algorithms
+- **Common Locale File**: Added `locales/common.json` for shared translation keys across frameworks
+- **Zero Shell Security**: Complete removal of `child_process` dependencies for maximum security
+- **Exit/Cancel Option**: Added option to exit/cancel (press 0) during directory selection in fixer command
+
+### Changed
+- **Security Overhaul**: Replaced all `child_process` imports with native Node.js APIs
+- **Performance**: Maintained 97% performance improvement while adding security enhancements
+- **Framework Detection**: Updated detection patterns for JavaScript, Python, Go, Java, and PHP
+- **File Structure**: Optimized package structure with removed outdated files
+- **Documentation**: Comprehensive updates to reflect new features and security improvements
+
+### Removed
+- **Outdated Test Files**: Cleaned up test directories and removed deprecated test scripts
+- **Debug Tools**: Removed unused benchmark and package test files
+- **Shell Dependencies**: Eliminated all shell command dependencies
+- **Legacy Files**: Removed outdated configuration and development files
+
+### Security
+- **Zero Vulnerabilities**: Successfully passed security audit with 0 vulnerabilities
+- **Memory Safety**: Enhanced memory-safe operations throughout the codebase
+- **Input Validation**: Improved validation for all user inputs and file operations
+- **Dependency Cleanup**: Removed all shell-related dependencies
+
+### Performance
+- **Zero Overhead**: Security enhancements added zero performance overhead
+- **Python Detection**: Minimal overhead from new Python framework detection
+- **Memory Usage**: Maintained <2MB memory usage for all operations
+- **Validation**: Enhanced validation with no performance impact

package/README.md

@@ -1,6 +1,6 @@
-# i18ntk v2.5.1
+# i18ntk v3.0.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,52 +9,25 @@ 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.5.1)](https://socket.dev/npm/package/i18ntk/overview/2.5.1)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/3.0.0)](https://socket.dev/npm/package/i18ntk/overview/3.0.0)
 
 ## Upgrade Notice
 
-Versions earlier than `2.5.1` may contain known stability and security issues.
-They are considered unsupported for production use. Upgrade to `2.5.1` or newer.
-
-## v2.5.1 Security Update
-
-`v2.5.1` is a security and packaging-process update for the `2.5.x` release line.
-
-### Change Summary
-
-- Hardened `utils/admin-auth.js` so `verifyPin()` fails closed when admin config is missing, disabled, or malformed.
-- Hardened auth-required checks so enabled PIN protection does not silently bypass authentication when admin config is unusable.
-- Normalized admin session expiry handling by storing both `expires` and `expiresAt` and cleaning up either format consistently.
-- Marked the root `package.json` as development-only and added a separate public manifest flow.
-- Added package scripts to stage, pack, and publish the public npm package from `package.public.json`.
-- Added a root publish guard via `prepack` and `prepublishOnly` to block accidental publishing of the development manifest.
-- Updated ignore rules to exclude release staging artifacts and public package metadata from the repo/package payload.
-- Replaced the expanded `SECURITY.md` policy with a shorter reporting-oriented policy and added community docs links.
-- Updated docs and release reset automation to use `npm run package:public` instead of `npm pack --dry-run`.
-
-### Files Changed
-
-- `utils/admin-auth.js`: fixed fail-open PIN verification and session expiry consistency.
-- `tests/security.test.js`: added admin-auth fail-closed and session cleanup coverage.
-- `package.json`: set development-only metadata, adjusted included files, and added public packaging/publish scripts.
-- `package.public.json`: introduced the stripped public npm manifest.
-- `scripts/build-public-package.js`: added the public package staging, pack, and publish workflow.
-- `scripts/prevent-root-publish.js`: added a guard against publishing the root development manifest.
-- `scripts/reset-release-state.js`: switched release validation to the public package build flow.
-- `README.md`, `docs/README.md`, `docs/development/AGENTS.md`, `docs/migration-guide-v2.5.1.md`, `docs/migration-guide-v2.5.0.md`: documented the security fix, packaging, and community file layout.
-- `SECURITY.md`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `FUNDING.md`: updated or added community and security-facing docs.
-- `.gitignore`, `.npmignore`: excluded release staging output and public-package metadata.
-
-### Audit Trail
-
-- Risk addressed: AI-based analysis flagged `verifyPin()` as fail-open when admin config was missing or disabled.
-- Behavior change: direct `verifyPin()` calls now return `false` unless a usable enabled PIN config exists.
-- Behavior change: when settings require PIN auth but admin config is broken, protected auth checks now require authentication and verification fails closed.
-- Risk: the root manifest is intentionally non-publishable, so publishing flows must use the public-package scripts.
-- Behavior change: `npm pack` and `npm publish` at the repo root are blocked by guard scripts.
-- Behavior change: the public npm payload is staged from `package.public.json` rather than the development manifest.
-- Validation note: release-state reset now exercises `npm run package:public` as part of its checks.
-- Validation note: this documentation update describes the working tree changes used for the packaging split.
+Versions earlier than `3.0.0` may contain known stability and security issues.
+They are considered unsupported for production use. Upgrade to `3.0.0` or newer.
+
+## v3.0.0 - Auto Translate Release
+
+v3.0.0 adds automatic JSON locale translation through the management menu and the standalone `i18ntk-translate` command. Highlights:
+
+- **Auto Translate (Beta)**: Translate one or more source JSON files into one or more target languages from menu option 14.
+- **Standalone CLI**: Use `i18ntk-translate <source-file> <target-lang>` for direct automation and batch translation.
+- **Dry-run preview**: Review translated/skipped counts before writing target files.
+- **Placeholder protection**: Detect and preserve placeholders such as `{name}`, `{{count}}`, `%s`, `%d`, `:id`, `%{name}`, and `${value}`.
+- **Post-translation report**: Print or write translated and skipped key counts.
+- **Zero dependencies**: Translation support uses built-in Node.js modules and the free Google Translate endpoint.
+
+For the full detailed changelog, see [CHANGELOG.md](./CHANGELOG.md). For migration notes, see [docs/migration-guide-v3.0.0.md](./docs/migration-guide-v3.0.0.md).
 
 ## What i18ntk Does
 
@@ -63,6 +36,7 @@ They are considered unsupported for production use. Upgrade to `2.5.1` or newer.
 - 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
 
@@ -73,6 +47,7 @@ They are considered unsupported for production use. Upgrade to `2.5.1` or newer.
 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).
 
@@ -125,6 +100,7 @@ i18ntk --command=usage
 i18ntk --command=scanner
 i18ntk --command=sizing
 i18ntk --command=complete
+i18ntk --command=translate
 i18ntk --command=summary
 ```
 
@@ -142,6 +118,7 @@ i18ntk-summary
 i18ntk-doctor
 i18ntk-fixer
 i18ntk-backup
+i18ntk-translate
 ```
 
 Note: `i18ntk --command=backup` in the manager flow is disabled in current builds.
@@ -158,12 +135,42 @@ Use the standalone `i18ntk-backup` executable when backup operations are require
 - `--dry-run`
 - `--help`
 
+Auto Translate also supports:
+
+- `--source-lang <code>`
+- `--files <pattern>`
+- `--skip-placeholders`
+- `--send-placeholders`
+- `--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 --skip-placeholders
+```
+
+The manager flow accepts comma- or space-separated target language codes, previews the first target language with a dry run, asks for confirmation, then writes translated files under matching target-language directories such as `locales/de/common.json`.
+
+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.
@@ -194,7 +201,7 @@ Example `.i18ntk-config`:
 
 ```json
 {
-  "version": "2.5.1",
+  "version": "3.0.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",
@@ -215,10 +222,12 @@ 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.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
 

package/main/i18ntk-analyze.js

@@ -252,7 +252,7 @@ class I18nAnalyzer {
               const relativePath = path.relative(this.sourceDir, fullPath);
               const shouldExclude = (this.config.excludeFiles || []).some(pattern => {
                 if (typeof pattern === 'string') {
-                  return relativePath === pattern || relativePath.endsWith(path.sep + pattern);
+                  return relativePath === pattern || relativePath.endsWith('/' + pattern) || relativePath.endsWith('\\' + pattern);
                 }
                 if (pattern instanceof RegExp) {
                   return pattern.test(relativePath);
@@ -908,9 +908,9 @@ try {
         const isRequired = await adminAuth.isAuthRequired();
         if (isRequired) {
           console.log('\n' + t('adminCli.authRequiredForOperation', { operation: 'analyze translations' }));
-          const cliHelper = require('../utils/cli-helper');
-        const pin = await cliHelper.promptPin(t('adminCli.enterPin'));
-        const isValid = await this.adminAuth.verifyPin(pin);
+          const cli = require('../utils/cli-helper');
+        const pin = await cli.promptPin(t('adminCli.enterPin'));
+        const isValid = await adminAuth.verifyPin(pin);
           
           if (!isValid) {
             console.log(t('adminCli.invalidPin'));

package/main/i18ntk-scanner.js

@@ -181,9 +181,9 @@ class I18nTextScanner {
         if (pyproject.includes('Flask')) return 'flask';
       }
 
-      // Check for Python files
-      const hasPythonFiles = fs.readdirSync(projectRoot, { recursive: true })
-        .some(file => file.endsWith && file.endsWith('.py'));
+      // Check for Python files using safeReaddirSync
+      const pythonItems = SecurityUtils.safeReaddirSync(projectRoot, projectRoot, { withFileTypes: true }) || [];
+      const hasPythonFiles = pythonItems.some(item => item.isFile && item.name && item.name.endsWith('.py'));
       if (hasPythonFiles) return 'python';
     } catch (error) {
       // Continue to JS frameworks
@@ -420,20 +420,22 @@ class I18nTextScanner {
     const extensions = ['.js', '.jsx', '.ts', '.tsx', '.vue', '.html', '.svelte', '.py', '.pyx', '.pyi'];
 
     const scanRecursive = (currentDir) => {
-      const items = fs.readdirSync(currentDir);
+      const items = SecurityUtils.safeReaddirSync(currentDir, path.dirname(currentDir), { withFileTypes: true });
+      if (!items) return;
 
       for (const item of items) {
-        const fullPath = path.join(currentDir, item);
-        const stat = fs.statSync(fullPath);
+        const fullPath = path.join(currentDir, item.name);
+        const stat = SecurityUtils.safeStatSync(fullPath, currentDir);
+        if (!stat) continue;
 
         if (stat.isDirectory()) {
-          if (!item.startsWith('.') && !this.shouldExcludeFile(fullPath, exclusions)) {
+          if (!item.name.startsWith('.') && !this.shouldExcludeFile(fullPath, exclusions)) {
             scanRecursive(fullPath);
           }
         } else if (stat.isFile()) {
-          const ext = path.extname(item);
+          const ext = path.extname(item.name);
           if (extensions.includes(ext) && !this.shouldExcludeFile(fullPath, exclusions)) {
-            if (!includeTests && (item.includes('.test.') || item.includes('.spec.'))) {
+            if (!includeTests && (item.name.includes('.test.') || item.name.includes('.spec.'))) {
               continue;
             }
 
@@ -455,7 +457,7 @@ class I18nTextScanner {
 
   async generateReport(results, outputDir) {
     if (!SecurityUtils.safeExistsSync(outputDir, path.dirname(outputDir))) {
-      fs.mkdirSync(outputDir, { recursive: true });
+      SecurityUtils.safeMkdirSync(outputDir, process.cwd(), { recursive: true });
     }
 
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
@@ -472,11 +474,11 @@ class I18nTextScanner {
     };
 
     // JSON report
-    SecurityUtils.safeWriteFileSync(reportFile, JSON.stringify(summary, null, 2), outputDir);
+    SecurityUtils.safeWriteFileSync(reportFile, JSON.stringify(summary, null, 2), outputDir, 'utf8');
 
     // Markdown summary
     const mdContent = this.generateMarkdownReport(summary);
-    SecurityUtils.safeWriteFileSync(summaryFile, mdContent, outputDir);
+    SecurityUtils.safeWriteFileSync(summaryFile, mdContent, outputDir, 'utf8');
 
     return { reportFile, summaryFile, summary };
   }