i18ntk 4.5.3 → 4.6.0
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 +63 -3
- package/README.md +127 -530
- package/main/i18ntk-analyze.js +77 -42
- package/main/i18ntk-complete.js +56 -37
- package/main/i18ntk-report.js +22 -9
- package/main/i18ntk-scanner.js +151 -29
- package/main/i18ntk-sizing.js +9 -6
- package/main/i18ntk-summary.js +61 -39
- package/main/i18ntk-usage.js +29 -16
- package/main/i18ntk-validate.js +38 -24
- package/main/manage/commands/AnalyzeCommand.js +79 -44
- package/main/manage/commands/ScannerCommand.js +158 -35
- package/main/manage/commands/ValidateCommand.js +37 -23
- package/main/manage/index.js +13 -9
- package/main/manage/services/FrameworkDetectionService.js +67 -9
- package/package.json +27 -36
- package/utils/config-helper.js +42 -32
- package/utils/exit-codes.js +8 -6
- package/utils/framework-detector.js +317 -6
- package/utils/prompt-helper.js +1 -1
- package/utils/report-model.js +17 -4
- package/utils/usage-source.js +2 -1
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# i18ntk v4.
|
|
1
|
+
# i18ntk v4.6.0
|
|
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,641 +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.0)
|
|
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.3
|
|
68
|
-
|
|
69
|
-
- **TSX/JSX SCANNING**: `supportedExtensions` default now includes `.tsx` and `.jsx`. Previously excluded from source scanning, causing React/Next.js projects to miss 97%+ of translation keys.
|
|
70
|
-
|
|
71
|
-
## What's New in 4.5.2
|
|
30
|
+
## What's New in 4.6.0
|
|
72
31
|
|
|
73
|
-
-
|
|
74
|
-
-
|
|
75
|
-
-
|
|
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
|
-
- **CORRECT COMPLETENESS**: Validation now shows accurate completion percentages vs source locale (e.g., 33% instead of misleading 100%).
|
|
81
|
-
- **NO MORE PARENT KEYS**: `getAllKeys()` no longer reports parent namespace objects (`footer`) as missing keys alongside their leaf children (`footer.copyright`).
|
|
82
|
-
- **DOCTOR SMARTER**: No longer flags unconfigured languages (`de`, `ru`) as issues. Auto-detects available languages from the i18n directory structure.
|
|
83
|
-
- **SCANNER FIXED**: Scanner now correctly scans `src/` directory for hardcoded text, not `locales/`.
|
|
84
|
-
- **RUNTIME ALIASES**: `initRuntime()` now supports `localeDir`/`targetLocale`/`sourceLocale` as aliases for `baseDir`/`language`/`fallbackLanguage`.
|
|
85
|
-
|
|
86
|
-
## What's New in 4.5.0
|
|
87
|
-
|
|
88
|
-
- **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.
|
|
89
|
-
- **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.
|
|
90
|
-
- **COMPLETE COMMAND FIXED**: `i18ntk-complete` no longer crashes with `getUnifiedConfig is not defined`. The missing config-helper import has been added.
|
|
91
|
-
- **MALFORMED JSON HANDLING**: Report generation now gracefully skips malformed JSON files with a warning instead of aborting the entire report.
|
|
92
|
-
- **NULL SAFETY**: `stripBOMAndComments()` in i18n-helper now handles null/undefined inputs without throwing.
|
|
93
|
-
- **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.
|
|
94
|
-
|
|
95
|
-
See [CHANGELOG.md](./CHANGELOG.md) for more release details.
|
|
40
|
+
[Full changelog →](./CHANGELOG.md)
|
|
96
41
|
|
|
97
42
|
## Quick Start
|
|
98
43
|
|
|
99
|
-
Initialize a project:
|
|
100
|
-
|
|
101
|
-
```bash
|
|
102
|
-
i18ntk
|
|
103
|
-
# or with explicit command
|
|
104
|
-
i18ntk --command=init
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
Run common checks:
|
|
108
|
-
|
|
109
|
-
```bash
|
|
110
|
-
i18ntk --command=analyze
|
|
111
|
-
i18ntk --command=validate
|
|
112
|
-
i18ntk --command=usage
|
|
113
|
-
i18ntk report --json
|
|
114
|
-
i18ntk --command=sizing
|
|
115
|
-
i18ntk --command=summary
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
Complete or fix translation files:
|
|
119
|
-
|
|
120
44
|
```bash
|
|
121
|
-
i18ntk
|
|
122
|
-
i18ntk
|
|
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
|
|
123
53
|
```
|
|
124
54
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
i18ntk --command=translate
|
|
129
|
-
# or
|
|
130
|
-
i18ntk-translate locales/en/common.json de --report-stdout
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
The full onboarding guide is in [docs/getting-started.md](./docs/getting-started.md).
|
|
134
|
-
|
|
135
|
-
## Main Commands
|
|
136
|
-
|
|
137
|
-
Primary CLI:
|
|
138
|
-
|
|
139
|
-
```bash
|
|
140
|
-
i18ntk
|
|
141
|
-
i18ntk --help
|
|
142
|
-
i18ntk --command=init
|
|
143
|
-
i18ntk --command=analyze
|
|
144
|
-
i18ntk --command=validate
|
|
145
|
-
i18ntk --command=usage
|
|
146
|
-
i18ntk report --json --markdown --html --out ./i18ntk-reports
|
|
147
|
-
i18ntk --command=scanner
|
|
148
|
-
i18ntk --command=sizing
|
|
149
|
-
i18ntk --command=complete
|
|
150
|
-
i18ntk --command=translate
|
|
151
|
-
i18ntk --command=summary
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
Standalone executables:
|
|
155
|
-
|
|
156
|
-
```bash
|
|
157
|
-
i18ntk-init
|
|
158
|
-
i18ntk-analyze
|
|
159
|
-
i18ntk-validate
|
|
160
|
-
i18ntk-usage
|
|
161
|
-
i18ntk-report
|
|
162
|
-
i18ntk-scanner
|
|
163
|
-
i18ntk-sizing
|
|
164
|
-
i18ntk-complete
|
|
165
|
-
i18ntk-summary
|
|
166
|
-
i18ntk-doctor
|
|
167
|
-
i18ntk-fixer
|
|
168
|
-
i18ntk-backup
|
|
169
|
-
i18ntk-translate
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
Note: manager route `i18ntk --command=backup` is available via the interactive menu. Use `i18ntk-backup` directly for scripted backup operations.
|
|
55
|
+
See [docs/getting-started.md](./docs/getting-started.md) for the full onboarding guide.
|
|
173
56
|
|
|
174
57
|
## Command Reference
|
|
175
58
|
|
|
176
|
-
| Command
|
|
177
|
-
|
|
|
178
|
-
| `i18ntk`
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
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>`.
|
|
191
76
|
|
|
192
77
|
## Common Options
|
|
193
78
|
|
|
194
|
-
Many commands support:
|
|
195
|
-
|
|
196
|
-
- `--source-dir <path>`
|
|
197
|
-
- `--i18n-dir <path>`
|
|
198
|
-
- `--output-dir <path>`
|
|
199
|
-
- `--source-language <code>`
|
|
200
|
-
- `--ui-language <code>`
|
|
201
|
-
- `--no-prompt`
|
|
202
|
-
- `--help`
|
|
203
|
-
|
|
204
|
-
Command-specific tools add their own flags such as `--dry-run`, `--output-report`, `--cleanup`, `--predict-expansion`, or Auto Translate provider options.
|
|
205
|
-
|
|
206
|
-
Example:
|
|
207
|
-
|
|
208
|
-
```bash
|
|
209
|
-
i18ntk --command=analyze --source-dir=./src --i18n-dir=./locales --output-dir=./i18ntk-reports
|
|
210
79
|
```
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
# 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
|
|
219
87
|
```
|
|
220
88
|
|
|
221
|
-
|
|
89
|
+
## Auto Translate
|
|
222
90
|
|
|
223
91
|
```bash
|
|
224
92
|
i18ntk-translate locales/en/common.json de
|
|
225
|
-
i18ntk-translate locales/en/common.json fr --dry-run --
|
|
226
|
-
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
|
|
227
94
|
```
|
|
228
95
|
|
|
229
|
-
|
|
96
|
+
**Providers:** Google (default), DeepL, LibreTranslate
|
|
230
97
|
|
|
231
98
|
```bash
|
|
232
|
-
export DEEPL_API_KEY="your-
|
|
233
|
-
i18ntk-translate locales/en/common.json de --provider deepl --no-confirm
|
|
234
|
-
|
|
235
|
-
export LIBRETRANSLATE_URL="https://libretranslate.com/translate"
|
|
236
|
-
export LIBRETRANSLATE_API_KEY="optional-api-key"
|
|
237
|
-
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
|
|
238
101
|
```
|
|
239
102
|
|
|
240
|
-
`
|
|
241
|
-
|
|
242
|
-
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.
|
|
243
|
-
|
|
244
|
-
The manager flow asks for:
|
|
245
|
-
|
|
246
|
-
- source locale directory, either the folder with JSON files or a locale root such as `./locales`
|
|
247
|
-
- source language code
|
|
248
|
-
- one or more target languages, or `all`
|
|
249
|
-
- one JSON file or all JSON files in the source directory
|
|
250
|
-
|
|
251
|
-
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.
|
|
252
|
-
|
|
253
|
-
Before writing files, the manager can run a dry-run preview. After confirmation it writes translated files under sibling target-language folders, for example:
|
|
254
|
-
|
|
255
|
-
```text
|
|
256
|
-
locales/en/common.json
|
|
257
|
-
locales/de/common.json
|
|
258
|
-
locales/fr/common.json
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
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.
|
|
262
|
-
|
|
263
|
-
### Placeholder Handling
|
|
264
|
-
|
|
265
|
-
Auto Translate detects common placeholders such as:
|
|
266
|
-
|
|
267
|
-
- `{name}`
|
|
268
|
-
- `{{count}}`
|
|
269
|
-
- `%s`
|
|
270
|
-
- `%d`
|
|
271
|
-
- `:id`
|
|
272
|
-
- `%{name}`
|
|
273
|
-
- `${value}`
|
|
274
|
-
- `{count, plural, one {# item} other {# items}}`
|
|
275
|
-
- `$t(common.save)`
|
|
276
|
-
- `%(total).2f`
|
|
277
|
-
|
|
278
|
-
Useful flags:
|
|
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.
|
|
279
104
|
|
|
280
|
-
|
|
281
|
-
- `--skip-placeholders`: copy placeholder-bearing strings unchanged
|
|
282
|
-
- `--send-placeholders`: send placeholder-bearing strings through translation after masking
|
|
283
|
-
- `--custom-regex <regex>`: add project-specific placeholder detection
|
|
284
|
-
- `--only-missing`: keep existing translated target values and translate only missing/source-copy/likely English values (default)
|
|
285
|
-
- `--translate-all`: re-translate every source string
|
|
286
|
-
|
|
287
|
-
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.
|
|
288
|
-
|
|
289
|
-
### Protected Terms and Keys
|
|
290
|
-
|
|
291
|
-
Auto Translate can create and use a project-local protection file:
|
|
292
|
-
|
|
293
|
-
```bash
|
|
294
|
-
i18ntk-translate locales/en/common.json de --create-protection-file --protection-file ./i18ntk-auto-translate.json
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
Example `i18ntk-auto-translate.json`:
|
|
105
|
+
Protected terms and keys via `i18ntk-auto-translate.json`:
|
|
298
106
|
|
|
299
107
|
```json
|
|
300
108
|
{
|
|
301
109
|
"version": 1,
|
|
302
|
-
"terms": [
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
{ "value": "OK", "context": "after:Click|Press|Tap" },
|
|
306
|
-
{ "value": "API", "context": "standalone" }
|
|
307
|
-
],
|
|
308
|
-
"keys": ["app.brandName", "legal.companyName", "product.*.symbol"],
|
|
309
|
-
"values": ["BrandName Ltd", "support@example.com"],
|
|
110
|
+
"terms": ["BrandName", "PRODUCT_CODE"],
|
|
111
|
+
"keys": ["app.brandName", "product.*.symbol"],
|
|
112
|
+
"values": ["BrandName Ltd"],
|
|
310
113
|
"patterns": ["[A-Z]{2,}-\\d+"]
|
|
311
114
|
}
|
|
312
115
|
```
|
|
313
116
|
|
|
314
|
-
|
|
315
|
-
- **Plain strings**: masked everywhere (backward compatible).
|
|
316
|
-
- **Context objects**: masked only in specific contexts (`after:word`, `before:word`, `standalone`, `surrounded:left,right`).
|
|
317
|
-
- `keys` are exact key paths or `*` wildcard paths copied unchanged.
|
|
318
|
-
- `values` are exact source values copied unchanged.
|
|
319
|
-
- `patterns` are JavaScript regex strings for advanced protected substrings.
|
|
320
|
-
|
|
321
|
-
Useful flags:
|
|
322
|
-
|
|
323
|
-
- `--protection-file <path>`
|
|
324
|
-
- `--create-protection-file`
|
|
325
|
-
- `--no-protection`
|
|
326
|
-
|
|
327
|
-
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.
|
|
328
|
-
|
|
329
|
-
See [docs/auto-translate.md](./docs/auto-translate.md) for the full Auto Translate guide.
|
|
330
|
-
|
|
331
|
-
## Validation
|
|
117
|
+
[Auto Translate guide →](./docs/auto-translate.md)
|
|
332
118
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
Validation warning types are specific:
|
|
336
|
-
|
|
337
|
-
- `Potential risky content`: URL, email address, or secret-like value
|
|
338
|
-
- `Possible untranslated English content`: target-language value appears to contain too much English
|
|
339
|
-
|
|
340
|
-
English-content warnings include:
|
|
341
|
-
|
|
342
|
-
- detected English percentage
|
|
343
|
-
- configured threshold
|
|
344
|
-
- matched word count
|
|
345
|
-
- sample matched words
|
|
119
|
+
## Configuration
|
|
346
120
|
|
|
347
|
-
|
|
121
|
+
Example `.i18ntk-config`:
|
|
348
122
|
|
|
349
123
|
```json
|
|
350
124
|
{
|
|
125
|
+
"version": "4.6.0",
|
|
126
|
+
"sourceDir": "./locales",
|
|
127
|
+
"i18nDir": "./locales",
|
|
128
|
+
"sourceLanguage": "en",
|
|
129
|
+
"defaultLanguages": ["en", "de", "es", "fr", "ru"],
|
|
130
|
+
"keyStyle": "dot.notation",
|
|
351
131
|
"englishContentThresholdPercent": 10,
|
|
352
|
-
"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
|
+
}
|
|
353
142
|
}
|
|
354
143
|
```
|
|
355
144
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
`i18ntk-sizing` reports translation file sizes, key counts, average value length, and file-set mismatches across language folders.
|
|
359
|
-
|
|
360
|
-
```bash
|
|
361
|
-
i18ntk-sizing --source-dir ./locales --format table
|
|
362
|
-
i18ntk-sizing --source-dir ./locales --detailed --output-dir ./i18ntk-reports
|
|
363
|
-
```
|
|
364
|
-
|
|
365
|
-
Use `--detailed` to print per-file rows in the terminal.
|
|
366
|
-
|
|
367
|
-
### Expansion Prediction (New in 4.0.0)
|
|
368
|
-
|
|
369
|
-
Predict UI layout overflow risk by analyzing per-key character-count expansion across languages:
|
|
370
|
-
|
|
371
|
-
```bash
|
|
372
|
-
i18ntk-sizing --source-dir ./locales --predict-expansion --output-report
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
Expansion ratios are classified into risk tiers:
|
|
376
|
-
|
|
377
|
-
- **Safe** (<30% expansion): no UI impact expected
|
|
378
|
-
- **Warning** (30–50%): may overflow in tight layouts — test on target languages
|
|
379
|
-
- **Critical** (>50%): high risk of truncation — review UI element sizing
|
|
145
|
+
[Configuration reference →](./docs/api/CONFIGURATION.md)
|
|
380
146
|
|
|
381
|
-
|
|
147
|
+
## Scanner
|
|
382
148
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
`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.
|
|
386
150
|
|
|
387
151
|
```bash
|
|
388
|
-
i18ntk-scanner --
|
|
389
|
-
i18ntk-scanner --
|
|
152
|
+
i18ntk-scanner --code-dir ./src --source-locale de
|
|
153
|
+
i18ntk-scanner --code-dir ./src --source-locale ja --output-report
|
|
390
154
|
```
|
|
391
155
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
## Usage: Dead Key Detection (New in 4.0.0)
|
|
156
|
+
## Usage Analysis
|
|
395
157
|
|
|
396
|
-
|
|
158
|
+
Tracks key references, detects dead keys with confidence scores, resolves dynamic patterns (templates, arrays, object maps), and recommends namespace alignment.
|
|
397
159
|
|
|
398
160
|
```bash
|
|
399
|
-
i18ntk-usage --
|
|
400
|
-
i18ntk-usage --source-dir ./src --i18n-dir ./locales --cleanup --dry-run-delete
|
|
401
|
-
```
|
|
402
|
-
|
|
403
|
-
Each dead key receives a confidence score (0.0–1.0) factoring:
|
|
404
|
-
|
|
405
|
-
- 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
|
|
406
|
-
- Key appears in source code comments or JSDoc — medium score
|
|
407
|
-
- Parent file recently modified (<30 days) — medium score
|
|
408
|
-
- No references found anywhere — high score (>0.8)
|
|
409
|
-
|
|
410
|
-
The `--dry-run-delete` flag writes a `.dead-keys.json` report for review before any destructive action.
|
|
411
|
-
|
|
412
|
-
## Validator: Key Naming Conventions (New in 4.0.0)
|
|
413
|
-
|
|
414
|
-
Enforce consistent translation key naming across your project:
|
|
415
|
-
|
|
416
|
-
```bash
|
|
417
|
-
i18ntk-validate --enforce-key-style
|
|
418
|
-
```
|
|
419
|
-
|
|
420
|
-
Configure the expected style in `.i18ntk-config`:
|
|
421
|
-
|
|
422
|
-
```json
|
|
423
|
-
{
|
|
424
|
-
"keyStyle": "dot.notation"
|
|
425
|
-
}
|
|
161
|
+
i18ntk-usage --code-dir ./src --locales-dir ./locales --cleanup --dry-run-delete
|
|
426
162
|
```
|
|
427
163
|
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
## Watch: Hot Reload (New in 4.0.0)
|
|
431
|
-
|
|
432
|
-
`utils/watch-locales.js` now provides debounced file watching with EventEmitter support:
|
|
433
|
-
|
|
434
|
-
```js
|
|
435
|
-
const watchLocales = require('i18ntk/utils/watch-locales');
|
|
436
|
-
const watcher = watchLocales('./locales');
|
|
437
|
-
|
|
438
|
-
watcher.on('change', (filePath) => {
|
|
439
|
-
console.log('Locale changed:', filePath);
|
|
440
|
-
});
|
|
441
|
-
|
|
442
|
-
watcher.on('add', (filePath) => {
|
|
443
|
-
console.log('Locale added:', filePath);
|
|
444
|
-
});
|
|
445
|
-
|
|
446
|
-
// Later:
|
|
447
|
-
watcher.stop();
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
Features: 300ms debounce (configurable), SHA-256 hash tracking to skip no-change saves, and a maximum of 50 watched directories.
|
|
451
|
-
|
|
452
|
-
### Migration
|
|
453
|
-
|
|
454
|
-
The `watchLocales` return value gained EventEmitter methods in v4.0.0. Existing stop-function usage still works:
|
|
455
|
-
|
|
456
|
-
```js
|
|
457
|
-
const stop = watchLocales('./locales', onChange);
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
Can be updated to:
|
|
461
|
-
|
|
462
|
-
```js
|
|
463
|
-
const watcher = watchLocales('./locales');
|
|
464
|
-
watcher.on('change', onChange);
|
|
465
|
-
watcher.stop();
|
|
466
|
-
```
|
|
467
|
-
|
|
468
|
-
Passing a callback as the second argument is still supported — it auto-subscribes to `change` and `add` events.
|
|
469
|
-
|
|
470
|
-
## Backup: Incremental Mode (New in 4.0.0)
|
|
471
|
-
|
|
472
|
-
Create differential backups that only include changed files:
|
|
473
|
-
|
|
474
|
-
```bash
|
|
475
|
-
i18ntk-backup create ./locales --incremental
|
|
476
|
-
```
|
|
477
|
-
|
|
478
|
-
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.
|
|
479
|
-
|
|
480
|
-
## Runtime: Lazy Loading (New in 4.0.0)
|
|
481
|
-
|
|
482
|
-
Reduce memory usage by deferring locale file loads until first key access:
|
|
164
|
+
## Runtime
|
|
483
165
|
|
|
484
166
|
```js
|
|
485
167
|
const runtime = require('i18ntk/runtime');
|
|
486
|
-
|
|
487
|
-
const i18n = runtime.initRuntime({
|
|
488
|
-
baseDir: './locales',
|
|
489
|
-
language: 'en',
|
|
490
|
-
lazy: true,
|
|
491
|
-
});
|
|
492
|
-
|
|
493
|
-
console.log(i18n.t('common.hello')); // loads common.json on first access
|
|
494
|
-
```
|
|
495
|
-
|
|
496
|
-
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.
|
|
497
|
-
|
|
498
|
-
Production guidance:
|
|
499
|
-
|
|
500
|
-
- Prefer the object returned from `initRuntime()` instead of module-level `runtime.t()` in apps with multiple tenants, projects, or locale roots.
|
|
501
|
-
- Use `lazy: true` for large modular locale folders where lower steady-state memory matters more than a small first-key lookup cost.
|
|
502
|
-
- Use `preload: true` without `lazy` for small locale sets or latency-sensitive startup paths.
|
|
503
|
-
- Call `refresh(language)` after deploying or writing changed locale files so cached data and lazy manifests are rebuilt.
|
|
504
|
-
- Use per-call language overrides when rendering one-off alternate-language strings: `i18n.t('common.hello', {}, { language: 'de' })`.
|
|
505
|
-
- Use `translateBatch()` for small groups of labels and `clearCache()` / `getCacheInfo()` for cache maintenance and diagnostics.
|
|
506
|
-
- `i18ntk/runtime/enhanced` remains available for compatibility with existing async/encryption users, but new production integrations should start with `i18ntk/runtime`.
|
|
507
|
-
|
|
508
|
-
## Runtime API
|
|
509
|
-
|
|
510
|
-
Use `i18ntk/runtime` when an application needs to read locale JSON files at runtime.
|
|
511
|
-
|
|
512
|
-
```js
|
|
513
|
-
const runtime = require('i18ntk/runtime');
|
|
514
|
-
|
|
515
168
|
const i18n = runtime.initRuntime({
|
|
516
169
|
baseDir: './locales',
|
|
517
170
|
language: 'en',
|
|
518
171
|
fallbackLanguage: 'en',
|
|
519
|
-
keySeparator: '.',
|
|
520
|
-
preload: true,
|
|
521
172
|
});
|
|
522
173
|
|
|
523
174
|
console.log(i18n.t('common.hello'));
|
|
524
175
|
i18n.setLanguage('fr');
|
|
525
|
-
console.log(i18n.getLanguage());
|
|
526
176
|
console.log(i18n.getAvailableLanguages());
|
|
527
|
-
i18n.refresh('fr');
|
|
528
177
|
```
|
|
529
178
|
|
|
530
|
-
|
|
179
|
+
**Lazy loading** reduces memory on large locale folders:
|
|
531
180
|
|
|
532
181
|
```js
|
|
533
|
-
i18n.
|
|
534
|
-
i18n.translateBatch(['menu.home', 'menu.settings']);
|
|
535
|
-
i18n.clearCache('fr');
|
|
536
|
-
console.log(i18n.getCacheInfo());
|
|
182
|
+
const i18n = runtime.initRuntime({ baseDir: './locales', language: 'en', lazy: true });
|
|
537
183
|
```
|
|
538
184
|
|
|
539
|
-
|
|
185
|
+
**Per-call language overrides:**
|
|
540
186
|
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
187
|
+
```js
|
|
188
|
+
i18n.t('common.hello', {}, { language: 'de' });
|
|
189
|
+
```
|
|
544
190
|
|
|
545
|
-
|
|
191
|
+
**Batch translation:**
|
|
546
192
|
|
|
547
|
-
```
|
|
548
|
-
|
|
549
|
-
"version": "4.5.3",
|
|
550
|
-
"sourceDir": "./locales",
|
|
551
|
-
"i18nDir": "./locales",
|
|
552
|
-
"outputDir": "./i18ntk-reports",
|
|
553
|
-
"sourceLanguage": "en",
|
|
554
|
-
"defaultLanguages": ["en", "de", "es", "fr", "ru"],
|
|
555
|
-
"reports": {
|
|
556
|
-
"format": "markdown"
|
|
557
|
-
},
|
|
558
|
-
"englishContentThresholdPercent": 10,
|
|
559
|
-
"allowedEnglishTerms": ["BrandName", "PRODUCT_CODE"],
|
|
560
|
-
"autoTranslate": {
|
|
561
|
-
"placeholderMode": "preserve",
|
|
562
|
-
"concurrency": 12,
|
|
563
|
-
"batchSize": 100,
|
|
564
|
-
"progressInterval": 25,
|
|
565
|
-
"retryCount": 3,
|
|
566
|
-
"retryDelay": 1000,
|
|
567
|
-
"timeout": 15000,
|
|
568
|
-
"dryRunFirst": true,
|
|
569
|
-
"onlyMissingOrEnglish": true,
|
|
570
|
-
"reportStdout": true,
|
|
571
|
-
"bom": false,
|
|
572
|
-
"protectionEnabled": true,
|
|
573
|
-
"protectionFile": "./i18ntk-auto-translate.json",
|
|
574
|
-
"promptProtectionSetup": true,
|
|
575
|
-
"promptProtectionUpdate": true
|
|
576
|
-
},
|
|
577
|
-
"setup": {
|
|
578
|
-
"completed": true
|
|
579
|
-
},
|
|
580
|
-
"extensions": {
|
|
581
|
-
"workbench": {
|
|
582
|
-
"localeDirectory": "./locales",
|
|
583
|
-
"sourceLocale": "en"
|
|
584
|
-
},
|
|
585
|
-
"lens": {
|
|
586
|
-
"localeDirectory": "./locales",
|
|
587
|
-
"sourceLocale": "en",
|
|
588
|
-
"keyFormats": ["dot", "snake"]
|
|
589
|
-
}
|
|
590
|
-
}
|
|
591
|
-
}
|
|
193
|
+
```js
|
|
194
|
+
i18n.translateBatch(['menu.home', 'menu.settings']);
|
|
592
195
|
```
|
|
593
196
|
|
|
594
|
-
|
|
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
|
|
595
203
|
|
|
596
|
-
|
|
204
|
+
[Runtime guide →](./docs/runtime.md)
|
|
597
205
|
|
|
598
|
-
|
|
206
|
+
## Watch
|
|
599
207
|
|
|
600
|
-
|
|
208
|
+
```js
|
|
209
|
+
const watchLocales = require('i18ntk/utils/watch-locales');
|
|
210
|
+
const watcher = watchLocales('./locales');
|
|
601
211
|
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
- bundled internal UI locales
|
|
607
|
-
- shared utilities required by the shipped commands
|
|
608
|
-
- `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
|
+
```
|
|
609
216
|
|
|
610
|
-
|
|
217
|
+
Features: 300ms debounce, SHA-256 hash tracking, 50-directory cap. The callback form `watchLocales('./locales', onChange)` is still supported.
|
|
611
218
|
|
|
612
219
|
## Documentation
|
|
613
220
|
|
|
614
|
-
- [Documentation Index](./docs/README.md)
|
|
615
221
|
- [Getting Started](./docs/getting-started.md)
|
|
222
|
+
- [Configuration](./docs/api/CONFIGURATION.md)
|
|
616
223
|
- [API Reference](./docs/api/API_REFERENCE.md)
|
|
617
|
-
- [
|
|
618
|
-
- [
|
|
619
|
-
- [Auto Translate Guide](./docs/auto-translate.md)
|
|
224
|
+
- [Runtime API](./docs/runtime.md)
|
|
225
|
+
- [Auto Translate](./docs/auto-translate.md)
|
|
620
226
|
- [Scanner Guide](./docs/scanner-guide.md)
|
|
621
227
|
- [Environment Variables](./docs/environment-variables.md)
|
|
622
|
-
- [Migration Guide v4.3.3](./docs/migration-guide-v4.3.3.md)
|
|
623
228
|
|
|
624
229
|
## Security
|
|
625
230
|
|
|
626
|
-
- No API key
|
|
627
|
-
- Do not store secrets in locale files, `.i18ntk-config`, or protection files
|
|
628
|
-
-
|
|
629
|
-
- Report security issues using [SECURITY.md](./SECURITY.md).
|
|
630
|
-
|
|
631
|
-
## Community
|
|
632
|
-
|
|
633
|
-
- [Contributing](./CONTRIBUTING.md)
|
|
634
|
-
- [Code of Conduct](./CODE_OF_CONDUCT.md)
|
|
635
|
-
- [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)
|
|
636
234
|
|
|
637
|
-
## Related
|
|
235
|
+
## Related
|
|
638
236
|
|
|
639
|
-
| Tool
|
|
640
|
-
|
|
|
641
|
-
|
|
|
642
|
-
|
|
|
643
|
-
|
|
|
644
|
-
|
|
|
645
|
-
| **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 |
|
|
646
243
|
|
|
647
244
|
## License
|
|
648
245
|
|
|
649
|
-
|
|
246
|
+
See [LICENSE](./LICENSE).
|