i18ntk 4.5.4 → 4.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +45 -2
- package/README.md +124 -536
- package/main/i18ntk-init.js +56 -25
- package/main/i18ntk-scanner.js +148 -29
- package/main/i18ntk-translate.js +6 -3
- package/main/manage/commands/ScannerCommand.js +145 -28
- package/main/manage/services/FrameworkDetectionService.js +67 -9
- package/main/manage/services/InitService.js +56 -25
- package/package.json +27 -43
- package/utils/config-helper.js +2 -2
- package/utils/framework-detector.js +317 -6
- package/utils/report-model.js +17 -4
- package/utils/usage-source.js +2 -1
- package/utils/validation-risk.js +22 -13
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# i18ntk v4.
|
|
1
|
+
# i18ntk v4.6.1
|
|
2
2
|
|
|
3
3
|
A zero-dependency internationalization toolkit for setup, scanning, analysis, validation, usage tracking, translation completion, automatic JSON locale translation, reporting, and runtime translation loading.
|
|
4
4
|
|
|
@@ -9,650 +9,238 @@ A zero-dependency internationalization toolkit for setup, scanning, analysis, va
|
|
|
9
9
|
[](https://nodejs.org)
|
|
10
10
|
[](https://www.npmjs.com/package/i18ntk)
|
|
11
11
|
[](LICENSE)
|
|
12
|
-
[](https://socket.dev/npm/package/i18ntk/overview/4.6.1)
|
|
13
13
|
|
|
14
|
-
[](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-workbench)
|
|
15
|
+
[](https://marketplace.visualstudio.com/items?itemName=VladNoskov.i18ntk-lens)
|
|
16
16
|
|
|
17
|
-
##
|
|
17
|
+
## Ecosystem
|
|
18
18
|
|
|
19
|
-
- i18ntk — CLI and runtime
|
|
20
|
-
- i18ntk Workbench —
|
|
21
|
-
- i18ntk Lens — inline hovers, CodeLens, and diagnostics
|
|
22
|
-
|
|
23
|
-
Use the CLI in CI, Workbench for project-level management, and Lens for day-to-day editor feedback.
|
|
19
|
+
- **i18ntk** — CLI toolkit and runtime (this package)
|
|
20
|
+
- **i18ntk Workbench** — VS Code dashboard, reports, and key management
|
|
21
|
+
- **i18ntk Lens** — inline hovers, CodeLens, and diagnostics
|
|
24
22
|
|
|
25
23
|
## Install
|
|
26
24
|
|
|
27
25
|
```bash
|
|
28
|
-
# global CLI use
|
|
29
26
|
npm install -g i18ntk
|
|
30
|
-
|
|
31
|
-
# local project use
|
|
32
|
-
npm install --save-dev i18ntk
|
|
33
|
-
|
|
34
|
-
# one-off execution
|
|
35
27
|
npx i18ntk --help
|
|
36
28
|
```
|
|
37
29
|
|
|
38
|
-
##
|
|
39
|
-
|
|
40
|
-
**What it does**
|
|
41
|
-
|
|
42
|
-
- Manages locale files from the command line.
|
|
43
|
-
- Finds missing, unused, risky, and inconsistent translation keys.
|
|
44
|
-
- Produces validation and summary reports.
|
|
45
|
-
- Supports framework-aware i18n workflows.
|
|
46
|
-
- Provides a lightweight runtime translation toolkit.
|
|
47
|
-
|
|
48
|
-
**What it does not do**
|
|
49
|
-
|
|
50
|
-
- It is not a translation management SaaS.
|
|
51
|
-
- It does not replace human translation review.
|
|
52
|
-
- It does not force you to replace i18next, react-i18next, vue-i18n, or another runtime.
|
|
53
|
-
|
|
54
|
-
**Why not i18next?**
|
|
55
|
-
|
|
56
|
-
i18next is mainly a runtime internationalization library. i18ntk is mainly workflow tooling around translation files. They can work together: i18next handles runtime translation, while i18ntk handles setup, scanning, validation, reporting, and maintenance.
|
|
57
|
-
|
|
58
|
-
| Need | i18ntk | i18next |
|
|
59
|
-
| ------------------------- | ------------- | ---------------- |
|
|
60
|
-
| Runtime translation | Basic toolkit | Mature runtime |
|
|
61
|
-
| Locale file scanning | Yes | No |
|
|
62
|
-
| Missing key detection | Yes | No |
|
|
63
|
-
| Unused key detection | Yes | No |
|
|
64
|
-
| Validation reports | Yes | Limited |
|
|
65
|
-
| Auto-translation workflow | Yes | External tooling |
|
|
66
|
-
|
|
67
|
-
## What's New in 4.5.4
|
|
68
|
-
|
|
69
|
-
- **CLI RELIABILITY**: Direct and manager-routed commands now propagate runtime, validation, and report failures with non-zero exit codes and never print success after failure.
|
|
70
|
-
- **CI READY**: Commands skip prompts under `--no-prompt`, `CI=true`, or non-TTY stdin/stdout.
|
|
71
|
-
- **CLEAR FLAGS**: Added `--code-dir` / `--source-code-dir`, `--locales-dir` / `--i18n-dir`, and `--source-locale` while preserving legacy aliases.
|
|
72
|
-
- **COMMAND FIXES**: Fixed `i18ntk-analyze` setup guidance crash, `i18ntk-complete --help`, `i18ntk-summary` `NaN` averages, validation success/failure wording, and completion summary labels.
|
|
73
|
-
|
|
74
|
-
## What's New in 4.5.3
|
|
30
|
+
## What's New in 4.6.0
|
|
75
31
|
|
|
76
|
-
- **
|
|
32
|
+
- **25+ framework detections** — Rust, Remix, Gatsby, Astro, Qwik, SolidJS, Ember, React Native, Expo, Ionic added. All drawn from a single centralized detector.
|
|
33
|
+
- **Rust support** — Cargo.toml detection and `.rs` file scanning with fluent/gettext-rs framework patterns.
|
|
34
|
+
- **File extensions** — `.astro`, `.mdx`, `.mjs`, `.mts`, `.cjs`, `.cts`, `.rs` scanned across all tools.
|
|
35
|
+
- **ICU/Fluent placeholder support** — Fluent `$variable` and ICU `{var, plural, ...}` patterns detected.
|
|
36
|
+
- **JSX component detection** — `<Trans>`, `<FormattedMessage>`, `<Translate>` components recognized.
|
|
37
|
+
- **Health score fix** — No more negative or misleadingly low scores.
|
|
38
|
+
- **Centralized architecture** — Framework data, extensions, excludes, and patterns live in one module consumed by all tools.
|
|
77
39
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
- The `complete` command now correctly inserts missing keys at the right nesting level when target locale files have namespace wrappers (e.g., `auth.json` containing `{ "auth": { ... } }`). Keys inside `auth.panel.sign_in` now go inside the `auth` wrapper, not at root level.
|
|
81
|
-
- Fixed `complete` command: missing keys now inserted inside namespace wrapper when file has top-level key matching filename (e.g., auth.json with `{ "auth": … }`).
|
|
82
|
-
- Fixed `translate --output-dir`: output now placed in `<outputDir>/<targetLang>/<filename>`, preventing language overwrites.
|
|
83
|
-
- Enhanced `scanner` and `report-model` to filter out JS built-in type names (e.g., Promise, Boolean) and code expressions (e.g., `&&`, `${…}`) from hardcoded text detection.
|
|
84
|
-
|
|
85
|
-
## What's New in 4.5.1
|
|
86
|
-
|
|
87
|
-
- **CORRECT COMPLETENESS**: Validation now shows accurate completion percentages vs source locale (e.g., 33% instead of misleading 100%).
|
|
88
|
-
- **NO MORE PARENT KEYS**: `getAllKeys()` no longer reports parent namespace objects (`footer`) as missing keys alongside their leaf children (`footer.copyright`).
|
|
89
|
-
- **DOCTOR SMARTER**: No longer flags unconfigured languages (`de`, `ru`) as issues. Auto-detects available languages from the i18n directory structure.
|
|
90
|
-
- **SCANNER FIXED**: Scanner now correctly scans `src/` directory for hardcoded text, not `locales/`.
|
|
91
|
-
- **RUNTIME ALIASES**: `initRuntime()` now supports `localeDir`/`targetLocale`/`sourceLocale` as aliases for `baseDir`/`language`/`fallbackLanguage`.
|
|
92
|
-
|
|
93
|
-
## What's New in 4.5.0
|
|
94
|
-
|
|
95
|
-
- **PROTOTYPE POLLUTION HARDENED**: Three layers of defense added — `readJsonSafe()` now recursively strips `__proto__`, `constructor`, and `prototype` keys from all parsed JSON; `deepMerge()` in the runtime blocks these keys during locale merging; `mergeWithDefaults()` in settings-manager filters them from user settings.
|
|
96
|
-
- **BACKUP FIXED**: All backup operations (create, restore, list, verify, cleanup) now work. A duplicate `sourceDir` declaration that caused a SyntaxError at module load has been removed. Corrupt backup files are now handled gracefully with descriptive error messages.
|
|
97
|
-
- **COMPLETE COMMAND FIXED**: `i18ntk-complete` no longer crashes with `getUnifiedConfig is not defined`. The missing config-helper import has been added.
|
|
98
|
-
- **MALFORMED JSON HANDLING**: Report generation now gracefully skips malformed JSON files with a warning instead of aborting the entire report.
|
|
99
|
-
- **NULL SAFETY**: `stripBOMAndComments()` in i18n-helper now handles null/undefined inputs without throwing.
|
|
100
|
-
- **ERROR HANDLING HARDENED**: Lazy-load failures in runtime now log to console when `I18NTK_DEBUG` is set. Settings save errors are now re-thrown instead of silently swallowed. Legacy config migration has proper error handling.
|
|
101
|
-
|
|
102
|
-
See [CHANGELOG.md](./CHANGELOG.md) for more release details.
|
|
40
|
+
[Full changelog →](./CHANGELOG.md)
|
|
103
41
|
|
|
104
42
|
## Quick Start
|
|
105
43
|
|
|
106
|
-
Initialize a project:
|
|
107
|
-
|
|
108
|
-
```bash
|
|
109
|
-
i18ntk
|
|
110
|
-
# or with explicit command
|
|
111
|
-
i18ntk --command=init
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
Run common checks:
|
|
115
|
-
|
|
116
|
-
```bash
|
|
117
|
-
i18ntk --command=analyze
|
|
118
|
-
i18ntk --command=validate
|
|
119
|
-
i18ntk --command=usage
|
|
120
|
-
i18ntk report --json
|
|
121
|
-
i18ntk --command=sizing
|
|
122
|
-
i18ntk --command=summary
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
Complete or fix translation files:
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
i18ntk --command=complete
|
|
129
|
-
i18ntk-fixer --help
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
Auto-translate locale JSON:
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
i18ntk --command=translate
|
|
136
|
-
# or
|
|
137
|
-
i18ntk-translate locales/en/common.json de --report-stdout
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
The full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).
|
|
141
|
-
|
|
142
|
-
## Main Commands
|
|
143
|
-
|
|
144
|
-
Primary CLI:
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
i18ntk
|
|
148
|
-
i18ntk --help
|
|
149
|
-
i18ntk --command=init
|
|
150
|
-
i18ntk --command=analyze
|
|
151
|
-
i18ntk --command=validate
|
|
152
|
-
i18ntk --command=usage
|
|
153
|
-
i18ntk report --json --markdown --html --out ./i18ntk-reports
|
|
154
|
-
i18ntk --command=scanner
|
|
155
|
-
i18ntk --command=sizing
|
|
156
|
-
i18ntk --command=complete
|
|
157
|
-
i18ntk --command=translate
|
|
158
|
-
i18ntk --command=summary
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
Standalone executables:
|
|
162
|
-
|
|
163
44
|
```bash
|
|
164
|
-
i18ntk
|
|
165
|
-
i18ntk
|
|
166
|
-
i18ntk
|
|
167
|
-
i18ntk
|
|
168
|
-
i18ntk
|
|
169
|
-
i18ntk
|
|
170
|
-
i18ntk-
|
|
171
|
-
i18ntk
|
|
172
|
-
i18ntk-summary
|
|
173
|
-
i18ntk-doctor
|
|
174
|
-
i18ntk-fixer
|
|
175
|
-
i18ntk-backup
|
|
176
|
-
i18ntk-translate
|
|
45
|
+
i18ntk # interactive menu
|
|
46
|
+
i18ntk --command=analyze # coverage report
|
|
47
|
+
i18ntk --command=validate # quality checks
|
|
48
|
+
i18ntk --command=usage # key usage tracking
|
|
49
|
+
i18ntk report --json --out ./reports # full report
|
|
50
|
+
i18ntk --command=complete # fill missing keys
|
|
51
|
+
i18ntk --command=translate # auto-translate
|
|
52
|
+
i18ntk --command=summary # status overview
|
|
177
53
|
```
|
|
178
54
|
|
|
179
|
-
|
|
55
|
+
See [docs/getting-started.md](./docs/getting-started.md) for the full onboarding guide.
|
|
180
56
|
|
|
181
57
|
## Command Reference
|
|
182
58
|
|
|
183
|
-
| Command
|
|
184
|
-
|
|
|
185
|
-
| `i18ntk`
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
59
|
+
| Command | Purpose | Output |
|
|
60
|
+
| ----------- | ------------------------------------------ | ----------------------------- |
|
|
61
|
+
| `i18ntk` | Interactive management menu | — |
|
|
62
|
+
| `init` | Setup locale folders and target files | Locale JSON, `.i18ntk-config` |
|
|
63
|
+
| `analyze` | Translation coverage comparison | Reports |
|
|
64
|
+
| `validate` | Structure, quality, and risk validation | Summary report |
|
|
65
|
+
| `usage` | Map keys to source, find dead/missing keys | Usage report |
|
|
66
|
+
| `report` | Stable schema report (JSON/MD/HTML) | stdout or file output |
|
|
67
|
+
| `scanner` | Detect hardcoded text in source files | Scanner report |
|
|
68
|
+
| `complete` | Fill missing keys in target files | Target locale JSON |
|
|
69
|
+
| `translate` | Auto-translate via provider AI | Target locale JSON |
|
|
70
|
+
| `sizing` | Expansion risk and layout analysis | Sizing report |
|
|
71
|
+
| `summary` | Project translation status overview | Console output |
|
|
72
|
+
| `fixer` | Fix placeholders and markers | Locale JSON |
|
|
73
|
+
| `backup` | Create/verify/restore locale backups | Backup archives |
|
|
74
|
+
|
|
75
|
+
Each is available as `i18ntk --command=<name>` or standalone `i18ntk-<name>`.
|
|
198
76
|
|
|
199
77
|
## Common Options
|
|
200
78
|
|
|
201
|
-
Many commands support:
|
|
202
|
-
|
|
203
|
-
- `--code-dir <path>` or `--source-code-dir <path>` for application source files
|
|
204
|
-
- `--locales-dir <path>` or `--i18n-dir <path>` for locale files
|
|
205
|
-
- `--output-dir <path>`
|
|
206
|
-
- `--source-locale <code>`
|
|
207
|
-
- `--ui-language <code>`
|
|
208
|
-
- `--no-prompt`
|
|
209
|
-
- `--help`
|
|
210
|
-
|
|
211
|
-
Legacy `--source-dir` and `--source-language` remain supported. For scanner-style commands, `--source-dir` means source code. For locale-only commands, prefer `--locales-dir` to avoid ambiguity.
|
|
212
|
-
|
|
213
|
-
Command-specific tools add their own flags such as `--dry-run`, `--output-report`, `--cleanup`, `--predict-expansion`, or Auto Translate provider options.
|
|
214
|
-
|
|
215
|
-
Example:
|
|
216
|
-
|
|
217
|
-
```bash
|
|
218
|
-
i18ntk --command=analyze --code-dir=./src --locales-dir=./locales --source-locale=en --output-dir=./i18ntk-reports
|
|
219
79
|
```
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
# choose "Auto Translate"
|
|
80
|
+
--code-dir <path> Source code directory
|
|
81
|
+
--locales-dir <path> Locale files directory
|
|
82
|
+
--output-dir <path> Report output directory
|
|
83
|
+
--source-locale <code> Source language code (e.g. en)
|
|
84
|
+
--framework <name> Override framework detection
|
|
85
|
+
--no-prompt Skip interactive prompts
|
|
86
|
+
--help Show help
|
|
228
87
|
```
|
|
229
88
|
|
|
230
|
-
|
|
89
|
+
## Auto Translate
|
|
231
90
|
|
|
232
91
|
```bash
|
|
233
92
|
i18ntk-translate locales/en/common.json de
|
|
234
|
-
i18ntk-translate locales/en/common.json fr --dry-run --
|
|
235
|
-
i18ntk-translate locales/en es --source-dir locales/en --files "*.json" --no-confirm --preserve-placeholders
|
|
93
|
+
i18ntk-translate locales/en/common.json fr --dry-run --preserve-placeholders
|
|
236
94
|
```
|
|
237
95
|
|
|
238
|
-
|
|
96
|
+
**Providers:** Google (default), DeepL, LibreTranslate
|
|
239
97
|
|
|
240
98
|
```bash
|
|
241
|
-
export DEEPL_API_KEY="your-
|
|
242
|
-
i18ntk-translate locales/en/common.json de --provider deepl --no-confirm
|
|
243
|
-
|
|
244
|
-
export LIBRETRANSLATE_URL="https://libretranslate.com/translate"
|
|
245
|
-
export LIBRETRANSLATE_API_KEY="optional-api-key"
|
|
246
|
-
i18ntk-translate locales/en/common.json es --provider libretranslate --no-confirm --preserve-placeholders
|
|
99
|
+
export DEEPL_API_KEY="your-key"
|
|
100
|
+
i18ntk-translate locales/en/common.json de --provider deepl --no-confirm
|
|
247
101
|
```
|
|
248
102
|
|
|
249
|
-
`
|
|
250
|
-
|
|
251
|
-
Provider 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.
|
|
252
|
-
|
|
253
|
-
The manager flow asks for:
|
|
254
|
-
|
|
255
|
-
- source locale directory, either the folder with JSON files or a locale root such as `./locales`
|
|
256
|
-
- source language code
|
|
257
|
-
- one or more target languages, or `all`
|
|
258
|
-
- one JSON file or all JSON files in the source directory
|
|
259
|
-
|
|
260
|
-
If you select a locale root such as `./locales` and choose source language `en`, the manager automatically uses `./locales/en` when that folder contains the source JSON files.
|
|
261
|
-
|
|
262
|
-
Before writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:
|
|
263
|
-
|
|
264
|
-
```text
|
|
265
|
-
locales/en/common.json
|
|
266
|
-
locales/de/common.json
|
|
267
|
-
locales/fr/common.json
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
Auto Translate is target-aware by default. When a target file already exists, it keeps translated target values and only sends values that are missing, empty, marked as untranslated, still identical to the source, likely still English, or visibly corrupt from encoding damage such as `?????`, replacement characters, or common mojibake. Use `--translate-all` when you intentionally want to re-translate every source string.
|
|
271
|
-
|
|
272
|
-
### Placeholder Handling
|
|
273
|
-
|
|
274
|
-
Auto Translate detects common placeholders such as:
|
|
103
|
+
**Placeholder-aware translation** detects `{name}`, `{{count}}`, `%s`, `:id`, `${value}`, `$t(key)`, and ICU pattern syntax. The default mode is `--only-missing` — existing translations are preserved.
|
|
275
104
|
|
|
276
|
-
|
|
277
|
-
- `{{count}}`
|
|
278
|
-
- `%s`
|
|
279
|
-
- `%d`
|
|
280
|
-
- `:id`
|
|
281
|
-
- `%{name}`
|
|
282
|
-
- `${value}`
|
|
283
|
-
- `{count, plural, one {# item} other {# items}}`
|
|
284
|
-
- `$t(common.save)`
|
|
285
|
-
- `%(total).2f`
|
|
286
|
-
|
|
287
|
-
Useful flags:
|
|
288
|
-
|
|
289
|
-
- `--preserve-placeholders`: translate text around placeholders and reinsert original tokens
|
|
290
|
-
- `--skip-placeholders`: copy placeholder-bearing strings unchanged
|
|
291
|
-
- `--send-placeholders`: send placeholder-bearing strings through translation after masking
|
|
292
|
-
- `--custom-regex <regex>`: add project-specific placeholder detection
|
|
293
|
-
- `--only-missing`: keep existing translated target values and translate only missing/source-copy/likely English values (default)
|
|
294
|
-
- `--translate-all`: re-translate every source string
|
|
295
|
-
|
|
296
|
-
Progress output is stage-aware for large files. Normal keys are reported as `Translating strings`, while preserve-mode placeholder work is reported as `Translating placeholder-safe text segments`; each progress update includes the current key path when available.
|
|
297
|
-
|
|
298
|
-
### Protected Terms and Keys
|
|
299
|
-
|
|
300
|
-
Auto Translate can create and use a project-local protection file:
|
|
301
|
-
|
|
302
|
-
```bash
|
|
303
|
-
i18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
Example `i18ntk-auto-translate.json`:
|
|
105
|
+
Protected terms and keys via `i18ntk-auto-translate.json`:
|
|
307
106
|
|
|
308
107
|
```json
|
|
309
108
|
{
|
|
310
109
|
"version": 1,
|
|
311
|
-
"terms": [
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
{ "value": "OK", "context": "after:Click|Press|Tap" },
|
|
315
|
-
{ "value": "API", "context": "standalone" }
|
|
316
|
-
],
|
|
317
|
-
"keys": ["app.brandName", "legal.companyName", "product.*.symbol"],
|
|
318
|
-
"values": ["BrandName Ltd", "support@example.com"],
|
|
110
|
+
"terms": ["BrandName", "PRODUCT_CODE"],
|
|
111
|
+
"keys": ["app.brandName", "product.*.symbol"],
|
|
112
|
+
"values": ["BrandName Ltd"],
|
|
319
113
|
"patterns": ["[A-Z]{2,}-\\d+"]
|
|
320
114
|
}
|
|
321
115
|
```
|
|
322
116
|
|
|
323
|
-
|
|
324
|
-
- **Plain strings**: masked everywhere (backward compatible).
|
|
325
|
-
- **Context objects**: masked only in specific contexts (`after:word`, `before:word`, `standalone`, `surrounded:left,right`).
|
|
326
|
-
- `keys` are exact key paths or `*` wildcard paths copied unchanged.
|
|
327
|
-
- `values` are exact source values copied unchanged.
|
|
328
|
-
- `patterns` are JavaScript regex strings for advanced protected substrings.
|
|
329
|
-
|
|
330
|
-
Useful flags:
|
|
331
|
-
|
|
332
|
-
- `--protection-file <path>`
|
|
333
|
-
- `--create-protection-file`
|
|
334
|
-
- `--no-protection`
|
|
335
|
-
|
|
336
|
-
Open Settings and choose `Auto Translate` to edit defaults for placeholder mode, translate-only-needed mode, concurrency, batch size, retry settings, report output, BOM output, protection file path, first-run setup prompt, and update prompt.
|
|
337
|
-
|
|
338
|
-
See [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.
|
|
117
|
+
[Auto Translate guide →](./docs/auto-translate.md)
|
|
339
118
|
|
|
340
|
-
##
|
|
341
|
-
|
|
342
|
-
Validation checks locale structure, completeness, placeholders, and content risks.
|
|
343
|
-
|
|
344
|
-
Validation warning types are specific:
|
|
345
|
-
|
|
346
|
-
- `Potential risky content`: URL, email address, or secret-like value
|
|
347
|
-
- `Possible untranslated English content`: target-language value appears to contain too much English
|
|
348
|
-
|
|
349
|
-
English-content warnings include:
|
|
350
|
-
|
|
351
|
-
- detected English percentage
|
|
352
|
-
- configured threshold
|
|
353
|
-
- matched word count
|
|
354
|
-
- sample matched words
|
|
119
|
+
## Configuration
|
|
355
120
|
|
|
356
|
-
|
|
121
|
+
Example `.i18ntk-config`:
|
|
357
122
|
|
|
358
123
|
```json
|
|
359
124
|
{
|
|
125
|
+
"version": "4.6.1",
|
|
126
|
+
"sourceDir": "./locales",
|
|
127
|
+
"i18nDir": "./locales",
|
|
128
|
+
"sourceLanguage": "en",
|
|
129
|
+
"defaultLanguages": ["en", "de", "es", "fr", "ru"],
|
|
130
|
+
"keyStyle": "dot.notation",
|
|
360
131
|
"englishContentThresholdPercent": 10,
|
|
361
|
-
"allowedEnglishTerms": ["BrandName",
|
|
132
|
+
"allowedEnglishTerms": ["BrandName"],
|
|
133
|
+
"autoTranslate": {
|
|
134
|
+
"placeholderMode": "preserve",
|
|
135
|
+
"concurrency": 12,
|
|
136
|
+
"onlyMissingOrEnglish": true
|
|
137
|
+
},
|
|
138
|
+
"extensions": {
|
|
139
|
+
"workbench": { "localeDirectory": "./locales", "sourceLocale": "en" },
|
|
140
|
+
"lens": { "localeDirectory": "./locales", "sourceLocale": "en", "keyFormats": ["dot", "snake"] }
|
|
141
|
+
}
|
|
362
142
|
}
|
|
363
143
|
```
|
|
364
144
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.
|
|
368
|
-
|
|
369
|
-
```bash
|
|
370
|
-
i18ntk-sizing --locales-dir ./locales --format table
|
|
371
|
-
i18ntk-sizing --locales-dir ./locales --detailed --output-dir ./i18ntk-reports
|
|
372
|
-
```
|
|
373
|
-
|
|
374
|
-
Use `--detailed` to print per-file rows in the terminal.
|
|
145
|
+
[Configuration reference →](./docs/api/CONFIGURATION.md)
|
|
375
146
|
|
|
376
|
-
|
|
147
|
+
## Scanner
|
|
377
148
|
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
```bash
|
|
381
|
-
i18ntk-sizing --locales-dir ./locales --predict-expansion --output-report
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
Expansion ratios are classified into risk tiers:
|
|
385
|
-
|
|
386
|
-
- **Safe** (<30% expansion): no UI impact expected
|
|
387
|
-
- **Warning** (30–50%): may overflow in tight layouts — test on target languages
|
|
388
|
-
- **Critical** (>50%): high risk of truncation — review UI element sizing
|
|
389
|
-
|
|
390
|
-
The 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.
|
|
391
|
-
|
|
392
|
-
## Scanner: Multi-Language Detection (New in 4.0.0)
|
|
393
|
-
|
|
394
|
-
`i18ntk-scanner` now supports detecting hardcoded text in multiple source languages beyond English:
|
|
149
|
+
Detects hardcoded text in 12+ languages with language-specific character ranges and stopword filtering. Framework-specific patterns for React, Vue, Angular, Svelte, Astro, Django, Flask, Python, Rust, Go, and more.
|
|
395
150
|
|
|
396
151
|
```bash
|
|
397
152
|
i18ntk-scanner --code-dir ./src --source-locale de
|
|
398
153
|
i18ntk-scanner --code-dir ./src --source-locale ja --output-report
|
|
399
154
|
```
|
|
400
155
|
|
|
401
|
-
|
|
156
|
+
## Usage Analysis
|
|
402
157
|
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
`i18ntk-usage` can identify translation keys that are defined but never referenced in source code:
|
|
158
|
+
Tracks key references, detects dead keys with confidence scores, resolves dynamic patterns (templates, arrays, object maps), and recommends namespace alignment.
|
|
406
159
|
|
|
407
160
|
```bash
|
|
408
|
-
i18ntk-usage --code-dir ./src --locales-dir ./locales --cleanup
|
|
409
161
|
i18ntk-usage --code-dir ./src --locales-dir ./locales --cleanup --dry-run-delete
|
|
410
162
|
```
|
|
411
163
|
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
- Unresolved dynamic key patterns (e.g., ``t(`prefix.${dynamic}`)``) — lower score and listed in the usage report; simple consts, bounded arrays, object maps, and ternaries are expanded to exact keys where possible
|
|
415
|
-
- Key appears in source code comments or JSDoc — medium score
|
|
416
|
-
- Parent file recently modified (<30 days) — medium score
|
|
417
|
-
- No references found anywhere — high score (>0.8)
|
|
418
|
-
|
|
419
|
-
The `--dry-run-delete` flag writes a `.dead-keys.json` report for review before any destructive action.
|
|
420
|
-
|
|
421
|
-
## Validator: Key Naming Conventions (New in 4.0.0)
|
|
422
|
-
|
|
423
|
-
Enforce consistent translation key naming across your project:
|
|
424
|
-
|
|
425
|
-
```bash
|
|
426
|
-
i18ntk-validate --enforce-key-style
|
|
427
|
-
```
|
|
428
|
-
|
|
429
|
-
Configure the expected style in `.i18ntk-config`:
|
|
430
|
-
|
|
431
|
-
```json
|
|
432
|
-
{
|
|
433
|
-
"keyStyle": "dot.notation"
|
|
434
|
-
}
|
|
435
|
-
```
|
|
436
|
-
|
|
437
|
-
Supported styles: `dot.notation`, `snake_case`, `camelCase`, `kebab-case`, `flat`. Violations are reported as warnings with suggested canonical forms.
|
|
438
|
-
|
|
439
|
-
## Watch: Hot Reload (New in 4.0.0)
|
|
440
|
-
|
|
441
|
-
`utils/watch-locales.js` now provides debounced file watching with EventEmitter support:
|
|
442
|
-
|
|
443
|
-
```js
|
|
444
|
-
const watchLocales = require('i18ntk/utils/watch-locales');
|
|
445
|
-
const watcher = watchLocales('./locales');
|
|
446
|
-
|
|
447
|
-
watcher.on('change', (filePath) => {
|
|
448
|
-
console.log('Locale changed:', filePath);
|
|
449
|
-
});
|
|
450
|
-
|
|
451
|
-
watcher.on('add', (filePath) => {
|
|
452
|
-
console.log('Locale added:', filePath);
|
|
453
|
-
});
|
|
454
|
-
|
|
455
|
-
// Later:
|
|
456
|
-
watcher.stop();
|
|
457
|
-
```
|
|
458
|
-
|
|
459
|
-
Features: 300ms debounce (configurable), SHA-256 hash tracking to skip no-change saves, and a maximum of 50 watched directories.
|
|
460
|
-
|
|
461
|
-
### Migration
|
|
462
|
-
|
|
463
|
-
The `watchLocales` return value gained EventEmitter methods in v4.0.0. Existing stop-function usage still works:
|
|
464
|
-
|
|
465
|
-
```js
|
|
466
|
-
const stop = watchLocales('./locales', onChange);
|
|
467
|
-
```
|
|
468
|
-
|
|
469
|
-
Can be updated to:
|
|
470
|
-
|
|
471
|
-
```js
|
|
472
|
-
const watcher = watchLocales('./locales');
|
|
473
|
-
watcher.on('change', onChange);
|
|
474
|
-
watcher.stop();
|
|
475
|
-
```
|
|
476
|
-
|
|
477
|
-
Passing a callback as the second argument is still supported — it auto-subscribes to `change` and `add` events.
|
|
478
|
-
|
|
479
|
-
## Backup: Incremental Mode (New in 4.0.0)
|
|
480
|
-
|
|
481
|
-
Create differential backups that only include changed files:
|
|
482
|
-
|
|
483
|
-
```bash
|
|
484
|
-
i18ntk-backup create ./locales --incremental
|
|
485
|
-
```
|
|
486
|
-
|
|
487
|
-
Incremental 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.
|
|
488
|
-
|
|
489
|
-
## Runtime: Lazy Loading (New in 4.0.0)
|
|
490
|
-
|
|
491
|
-
Reduce memory usage by deferring locale file loads until first key access:
|
|
492
|
-
|
|
493
|
-
```js
|
|
494
|
-
const runtime = require('i18ntk/runtime');
|
|
495
|
-
|
|
496
|
-
const i18n = runtime.initRuntime({
|
|
497
|
-
baseDir: './locales',
|
|
498
|
-
language: 'en',
|
|
499
|
-
lazy: true,
|
|
500
|
-
});
|
|
501
|
-
|
|
502
|
-
console.log(i18n.t('common.hello')); // loads common.json on first access
|
|
503
|
-
```
|
|
504
|
-
|
|
505
|
-
When `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.
|
|
506
|
-
|
|
507
|
-
Production guidance:
|
|
508
|
-
|
|
509
|
-
- Prefer the object returned from `initRuntime()` instead of module-level `runtime.t()` in apps with multiple tenants, projects, or locale roots.
|
|
510
|
-
- Use `lazy: true` for large modular locale folders where lower steady-state memory matters more than a small first-key lookup cost.
|
|
511
|
-
- Use `preload: true` without `lazy` for small locale sets or latency-sensitive startup paths.
|
|
512
|
-
- Call `refresh(language)` after deploying or writing changed locale files so cached data and lazy manifests are rebuilt.
|
|
513
|
-
- Use per-call language overrides when rendering one-off alternate-language strings: `i18n.t('common.hello', {}, { language: 'de' })`.
|
|
514
|
-
- Use `translateBatch()` for small groups of labels and `clearCache()` / `getCacheInfo()` for cache maintenance and diagnostics.
|
|
515
|
-
- `i18ntk/runtime/enhanced` remains available for compatibility with existing async/encryption users, but new production integrations should start with `i18ntk/runtime`.
|
|
516
|
-
|
|
517
|
-
## Runtime API
|
|
518
|
-
|
|
519
|
-
Use `i18ntk/runtime` when an application needs to read locale JSON files at runtime.
|
|
164
|
+
## Runtime
|
|
520
165
|
|
|
521
166
|
```js
|
|
522
167
|
const runtime = require('i18ntk/runtime');
|
|
523
|
-
|
|
524
168
|
const i18n = runtime.initRuntime({
|
|
525
169
|
baseDir: './locales',
|
|
526
170
|
language: 'en',
|
|
527
171
|
fallbackLanguage: 'en',
|
|
528
|
-
keySeparator: '.',
|
|
529
|
-
preload: true,
|
|
530
172
|
});
|
|
531
173
|
|
|
532
174
|
console.log(i18n.t('common.hello'));
|
|
533
175
|
i18n.setLanguage('fr');
|
|
534
|
-
console.log(i18n.getLanguage());
|
|
535
176
|
console.log(i18n.getAvailableLanguages());
|
|
536
|
-
i18n.refresh('fr');
|
|
537
177
|
```
|
|
538
178
|
|
|
539
|
-
|
|
179
|
+
**Lazy loading** reduces memory on large locale folders:
|
|
540
180
|
|
|
541
181
|
```js
|
|
542
|
-
i18n.
|
|
543
|
-
i18n.translateBatch(['menu.home', 'menu.settings']);
|
|
544
|
-
i18n.clearCache('fr');
|
|
545
|
-
console.log(i18n.getCacheInfo());
|
|
182
|
+
const i18n = runtime.initRuntime({ baseDir: './locales', language: 'en', lazy: true });
|
|
546
183
|
```
|
|
547
184
|
|
|
548
|
-
|
|
185
|
+
**Per-call language overrides:**
|
|
549
186
|
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
187
|
+
```js
|
|
188
|
+
i18n.t('common.hello', {}, { language: 'de' });
|
|
189
|
+
```
|
|
553
190
|
|
|
554
|
-
|
|
191
|
+
**Batch translation:**
|
|
555
192
|
|
|
556
|
-
```
|
|
557
|
-
|
|
558
|
-
"version": "4.5.4",
|
|
559
|
-
"sourceDir": "./locales",
|
|
560
|
-
"i18nDir": "./locales",
|
|
561
|
-
"outputDir": "./i18ntk-reports",
|
|
562
|
-
"sourceLanguage": "en",
|
|
563
|
-
"defaultLanguages": ["en", "de", "es", "fr", "ru"],
|
|
564
|
-
"reports": {
|
|
565
|
-
"format": "markdown"
|
|
566
|
-
},
|
|
567
|
-
"englishContentThresholdPercent": 10,
|
|
568
|
-
"allowedEnglishTerms": ["BrandName", "PRODUCT_CODE"],
|
|
569
|
-
"autoTranslate": {
|
|
570
|
-
"placeholderMode": "preserve",
|
|
571
|
-
"concurrency": 12,
|
|
572
|
-
"batchSize": 100,
|
|
573
|
-
"progressInterval": 25,
|
|
574
|
-
"retryCount": 3,
|
|
575
|
-
"retryDelay": 1000,
|
|
576
|
-
"timeout": 15000,
|
|
577
|
-
"dryRunFirst": true,
|
|
578
|
-
"onlyMissingOrEnglish": true,
|
|
579
|
-
"reportStdout": true,
|
|
580
|
-
"bom": false,
|
|
581
|
-
"protectionEnabled": true,
|
|
582
|
-
"protectionFile": "./i18ntk-auto-translate.json",
|
|
583
|
-
"promptProtectionSetup": true,
|
|
584
|
-
"promptProtectionUpdate": true
|
|
585
|
-
},
|
|
586
|
-
"setup": {
|
|
587
|
-
"completed": true
|
|
588
|
-
},
|
|
589
|
-
"extensions": {
|
|
590
|
-
"workbench": {
|
|
591
|
-
"localeDirectory": "./locales",
|
|
592
|
-
"sourceLocale": "en"
|
|
593
|
-
},
|
|
594
|
-
"lens": {
|
|
595
|
-
"localeDirectory": "./locales",
|
|
596
|
-
"sourceLocale": "en",
|
|
597
|
-
"keyFormats": ["dot", "snake"]
|
|
598
|
-
}
|
|
599
|
-
}
|
|
600
|
-
}
|
|
193
|
+
```js
|
|
194
|
+
i18n.translateBatch(['menu.home', 'menu.settings']);
|
|
601
195
|
```
|
|
602
196
|
|
|
603
|
-
|
|
197
|
+
Production guidance:
|
|
198
|
+
|
|
199
|
+
- Use the instance from `initRuntime()` — not module-level `runtime.t()` — in multi-tenant apps
|
|
200
|
+
- Use `lazy: true` for large folders; `preload: true` for small sets
|
|
201
|
+
- Call `refresh(language)` after deploying changed locale files
|
|
202
|
+
- `i18ntk/runtime/enhanced` remains available for async/encryption compatibility
|
|
604
203
|
|
|
605
|
-
|
|
204
|
+
[Runtime guide →](./docs/runtime.md)
|
|
606
205
|
|
|
607
|
-
|
|
206
|
+
## Watch
|
|
608
207
|
|
|
609
|
-
|
|
208
|
+
```js
|
|
209
|
+
const watchLocales = require('i18ntk/utils/watch-locales');
|
|
210
|
+
const watcher = watchLocales('./locales');
|
|
610
211
|
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
- bundled internal UI locales
|
|
616
|
-
- shared utilities required by the shipped commands
|
|
617
|
-
- `README.md`, `CHANGELOG.md`, `LICENSE`, and policy files
|
|
212
|
+
watcher.on('change', (filePath) => console.log('changed:', filePath));
|
|
213
|
+
watcher.on('add', (filePath) => console.log('added:', filePath));
|
|
214
|
+
watcher.stop();
|
|
215
|
+
```
|
|
618
216
|
|
|
619
|
-
|
|
217
|
+
Features: 300ms debounce, SHA-256 hash tracking, 50-directory cap. The callback form `watchLocales('./locales', onChange)` is still supported.
|
|
620
218
|
|
|
621
219
|
## Documentation
|
|
622
220
|
|
|
623
|
-
- [Documentation Index](./docs/README.md)
|
|
624
221
|
- [Getting Started](./docs/getting-started.md)
|
|
222
|
+
- [Configuration](./docs/api/CONFIGURATION.md)
|
|
625
223
|
- [API Reference](./docs/api/API_REFERENCE.md)
|
|
626
|
-
- [
|
|
627
|
-
- [
|
|
628
|
-
- [Auto Translate Guide](./docs/auto-translate.md)
|
|
224
|
+
- [Runtime API](./docs/runtime.md)
|
|
225
|
+
- [Auto Translate](./docs/auto-translate.md)
|
|
629
226
|
- [Scanner Guide](./docs/scanner-guide.md)
|
|
630
227
|
- [Environment Variables](./docs/environment-variables.md)
|
|
631
|
-
- [Migration Guide v4.3.3](./docs/migration-guide-v4.3.3.md)
|
|
632
228
|
|
|
633
229
|
## Security
|
|
634
230
|
|
|
635
|
-
- No API key
|
|
636
|
-
- Do not store secrets in locale files, `.i18ntk-config`, or protection files
|
|
637
|
-
-
|
|
638
|
-
- Report security issues using [SECURITY.md](./SECURITY.md).
|
|
639
|
-
|
|
640
|
-
## Community
|
|
641
|
-
|
|
642
|
-
- [Contributing](./CONTRIBUTING.md)
|
|
643
|
-
- [Code of Conduct](./CODE_OF_CONDUCT.md)
|
|
644
|
-
- [Funding](./FUNDING.md)
|
|
231
|
+
- No API key required for default Auto Translate
|
|
232
|
+
- Do not store secrets in locale files, `.i18ntk-config`, or protection files
|
|
233
|
+
- Report issues via [SECURITY.md](./SECURITY.md)
|
|
645
234
|
|
|
646
|
-
## Related
|
|
235
|
+
## Related
|
|
647
236
|
|
|
648
|
-
| Tool
|
|
649
|
-
|
|
|
650
|
-
|
|
|
651
|
-
|
|
|
652
|
-
|
|
|
653
|
-
|
|
|
654
|
-
| **ContextKit** | AI coding context manager for AGENTS.md, Claude, Cursor, Copilot, Roo, and Codex files. |
|
|
237
|
+
| Tool | Purpose |
|
|
238
|
+
| ---------------- | ------------------------------------------- |
|
|
239
|
+
| i18ntk Workbench | VS Code localization health dashboard |
|
|
240
|
+
| i18ntk Lens | Inline hovers, CodeLens, and diagnostics |
|
|
241
|
+
| PublishGuard | Pre-publish safety scanner for npm packages |
|
|
242
|
+
| ContextKit | AI coding context manager |
|
|
655
243
|
|
|
656
244
|
## License
|
|
657
245
|
|
|
658
|
-
|
|
246
|
+
See [LICENSE](./LICENSE).
|