i18ntk 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -3,8 +3,57 @@
 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).
-
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [4.1.0] - 2026-05-21
+
+### Fixed
+- Runtime: stale manifest entries (deleted files after manifest construction) no longer cause unhandled exceptions; loadedFiles set before load with try/catch guard.
+- Runtime: `refresh()` now correctly clears the key manifest for the refreshed language, preventing stale file references.
+- Runtime: null `baseDir` guard prevents cascading `validatePath(null)` errors in `loadKeyManifestFromDir`.
+- Backup: `handleVerify` hash-chain verification rewritten for incremental backups — rebuilds full state oldest→newest before per-entry hash comparison; no longer reports false "Missing file" errors for unchanged files.
+- Backup: `cleanupOldBackups` and `handleCleanup` now preserve parent backups of incremental chains by scanning kept backups for `_meta.parent` references before deletion.
+- Backup: `--incremental=false` is now correctly parsed as falsy (string-to-boolean conversion fixed).
+- Backup: `buildRestoreChain` detects circular parent references via visited-set traversal.
+- Sizing: `this.adminAuth` undefined crash in `run()` fixed — changed to correct `adminAuth` local variable.
+- Sizing: duplicate `analyze()` method removed; format-based display logic (`--format=json` vs table) restored to the surviving method.
+- Sizing: setup-check IIFE now guarded with `require.main === module`, preventing unexpected `process.exit()` on `require()`.
+- Scanner: `frameworks.vanilla` key added to `getFrameworkSpecific` — no longer returns `undefined` for vanilla projects.
+- Scanner: `--source-language` CLI flag now correctly propagates through config chain to `scanFile` and `generateSuggestion` (camelCase vs hyphen key mismatch fixed).
+- Scanner: `isTextInLanguage` now always validates character ratio unconditionally even for no-stopword language profiles.
+- Watch: `{ onChange: fn }` object-format callbacks are now properly subscribed to change/add/unlink events.
+- Watch: debounce `setTimeout` timers are now stored per-watcher and cleared on `emitter.stop()`, preventing memory leaks and spurious I/O after stop.
+- Watch: `'unlink'` events are now subscribed for backward-compatible plain-function callback users.
+- Usage: duplicate `require.main === module` block removed (caused `TypeError: Identifier 'main' has already been declared` at execution).
+- Usage: `_keyInSourceComments` optimized from O(n*m) to O(n+m) by pre-computing a `Set` of all comment strings once before the dead key loop.
+- Usage: `--cleanup=false` and `--dry-run-delete=false` now correctly parse as falsy via `toBool()` helper.
+- Usage: broken `detectFrameworkPatterns()` call with `undefined` arguments removed.
+- Usage: dead `return;` in `analyze()` removed so the result object is now actually returned.
+- Validator: missing `try` block in `run()` added so errors are caught by the existing `catch(error)` handler.
+- Validator: `--enforce-key-style=true/false` now correctly parsed (previously silently ignored due to `!includes('=')` guard).
+- Validator: `flat` style no longer produces false positives for nested keys — validates only the leaf segment (last `.`-delimited part).
+- Validator: `suggestKeyFix` for `flat` style now returns `segments.map(s => s.toLowerCase()).join('')` instead of camelCase.
+- Validator: `getLanguageFiles` no longer crashes when `excludeFiles` config property is undefined.
+- Validator: `enforceKeyStyle` now correctly propagated from CLI args to `this.config.enforceKeyStyle` in `run()`.
+- Protection: `standalone` mode boundary check now handles opening/closing punctuation (`(`, `[`, `{`, `"`, `'`, `-`, `–`, `—`) and CJK marks (`。`, `、`, `」`).
+- Protection: `\b` word-boundary assertions replaced with Unicode-aware `(^|[\s\p{P}])` / `([\s\p{P}]|$)` patterns with `u` flag for non-ASCII language support.
+- Protection: `surrounded` context rule parser now uses `indexOf(',')` split instead of greedy `(.+,.+)` regex to correctly parse multi-word right-side expressions.
+- Protection: `hasProtectionRules` no longer throws `TypeError` when `terms` property is undefined.
+- Protection: `shouldPreserveWholeValue` now respects context rules by only matching `type === 'global'` entries.
+- Manager option 7 ("Fix placeholder translations") now interpolates fixer status values correctly instead of printing raw `{languages}`, `{sourceDir}`, `{skipped}`, or `{totalIssues}` placeholders.
+- Delete Reports settings now include cache cleanup targets.
+- Public package metadata updated.
+
+### Security
+- Watch module: debounce timers properly cleaned up on stop and callback subscriptions corrected for object-format and unlink handlers.
+- Runtime: loadedFiles lock-before-load pattern prevents duplicate I/O and stale manifest crash.
+- Backup: circular parent reference detection; `--incremental=false` string truthy bypass closed.
+- Sizing: adminAuth variable reference corrected; require()-time `process.exit()` guarded.
+- Scanner: vanilla framework key prevents `undefined` return; stopword-less validRatio enforced.
+- Usage: O(n+m) comment scanning prevents DoS via large codebase with many dead keys; `toBool()` prevents flag injection.
+- Validator: try/catch pairing restored; `flat` leaf-segment prevents false-positive flood.
+- Protection: Unicode-aware punctuation boundaries for CJK/Cyrillic/Arabic; standalone boundaries include the expanded punctuation set.
+
 ## [4.0.0] - 2026-05-21
 
 ### Added
@@ -17,32 +66,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Runtime Lazy Loading**: `runtime/index.js` adds `lazy: true` option to `initRuntime()`. Defers locale file loading until the first key access, guided by an auto-generated key-to-file manifest. Falls back to eager loading if manifest is missing. Manifest capped at 100KB with path containment validation.
 - **Protection Context-Aware Rules**: `utils/translate/protection.js` extends the protection config schema to support context rules (`after:word`, `before:word`, `standalone`, `surrounded:left,right`). Plain string terms remain fully backward compatible. Total context rules capped at 100.
 
-### Fixed
-- `i18ntk/runtime` `initRuntime()` now returns independent runtime instances with separate language, fallback language, base directory, and cache state. Later `initRuntime()` calls no longer overwrite earlier returned runtimes or the module-level compatibility singleton.
-- Manager option 7 ("Fix placeholder translations") now interpolates fixer status values correctly instead of printing raw `{languages}`, `{sourceDir}`, `{skipped}`, or `{totalIssues}` placeholders.
+### Fixed
+- `i18ntk/runtime` `initRuntime()` now returns independent runtime instances with separate language, fallback language, base directory, and cache state. Later `initRuntime()` calls no longer overwrite earlier returned runtimes or the module-level compatibility singleton.
 
-### Changed
-- `watchLocales()` now returns a callable watcher object with EventEmitter methods instead of only a bare `stop` function. Existing `const stop = watchLocales(...); stop();` usage remains supported. The returned object fires `change`, `add`, `unlink`, `error` events. If a callback function is passed as the second argument, it is auto-subscribed to `change` and `add` for backward compatibility.
+### Changed
+- `watchLocales()` now returns a callable watcher object with EventEmitter methods instead of only a bare `stop` function. Existing `const stop = watchLocales(...); stop();` usage remains supported. The returned object fires `change`, `add`, `unlink`, `error` events. If a callback function is passed as the second argument, it is auto-subscribed to `change` and `add` for backward compatibility.
 - **BREAKING**: `i18ntk-sizing` JSON reports now include `expansionPredictions` at the top level when `--predict-expansion` is used. This field is additive — existing report fields are preserved.
 
-### Security
-- All new features reuse existing `SecurityUtils.safe*` wrappers for file I/O, path validation, and input sanitization.
-- Watch module validates all directory paths against project root with containment checks and caps at 50 directories.
-- Runtime lazy-loading manifest entries validated for path containment and size-limited to 100KB.
-- Protection context rules parsed from constrained DSL — never accepts raw user-controlled regex from config.
-- Backup incremental chain depth capped at 10 to prevent resource exhaustion; hash chain verified before restore.
-
-## [3.3.0] - 2026-05-20
+## [3.3.0] - 2026-05-20
 
-### Changed
-- Auto Translate now supports `--provider google|deepl|libretranslate`; DeepL uses `DEEPL_API_KEY`, while LibreTranslate supports `LIBRETRANSLATE_URL` and optional `LIBRETRANSLATE_API_KEY`.
-- Auto Translate provider networking now keeps HTTPS, host allowlist, response-size, private-network, and redacted security logging protections in place for additional providers.
-
-### Fixed
-- `i18ntk-complete` now fills missing target-language keys from the English source value with a language prefix such as `[DE] Home` instead of writing `NOT_TRANSLATED`; this works for both `locales/en/*.json` and monolith `locales/en.json` layouts.
-
-### Security
-- Eliminated all 21 dynamic `require()` calls flagged by Socket.dev: 20 `require(path.join(__dirname, ...))` patterns in `i18ntk-js.js`, `i18ntk-py.js`, `i18ntk-java.js`, `i18ntk-php.js`, and `i18ntk-go.js` converted to static string literal requires.
+### Changed
+- Auto Translate now supports `--provider google|deepl|libretranslate`; DeepL uses `DEEPL_API_KEY`, while LibreTranslate supports `LIBRETRANSLATE_URL` and optional `LIBRETRANSLATE_API_KEY`.
+- Auto Translate provider networking now keeps HTTPS, host allowlist, response-size, private-network, and redacted security logging protections in place for additional providers.
+
+### Fixed
+- `i18ntk-complete` now fills missing target-language keys from the English source value with a language prefix such as `[DE] Home` instead of writing `NOT_TRANSLATED`; this works for both `locales/en/*.json` and monolith `locales/en.json` layouts.
+
+### Security
+- Eliminated all 21 dynamic `require()` calls flagged by Socket.dev: 20 `require(path.join(__dirname, ...))` patterns in `i18ntk-js.js`, `i18ntk-py.js`, `i18ntk-java.js`, `i18ntk-php.js`, and `i18ntk-go.js` converted to static string literal requires.
 - Added `SecurityUtils.validatePath()` gate around the remaining dynamic `require()` in `i18ntk-translate.js` `loadCustomTranslateFn`.
 - Created `utils/translate/safe-network.js` — a secure HTTPS wrapper with URL host/path allowlist validation, response size limits (100KB), suspicious query parameter detection, and security event logging. All outbound network access now flows through this validated layer.
 - Replaced direct `https.get` call in `utils/translate/api.js` with `safeHttpGet` from the safe-network wrapper.
@@ -54,18 +95,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Socket.dev Analysis Disclaimer
 
-This package is a developer CLI and runtime helper that performs file I/O, network access (translation provider APIs on user request), and environment variable access. As such, Socket.dev will flag the following alerts that are **expected and by design**:
+This package is a developer CLI and runtime helper that performs file I/O, network access (translation provider APIs on user request), and environment variable access. As such, Socket.dev will flag the following alerts that are **expected and by design**:
 
 | Alert | Why it's expected |
 |---|---|
-| Network access | Only contacts configured translation providers via HTTPS when user invokes auto-translate. All outbound calls flow through `safe-network.js` with host/path allowlist validation, response size limits, private-network blocking, and redacted security event logging. No telemetry, no unexpected outbound calls. |
+| Network access | Only contacts configured translation providers via HTTPS when user invokes auto-translate. All outbound calls flow through `safe-network.js` with host/path allowlist validation, response size limits, private-network blocking, and redacted security event logging. No telemetry, no unexpected outbound calls. |
 | Environment variable access | Centralized through `env-manager.js` with a strict allowlist. Blocks `SECRET`, `PASSWORD`, `KEY`, `TOKEN`, `AWS_*`, `NPM_*`, and 15+ other patterns. |
 | Filesystem access | Reads/writes only project locale files and reports within validated paths. All FS operations gated by `SecurityUtils.validatePath`. |
-| URL strings | Hardcoded default provider URLs for Google, DeepL, and LibreTranslate used only for auto-translation. No external resource loading. |
-
-The v3.3.0 release resolves the actionable dynamic-require alert by eliminating all 21 instances.
-
-## [3.2.0] - 2026-05-16
+| URL strings | Hardcoded default provider URLs for Google, DeepL, and LibreTranslate used only for auto-translation. No external resource loading. |
+
+The v3.3.0 release resolves the actionable dynamic-require alert by eliminating all 21 instances.
+
+## [3.2.0] - 2026-05-16
 
 ### Security
 - **CRITICAL**: Fixed invalid `crypto.createCipherGCM`/`createDecipherGCM` API calls in `admin-pin.js` — replaced with `crypto.createCipheriv`/`createDecipheriv`.

package/README.md

@@ -1,4 +1,4 @@
-# i18ntk v4.0.0
+# i18ntk v4.1.0
 
 A i18n toolkit - A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
 
@@ -9,7 +9,7 @@ A i18n toolkit - A zero-dependency internationalization toolkit for setup, scann
 [![node](https://img.shields.io/badge/node-%3E%3D16-339933)](https://nodejs.org)
 [![dependencies](https://img.shields.io/badge/dependencies-0-success)](https://www.npmjs.com/package/i18ntk)
 [![license](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
-[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.0.0)](https://socket.dev/npm/package/i18ntk/overview/4.0.0)
+[![socket](https://socket.dev/api/badge/npm/package/i18ntk/4.1.0)](https://socket.dev/npm/package/i18ntk/overview/4.1.0)
 
 ## Install
 
@@ -30,6 +30,10 @@ Requirements:
 - npm `>=8.0.0`
 - No runtime dependencies
 
+## What's New in 4.1.0
+
+- **FIX**: Critical and high-impact bugs resolved across the v4.0.0 feature set — runtime staleness crashes, backup hash-chain verification, sizing adminAuth crash, scanner `--source-language` propagation, watch callback subscriptions, dead key detection performance, validator key style enforcement, and protection Unicode boundary handling. See [CHANGELOG.md](./CHANGELOG.md) for complete details.
+
 ## What's New in 4.0.0
 
 - **SIZING**: `--predict-expansion` flag computes per-key expansion ratios across languages with Safe/Warning/Critical risk tiers for UI layout planning.
@@ -40,7 +44,6 @@ Requirements:
 - **BACKUP**: `--incremental` flag creates differential backups with SHA-256 hashing and chained restores.
 - **RUNTIME**: `lazy: true` option defers locale file loading until first key access for lower memory usage.
 - **PROTECTION**: Context-aware rules (`after:word`, `before:word`, `standalone`, `surrounded:left,right`) for precise term masking.
-- **FIX**: `initRuntime()` now returns independent instances with isolated language and cache state.
 
 See [CHANGELOG.md](./CHANGELOG.md) for more release details.
 
@@ -446,7 +449,7 @@ Example:
 
 ```json
 {
-  "version": "4.0.0",
+  "version": "4.1.0",
   "sourceDir": "./locales",
   "i18nDir": "./locales",
   "outputDir": "./i18ntk-reports",

package/SECURITY.md

@@ -4,7 +4,7 @@
 
 The supported production line is `4.x`.
 
-Versions earlier than `4.0.0` are not recommended for production use because later releases include Auto Translate provider hardening, dynamic-require elimination, path-validation hardening, lazy loading with manifest validation, and incremental backup hash-chain verification.
+Versions earlier than `4.1.0` are not recommended for production use because later releases include Auto Translate provider hardening, dynamic-require elimination, path-validation hardening, lazy loading with manifest validation, incremental backup hash-chain verification, and post-4.0.0 critical bug fixes for runtime staleness, backup verification, and CLI flag parsing.
 
 ## Security Model
 
@@ -41,8 +41,10 @@ The v3.3.0 release **resolved** the previously actionable Socket.dev alert:
 The v4.0.0 release adds the following security hardening:
 - **Watch module**: all watched directories validated against project root with containment checks; capped at 50 directories.
 - **Runtime lazy loading**: key-to-file manifest entries validated for path containment; manifest size capped at 100KB.
-- **Incremental backups**: hash-chain verification before restore; chain depth capped at 10 increments.
-- **Protection context rules**: DSL-parsed context rules — never raw user-controlled regex from config; bounded at 200 chars per rule, 100 rules total.
+- **Incremental backups**: hash-chain verification before restore; chain depth capped at 10 increments; circular parent references detected.
+- **Protection context rules**: DSL-parsed context rules — never raw user-controlled regex from config; bounded at 200 chars per rule, 100 rules total; Unicode-aware `\p{P}` word boundaries for non-ASCII language support.
+- **Scanner multi-language detection**: source-language propagation fixed; stopword-less language profiles now still enforce valid-character ratios.
+- **Usage dead key detection**: optimized O(n+m) comment scanning instead of O(n*m); all CLI boolean flags validated with strict `toBool()` conversion.
 
 ## Reporting Vulnerabilities
 
@@ -66,7 +68,7 @@ Security reports are reviewed privately first. Confirmed issues should receive:
 
 ## User Guidance
 
-- Keep i18ntk updated to `4.0.0` or newer.
+- Keep i18ntk updated to `4.1.0` or newer.
 - Do not commit `.i18ntk-config`, admin PIN files, backup directories, generated reports, logs, npm credentials, or secret material.
 - Run i18ntk only in project directories you trust.
 - Review generated translation changes before committing them.

package/main/i18ntk-backup.js

@@ -98,18 +98,24 @@ function getParentHashes(parentData) {
   return hashes;
 }
 
-async function buildRestoreChain(startPath, startData) {
+async function buildRestoreChain(startPath, startData) {
   const chain = [{ path: startPath, data: startData }];
-  let current = startData;
-  let currentPath = startPath;
-
-  while (current._meta && current._meta.parent) {
-    if (chain.length >= 11) {
-      throw new Error('Chain broken: incremental backup chain exceeds the maximum depth of 10');
-    }
-    const parentName = current._meta.parent;
+  const visited = new Set();
+  visited.add(path.basename(startPath));
+  let current = startData;
+  let currentPath = startPath;
+
+  while (current._meta && current._meta.parent) {
+    if (chain.length >= 11) {
+      throw new Error('Chain broken: incremental backup chain exceeds the maximum depth of 10');
+    }
+    const parentName = current._meta.parent;
+    if (visited.has(parentName)) {
+      throw new Error('circular chain reference');
+    }
+    visited.add(parentName);
     const parentDir = path.dirname(currentPath);
-    const parentPath = path.join(parentDir, parentName);
+    const parentPath = path.join(parentDir, parentName);
     if (!SecurityUtils.safeExistsSync(parentPath, parentDir)) {
       throw new Error(`Chain broken: parent backup '${parentName}' not found in ${parentDir}`);
     }
@@ -122,10 +128,61 @@ async function buildRestoreChain(startPath, startData) {
     chain.push({ path: currentPath, data: current });
   }
 
-  chain.reverse();
-  return chain;
-}
-
+  chain.reverse();
+  return chain;
+}
+
+function readBackupData(backupPath, baseDir) {
+  const raw = SecurityUtils.safeReadFileSync(backupPath, baseDir, 'utf8');
+  if (raw === null) {
+    throw new Error(`Unable to read backup: ${path.basename(backupPath)}`);
+  }
+  return JSON.parse(raw);
+}
+
+function collectProtectedChainNames(backupDirPath, keptFiles) {
+  const protectedNames = new Set();
+  const byName = new Map();
+  for (const file of keptFiles) {
+    byName.set(file.name, file);
+  }
+
+  const queue = [];
+  for (const file of keptFiles) {
+    try {
+      const data = readBackupData(file.path, backupDirPath);
+      if (data._meta && data._meta.parent) {
+        queue.push(data._meta.parent);
+      }
+    } catch {}
+  }
+
+  while (queue.length > 0) {
+    const name = queue.shift();
+    if (protectedNames.has(name)) {
+      continue;
+    }
+    protectedNames.add(name);
+
+    const file = byName.get(name) || {
+      name,
+      path: path.join(backupDirPath, name)
+    };
+    if (!SecurityUtils.safeExistsSync(file.path, backupDirPath)) {
+      continue;
+    }
+
+    try {
+      const data = readBackupData(file.path, backupDirPath);
+      if (data._meta && data._meta.parent) {
+        queue.push(data._meta.parent);
+      }
+    } catch {}
+  }
+
+  return protectedNames;
+}
+
 const configManager = require('../utils/config-manager');
 const { logger } = require('../utils/logger');
 const { colors } = require('../utils/logger');
@@ -210,7 +267,15 @@ async function cleanupOldBackups(backupDirPath) {
       .sort((a, b) => b.time - a.time);
 
     const toDelete = backupFiles.slice(maxBackups);
-    for (const file of toDelete) {
+    const kept = backupFiles.slice(0, maxBackups);
+
+    const protectedChainNames = collectProtectedChainNames(backupDirPath, kept);
+
+    for (const file of toDelete) {
+      if (protectedChainNames.has(file.name)) {
+        logger.info(`  Keeping ${file.name} (parent of a kept incremental backup)`);
+        continue;
+      }
       try {
         await fsp.unlink(file.path);
       } catch (err) {
@@ -230,7 +295,7 @@ async function handleCreate(args) {
   const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
   const backupName = `backup-${timestamp}.json`;
   const backupPath = path.join(outputDir, backupName);
-  const isIncremental = !!args.incremental;
+  const isIncremental = args.incremental !== 'false' && args.incremental !== false;
 
   logger.debug(`Source directory: ${dir}`);
   logger.debug(`Backup will be saved to: ${backupPath}`);
@@ -488,32 +553,11 @@ async function handleVerify(args) {
     if (data._meta && data._meta.hashes) {
       logger.info('  Performing hash chain verification...');
 
-      const chain = [{ path: backupPath, data: data }];
-      let current = data;
-      let currentPath = backupPath;
-      while (current._meta && current._meta.parent) {
-        if (chain.length >= 11) {
-          logger.warn('  Chain broken: maximum incremental depth of 10 exceeded');
-          break;
-        }
-        const parentName = current._meta.parent;
-        const parentDir = path.dirname(currentPath);
-        const parentPath = path.join(parentDir, parentName);
-        if (!SecurityUtils.safeExistsSync(parentPath, parentDir)) {
-          logger.warn(`  Chain broken: parent '${parentName}' not found`);
-          break;
-        }
-        const parentRaw = SecurityUtils.safeReadFileSync(parentPath, parentDir, 'utf8');
-        if (parentRaw === null) {
-          logger.warn(`  Chain broken: cannot read parent '${parentName}'`);
-          break;
-        }
-        current = JSON.parse(parentRaw);
-        currentPath = parentPath;
-        chain.push({ path: currentPath, data: current });
-      }
-
+      const chain = await buildRestoreChain(backupPath, data);
+
       let allValid = true;
+
+      // Rebuild full state oldest->newest and verify each manifest against it.
       const reconstructed = {};
       for (const entry of chain) {
         const entryMeta = entry.data._meta;
@@ -526,13 +570,13 @@ async function handleVerify(args) {
 
         if (!entryHashes) {
           logger.warn(`  ${entryName}: no manifest hashes (legacy backup)`);
-          continue;
-        }
+          continue;
+        }
 
         let entryValid = true;
         for (const [file, expectedHash] of Object.entries(entryHashes)) {
           if (!Object.prototype.hasOwnProperty.call(reconstructed, file)) {
-            logger.warn(`    Missing file in manifest: ${file}`);
+            logger.warn(`    Missing file in reconstructed backup state: ${file}`);
             entryValid = false;
             continue;
           }
@@ -542,19 +586,20 @@ async function handleVerify(args) {
             entryValid = false;
           }
         }
+
+        if (entryValid) {
+          logger.success(`  ${entryName}: ${Object.keys(entryHashes).length} file(s) verified`);
+        } else {
+          allValid = false;
+        }
+      }
 
-        if (entryValid) {
-          logger.success(`  ${entryName}: ${Object.keys(entryHashes).length} file(s) verified`);
-        } else {
-          allValid = false;
-        }
-      }
-
-      if (allValid) {
-        logger.success('\nBackup chain verification passed');
-      } else {
-        logger.error('\nBackup chain verification FAILED');
-      }
+      if (allValid) {
+        logger.success('\nBackup chain verification passed');
+      } else {
+        logger.error('\nBackup chain verification FAILED');
+        process.exitCode = 1;
+      }
     } else {
       const fileCount = Object.keys(data).filter(k => k !== '_meta').length;
       logger.success('Backup is valid');
@@ -586,24 +631,33 @@ async function handleCleanup(args) {
     
     // Keep only the most recent 'keep' files
     const toDelete = backupFiles.slice(keep);
+    const kept = backupFiles.slice(0, keep);
     
     if (toDelete.length === 0) {
       logger.info('No old backups to delete.');
       return;
     }
     
-    // Delete old backups
-    for (const file of toDelete) {
-      try {
+    const protectedChainNames = collectProtectedChainNames(backupDir, kept);
+    let deletedCount = 0;
+    
+    // Delete old backups, skipping parents of kept backups
+    for (const file of toDelete) {
+      if (protectedChainNames.has(file.name)) {
+        logger.info(`  Keeping ${file.name} (parent of a kept incremental backup)`);
+        continue;
+      }
+      try {
         await fsp.unlink(file.path);
-        logger.info(`  - Deleted: ${file.name}`);
-      } catch (err) {
-        logger.error(`  - Failed to delete ${file.name}: ${err.message}`);
-      }
-    }
-    
-    logger.info(`\nRemoved ${toDelete.length} old backups`);
-    logger.info(`Total backups kept: ${keep}`);
+        logger.info(`  - Deleted: ${file.name}`);
+        deletedCount++;
+      } catch (err) {
+        logger.error(`  - Failed to delete ${file.name}: ${err.message}`);
+      }
+    }
+    
+    logger.info(`\nRemoved ${deletedCount} old backups`);
+    logger.info(`Total backups kept: ${keep}`);
     
   } catch (error) {
     logger.error('Error cleaning up backups:');

package/main/i18ntk-scanner.js

@@ -423,12 +423,11 @@ class I18nTextScanner {
       for (const word of words) {
         if (profile.stopwords.includes(word)) return true;
       }
-      const validChars = trimmed.match(/[\p{L}\p{N}\s\-,.!?':"()\[\]{}]/gu) || [];
-      const validRatio = validChars.length / trimmed.length;
-      return validRatio >= 0.5;
     }
 
-    return true;
+    const validChars = trimmed.match(/[\p{L}\p{N}\s\-,.!?':"()\[\]{}]/gu) || [];
+    const validRatio = validChars.length / trimmed.length;
+    return validRatio >= 0.5;
   }
 
   scanFile(filePath, patterns, minLength, maxLength) {
@@ -436,7 +435,7 @@ class I18nTextScanner {
       const content = SecurityUtils.safeReadFileSync(filePath, path.dirname(filePath), 'utf8');
       const lines = content.split('\n');
       const results = [];
-      const sourceLang = this.config.sourceLanguage || 'en';
+      const sourceLang = this.sourceLanguage || 'en';
 
       patterns.forEach(pattern => {
         let match;
@@ -475,7 +474,7 @@ class I18nTextScanner {
   }
 
   generateSuggestion(text) {
-    const sourceLang = this.config.sourceLanguage || 'en';
+    const sourceLang = this.sourceLanguage || 'en';
     const transliterations = {
       ja: { 'あ': 'a', 'い': 'i', 'う': 'u', 'え': 'e', 'お': 'o', 'か': 'ka', 'き': 'ki', 'く': 'ku', 'け': 'ke', 'こ': 'ko', 'さ': 'sa', 'し': 'shi', 'す': 'su', 'せ': 'se', 'そ': 'so', 'た': 'ta', 'ち': 'chi', 'つ': 'tsu', 'て': 'te', 'と': 'to', 'な': 'na', 'に': 'ni', 'ぬ': 'nu', 'ね': 'ne', 'の': 'no', 'は': 'ha', 'ひ': 'hi', 'ふ': 'fu', 'へ': 'he', 'ほ': 'ho', 'ま': 'ma', 'み': 'mi', 'む': 'mu', 'め': 'me', 'も': 'mo', 'や': 'ya', 'ゆ': 'yu', 'よ': 'yo', 'ら': 'ra', 'り': 'ri', 'る': 'ru', 'れ': 're', 'ろ': 'ro', 'わ': 'wa', 'を': 'wo', 'ん': 'n' },
       ru: { 'а': 'a', 'б': 'b', 'в': 'v', 'г': 'g', 'д': 'd', 'е': 'e', 'ё': 'yo', 'ж': 'zh', 'з': 'z', 'и': 'i', 'й': 'y', 'к': 'k', 'л': 'l', 'м': 'm', 'н': 'n', 'о': 'o', 'п': 'p', 'р': 'r', 'с': 's', 'т': 't', 'у': 'u', 'ф': 'f', 'х': 'kh', 'ц': 'ts', 'ч': 'ch', 'ш': 'sh', 'щ': 'sch', 'ъ': '', 'ы': 'y', 'ь': '', 'э': 'e', 'ю': 'yu', 'я': 'ya' },
@@ -533,6 +532,9 @@ class I18nTextScanner {
         gettext: `import gettext\ngettext.gettext('${text}')`,
         underscore: `from gettext import gettext as _\n_('${text}')`,
         lazy: `from gettext import gettext_lazy as _\n_('${text}')`
+      },
+      vanilla: {
+        generic: `t('ui.${text.toLowerCase().replace(/[^a-z0-9\s]/g, '').replace(/\s+/g, '_')}')`
       }
     };
 
@@ -696,7 +698,7 @@ class I18nTextScanner {
     this.sourceDir = this.config.sourceDir || './src';
 
     // Source language for multi-language detection
-    this.sourceLanguage = args['source-language'] || this.config.sourceLanguage || 'en';
+    this.sourceLanguage = args.sourceLanguage || this.config.sourceLanguage || 'en';
 
     // Resolve framework with precedence: CLI arg > config.framework.preference|string > auto-detect > fallback
     const cliFramework = args.framework;

package/main/i18ntk-sizing.js

@@ -41,15 +41,17 @@ const { logger } = require('../utils/logger');
 const { getGlobalReadline, closeGlobalReadline } = require('../utils/cli');
 const SetupEnforcer = require('../utils/setup-enforcer');
 
-// Ensure setup is complete before running
-(async () => {
-  try {
-    await SetupEnforcer.checkSetupCompleteAsync();
-  } catch (error) {
-    console.error('Setup check failed:', error.message);
-    process.exit(1);
-  }
-})();
+// Ensure setup is complete before running (only when executed directly)
+if (require.main === module) {
+  (async () => {
+    try {
+      await SetupEnforcer.checkSetupCompleteAsync();
+    } catch (error) {
+      console.error('Setup check failed:', error.message);
+      process.exit(1);
+    }
+  })();
+}
 
 loadTranslations();
 
@@ -1100,45 +1102,7 @@ Generated: ${new Date().toISOString()}
     }
   }
 
-  // Main analysis method
-  async analyze() {
-    const startTime = Date.now();
-    
-    try {
-        logger.info(t("sizing.starting_i18n_sizing_analysis"));
-        logger.info(t("sizing.source_directory", { sourceDir: this.sourceDir }));
-      
-      const files = this.getLanguageFiles();
-      
-      if (files.length === 0) {
-          logger.warn(t("sizing.no_translation_files_found"));
-          return;
-      }
-      
-      logger.info(t("sizing.found_languages", { languages: files.map(f => f.language).join(', ') }));
-      
-      this.analyzeFileSizes(files);
-      this.analyzeTranslationContent(files);
-      this.generateSizeComparison();
-      
-      if (this.format === 'table') {
-        this.displayFolderResults();
-      } else if (this.format === 'json') {
-          logger.info(t("sizing.analysisStats", { stats: JSON.stringify(this.stats, null, 2) }));
-      }
-      
-      await this.generateHumanReadableReport();
-      
-      const endTime = Date.now();
-      logger.info(t("sizing.analysis_completed", { duration: ((endTime - startTime) / 1000).toFixed(2) }));
-      
-    } catch (error) {
-        logger.error(t("sizing.analysis_failed", { errorMessage: error.message }));
-        process.exit(1);
-    }
-  }
-
-  // Parse command line arguments without yargs
+  // Parse command line arguments without yargs
   parseArgs() {
     const args = process.argv.slice(2);
     const options = {
@@ -1335,7 +1299,7 @@ Options:
         
         const cliHelper = require('../utils/cli-helper');
         const pin = await cliHelper.promptPin(t('adminCli.enterPin'));
-        const isValid = await this.adminAuth.verifyPin(pin);
+        const isValid = await adminAuth.verifyPin(pin);
         
         if (!isValid) {
           console.log(t('adminCli.invalidPin'));
@@ -1377,7 +1341,11 @@ Options:
       this.generateSizeComparison();
       
       // Display results
-      this.displayFolderResults();
+      if (this.format === 'table') {
+        this.displayFolderResults();
+      } else if (this.format === 'json') {
+          logger.info(t("sizing.analysisStats", { stats: JSON.stringify(this.stats, null, 2) }));
+      }
       
       // Generate reports if requested
       await this.generateHumanReadableReport();

package/main/i18ntk-usage.js

@@ -61,6 +61,10 @@ async function getConfig() {
   return await getUnifiedConfig('usage');
 }
 
+function toBool(v) {
+  return v === true || v === 'true' || v === '1';
+}
+
 class I18nUsageAnalyzer {
   constructor(config = {}) {
     this.config = config;
@@ -88,6 +92,7 @@ class I18nUsageAnalyzer {
     this.deadKeys = new Map();
     this.cleanupMode = false;
     this.dryRunDelete = false;
+    this._sourceCommentsSet = null;
     
     // Use global translation function
     this.rl = null;
@@ -383,10 +388,10 @@ class I18nUsageAnalyzer {
       console.log('🔍 Debug mode enabled');
     }
     
-    if (args.cleanup) {
+    if (toBool(args.cleanup)) {
       this.cleanupMode = true;
     }
-    if (args.dryRunDelete) {
+    if (toBool(args.dryRunDelete)) {
       this.dryRunDelete = true;
     }
     
@@ -533,9 +538,6 @@ class I18nUsageAnalyzer {
       // Load available translation keys first
       await this.loadAvailableKeys();
       
-      // NEW: Detect framework patterns before analysis
-      await this.detectFrameworkPatterns();
-      
       // Perform usage analysis with enhanced features
       await this.analyzeUsage();
       
@@ -614,6 +616,7 @@ class I18nUsageAnalyzer {
       }
       
       if (this.cleanupMode) {
+        this._buildSourceCommentsSet();
         const deadKeys = this.findDeadKeys();
         console.log('\n' + t('usage.deadKeysDetectionTitle'));
         console.log(t('usage.deadKeysCount', { count: deadKeys.length }));
@@ -1242,11 +1245,13 @@ Analysis Features (v1.10.1):
     return false;
   }
 
-  _keyInSourceComments(key) {
+  _buildSourceCommentsSet() {
+    if (this._sourceCommentsSet !== null) return;
+    this._sourceCommentsSet = new Set();
+
     const commentPatterns = [
       /\/\/[^\n]*/g,
-      /\/\*[\s\S]*?\*\//g,
-      /\/\*\*[\s\S]*?\*\//g
+      /\/\*[\s\S]*?\*\//g
     ];
 
     try {
@@ -1262,13 +1267,22 @@ Analysis Features (v1.10.1):
           const comments = content.match(pattern);
           if (comments) {
             for (const comment of comments) {
-              if (comment.includes(key)) {
-                return true;
-              }
+              this._sourceCommentsSet.add(comment);
             }
           }
         }
       }
+    } catch (e) {
+      this._sourceCommentsSet = new Set();
+    }
+  }
+
+  _keyInSourceComments(key) {
+    try {
+      if (!this._sourceCommentsSet || this._sourceCommentsSet.size === 0) return false;
+      for (const comment of this._sourceCommentsSet) {
+        if (comment.includes(key)) return true;
+      }
     } catch (e) {
       // Silently fail - comment detection is best-effort
     }
@@ -1936,9 +1950,6 @@ Analysis Features (v1.10.1):
       // Close readline interface to prevent hanging
       this.closeReadline();
       
-      // Return instead of force exit to allow proper cleanup
-      return;
-      
       return {
         success: true,
         stats: {
@@ -2013,40 +2024,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = I18nUsageAnalyzer;
-
-// Run if called directly
-if (require.main === module) {
-  async function main() {
-    try {
-      const cliArgs = parseCommonArgs(process.argv.slice(2));
-
-      if (cliArgs.help) {
-        displayHelp('usage');
-        process.exit(0);
-      }
-
-      // Let run() handle full initialization to avoid duplicate setup output
-      const analyzer = new I18nUsageAnalyzer();
-      await analyzer.run();
-    } catch (error) {
-      console.error('Error:', error.message);
-      process.exit(1);
-    }
-  }
-
-  // Check if we're being called from the menu system (stdin has data)
-  const hasStdinData = !process.stdin.isTTY;
-
-  if (hasStdinData) {
-    // When called from menu, consume stdin data and run with defaults
-    process.stdin.resume();
-    process.stdin.on('data', () => {});
-    process.stdin.on('end', () => {
-      main();
-    });
-  } else {
-    // Normal direct execution
-    main();
-  }
-}
+module.exports = I18nUsageAnalyzer;

package/main/i18ntk-validate.js

@@ -164,12 +164,13 @@ class I18nValidator {
       const args = process.argv.slice(2);
       args.forEach(arg => {
         const sanitizedArg = SecurityUtils.sanitizeInput(arg);
-        if (sanitizedArg.startsWith('--') && !sanitizedArg.includes('=')) {
+        if (sanitizedArg.startsWith('--enforce-key-style')) {
+          const val = arg.split('=')[1];
+          baseArgs.enforceKeyStyle = val === undefined ? true : val !== 'false';
+        } else if (sanitizedArg.startsWith('--') && !sanitizedArg.includes('=')) {
           const key = sanitizedArg.substring(2);
           if (['en', 'de', 'es', 'fr', 'ru', 'ja', 'zh'].includes(key)) {
             baseArgs.uiLanguage = key;
-          } else if (key === 'enforce-key-style') {
-            baseArgs.enforceKeyStyle = true;
           }
         }
       });
@@ -242,7 +243,7 @@ class I18nValidator {
       const files = items
         .filter(item => {
           return item.isFile() && item.name.endsWith('.json') && 
-                 !this.config.excludeFiles.includes(item.name);
+                 (!Array.isArray(this.config.excludeFiles) || !this.config.excludeFiles.includes(item.name));
         }).map(item => item.name);
       
       return files;
@@ -691,7 +692,8 @@ class I18nValidator {
     const violations = [];
     for (const key of allKeys) {
       const sanitizedKey = SecurityUtils.sanitizeInput(key);
-      if (!regex.test(sanitizedKey)) {
+      const testKey = keyStyle === 'flat' ? sanitizedKey.split('.').pop() : sanitizedKey;
+      if (!regex.test(testKey)) {
         violations.push({
           key: sanitizedKey,
           suggestedFix: this.suggestKeyFix(sanitizedKey, keyStyle),
@@ -729,7 +731,7 @@ class I18nValidator {
       case 'kebab-case':
         return segments.map(s => s.toLowerCase()).join('-');
       case 'flat':
-        return segments.map((s, i) => i === 0 ? s.toLowerCase() : s.charAt(0).toUpperCase() + s.slice(1).toLowerCase()).join('');
+        return segments.map(s => s.toLowerCase()).join('');
       default:
         return sanitizedKey;
     }
@@ -1054,6 +1056,7 @@ class I18nValidator {
     
     const args = this.parseArgs();
     
+    try {
     // Ensure config is always initialized
     if (!this.config) {
       this.config = {};
@@ -1071,6 +1074,7 @@ class I18nValidator {
       } else {
         await this.initialize();
       }
+      this.config.enforceKeyStyle = args.enforceKeyStyle !== undefined ? args.enforceKeyStyle : this.config.enforceKeyStyle;
       
       // Skip admin authentication when called from menu
       if (!fromMenu) {
@@ -1146,6 +1150,7 @@ class I18nValidator {
     );
     throw error;
   }
+  }
 }
 
 

package/package.json

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

package/runtime/index.js

@@ -139,7 +139,8 @@ function listJsonFilesRecursively(dir, baseDir = dir) {
   return results;
 }
 
-function loadKeyManifestFromDir(baseDir) {
+function loadKeyManifestFromDir(baseDir) {
+  if (!baseDir || typeof baseDir !== 'string') return new Map();
   const validatedBase = SecurityUtils.validatePath(baseDir, path.dirname(baseDir));
   const baseStat = SecurityUtils.safeStatSync(validatedBase, path.dirname(validatedBase));
   const baseRoot = baseStat && baseStat.isFile() ? path.dirname(validatedBase) : validatedBase;
@@ -288,11 +289,15 @@ function resolveKey(obj, key, sep = '.', runtimeState = null, lang = null) {
           const prefix = parts.slice(0, i).join(sep);
           const filePath = manifest.get(prefix);
           const loadedFileKey = `${lang}\0${filePath}`;
-          if (filePath && !runtimeState.loadedFiles.has(loadedFileKey)) {
-            loadFileLazy(runtimeState, filePath, lang);
-            runtimeState.loadedFiles.add(loadedFileKey);
-            const langData = runtimeState.cache.get(lang);
-            return resolveKey(langData, key, sep, runtimeState, lang);
+          if (filePath && !runtimeState.loadedFiles.has(loadedFileKey)) {
+            runtimeState.loadedFiles.add(loadedFileKey);
+            try {
+              loadFileLazy(runtimeState, filePath, lang);
+            } catch (_) {
+              // stale manifest entry — already marked as loaded to prevent retry
+            }
+            const langData = runtimeState.cache.get(lang);
+            return resolveKey(langData, key, sep, runtimeState, lang);
           }
         }
         if (!runtimeState.eagerLoadedLanguages.has(lang)) {
@@ -433,7 +438,8 @@ function refresh(lang) {
 
 function refreshForState(runtimeState, lang = runtimeState.language) {
   if (runtimeState.cache.has(lang)) runtimeState.cache.delete(lang);
-  if (runtimeState.eagerLoadedLanguages) runtimeState.eagerLoadedLanguages.delete(lang);
+  if (runtimeState.eagerLoadedLanguages) runtimeState.eagerLoadedLanguages.delete(lang);
+  if (runtimeState.keyManifest) runtimeState.keyManifest.delete(lang);
   if (runtimeState.loadedFiles) {
     for (const fileKey of Array.from(runtimeState.loadedFiles)) {
       if (fileKey.startsWith(`${lang}\0`)) runtimeState.loadedFiles.delete(fileKey);

package/utils/translate/protection.js

@@ -75,10 +75,15 @@ function parseContextString(context) {
     return { mode: 'before', words };
   }
 
-  const surroundedMatch = trimmed.match(/^surrounded:(.+),(.+)$/i);
-  if (surroundedMatch) {
-    const leftWords = surroundedMatch[1].split('|').map(w => w.trim()).filter(Boolean);
-    const rightWords = surroundedMatch[2].split('|').map(w => w.trim()).filter(Boolean);
+  const prefix = trimmed.substring(0, 'surrounded:'.length);
+  if (prefix.toLowerCase() === 'surrounded:') {
+    const rest = trimmed.substring('surrounded:'.length);
+    const idx = rest.indexOf(',');
+    if (idx === -1) return null;
+    const left = rest.slice(0, idx).trim();
+    const right = rest.slice(idx + 1).trim();
+    const leftWords = left.split('|').map(w => w.trim()).filter(Boolean);
+    const rightWords = right.split('|').map(w => w.trim()).filter(Boolean);
     if (leftWords.length === 0 || rightWords.length === 0) return null;
     return { mode: 'surrounded', left: leftWords, right: rightWords };
   }
@@ -243,7 +248,7 @@ function shouldPreserveWholeValue(keyPath, value, protection) {
   if (protection.keys.some(rule => keyMatchesRule(keyPath, rule))) return true;
   const valueText = String(value);
   return protection.values.includes(valueText) ||
-    (protection.normalizedTerms || []).some(rule => rule.value === valueText);
+    (protection.normalizedTerms || []).some(rule => rule.type === 'global' && rule.value === valueText);
 }
 
 function addReplacement(replacements, original) {
@@ -261,27 +266,27 @@ function shouldProtectInContext(value, rule, index, fullText) {
 
   if (context.mode === 'after') {
     const alternation = context.words.map(escapeRegExp).join('|');
-    const regex = new RegExp(`\\b(${alternation})\\s+$`, 'i');
+    const regex = new RegExp(`(^|[\\s\\p{P}])(${alternation})\\s+$`, 'iu');
     return regex.test(before);
   }
 
   if (context.mode === 'before') {
     const alternation = context.words.map(escapeRegExp).join('|');
-    const regex = new RegExp(`^\\s+(${alternation})\\b`, 'i');
+    const regex = new RegExp(`^\\s+(${alternation})([\\s\\p{P}]|$)`, 'iu');
     return regex.test(after);
   }
 
   if (context.mode === 'standalone') {
-    const isBoundaryBefore = before === '' || /\s$/.test(before);
-    const isBoundaryAfter = after === '' || /^[\s.,!?;:]/.test(after);
+    const isBoundaryBefore = before === '' || /(?:\s|\(|\[|\{|"|'|\-|–|—|。|、|」)$/.test(before);
+    const isBoundaryAfter = after === '' || /^[\s.,!?;:)\]}<>"'\-–—。、」]/.test(after);
     return isBoundaryBefore && isBoundaryAfter;
   }
 
   if (context.mode === 'surrounded') {
     const leftAlternation = context.left.map(escapeRegExp).join('|');
     const rightAlternation = context.right.map(escapeRegExp).join('|');
-    const leftRegex = new RegExp(`\\b(${leftAlternation})\\s+$`, 'i');
-    const rightRegex = new RegExp(`^\\s+(${rightAlternation})\\b`, 'i');
+    const leftRegex = new RegExp(`(^|[\\s\\p{P}])(${leftAlternation})\\s+$`, 'iu');
+    const rightRegex = new RegExp(`^\\s+(${rightAlternation})([\\s\\p{P}]|$)`, 'iu');
     return leftRegex.test(before) && rightRegex.test(after);
   }
 
@@ -361,7 +366,7 @@ function hasProtectionRules(protection) {
     protection &&
     (
       (protection.normalizedTerms && protection.normalizedTerms.length) ||
-      protection.terms.length ||
+      (protection.terms && protection.terms.length) ||
       protection.keys.length ||
       protection.values.length ||
       protection.patterns.length

package/utils/watch-locales.js

@@ -99,7 +99,7 @@ function watchDirectory(dir, emitter, watchers, options = {}) {
     return;
   }
 
-  watchers.push({ watcher, path: dir });
+  watchers.push({ watcher, path: dir, debounceTimers });
   watchState.count++;
 
   try {
@@ -126,6 +126,11 @@ function watchLocales(dirs, onChange, options = {}) {
   if (typeof onChange === 'function') {
     emitter.on('change', onChange);
     emitter.on('add', onChange);
+    emitter.on('unlink', onChange);
+  } else if (typeof onChange === 'object' && onChange !== null && typeof onChange.onChange === 'function') {
+    emitter.on('change', onChange.onChange);
+    emitter.on('add', onChange.onChange);
+    emitter.on('unlink', onChange.onChange);
   }
 
   const {
@@ -160,6 +165,12 @@ function watchLocales(dirs, onChange, options = {}) {
 
   const stop = () => {
     for (const entry of watchers) {
+      if (entry.debounceTimers) {
+        for (const timer of entry.debounceTimers.values()) {
+          clearTimeout(timer);
+        }
+        entry.debounceTimers.clear();
+      }
       try { entry.watcher.close(); } catch (_) { /* ignore */ }
     }
     watchers.length = 0;