ai-localize-locale-engine 2.0.5 → 2.0.6
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 +7 -0
- package/README.md +97 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
package/README.md
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# ai-localize-locale-engine
|
|
2
|
+
|
|
3
|
+
> Locale file extraction, writing, merging, deduplication, and synchronization for the [ai-localize-core](https://github.com/ai-localize/ai-localize-core) platform.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/ai-localize-locale-engine)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## What it does
|
|
11
|
+
|
|
12
|
+
- **`LocaleExtractor`** — converts `DetectedText[]` into `LocaleFile[]` with namespace splitting, key deduplication, and `staticKeys` injection
|
|
13
|
+
- **`LocaleWriter`** — writes locale JSON files with merge support (preserves existing translations)
|
|
14
|
+
- **`deduplicateTexts()`** — deduplicates scanned texts by key so the same string isn't extracted twice
|
|
15
|
+
- **Flat and nested layouts** — one file per language, or one per language+namespace
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install ai-localize-locale-engine
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Usage
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import { LocaleExtractor, LocaleWriter, deduplicateTexts } from 'ai-localize-locale-engine';
|
|
27
|
+
|
|
28
|
+
// Extract
|
|
29
|
+
const extractor = new LocaleExtractor({
|
|
30
|
+
defaultLanguage: 'en',
|
|
31
|
+
targetLanguages: ['fr', 'de'],
|
|
32
|
+
namespaceSplitting: true, // split by first path segment
|
|
33
|
+
staticKeys: { // injected into every locale file
|
|
34
|
+
MAX_COUNT: 'Max Count',
|
|
35
|
+
ALLOWED: 'Allowed',
|
|
36
|
+
},
|
|
37
|
+
});
|
|
38
|
+
const uniqueTexts = deduplicateTexts(scanResult.detectedTexts);
|
|
39
|
+
const { localeFiles, keyCount, namespaces } = extractor.extract(uniqueTexts);
|
|
40
|
+
|
|
41
|
+
// Write
|
|
42
|
+
const writer = new LocaleWriter({
|
|
43
|
+
localesDir: './locales',
|
|
44
|
+
merge: true, // preserve existing translations
|
|
45
|
+
localeStructure: 'nested', // or 'flat'
|
|
46
|
+
});
|
|
47
|
+
const { written, created, merged } = writer.write(localeFiles);
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Locale layouts
|
|
51
|
+
|
|
52
|
+
### `nested` (default)
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
locales/
|
|
56
|
+
en/
|
|
57
|
+
translation.json ← default namespace
|
|
58
|
+
dashboard.json
|
|
59
|
+
fr/
|
|
60
|
+
translation.json ← seeded with English values for translators
|
|
61
|
+
dashboard.json
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### `flat`
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
locales/
|
|
68
|
+
en.json ← all namespaces merged
|
|
69
|
+
fr.json
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Static keys
|
|
73
|
+
|
|
74
|
+
Inject constant strings into every locale file using `staticKeys`. These are identical across all languages and are **not** flagged as untranslated by the validator:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
const extractor = new LocaleExtractor({
|
|
78
|
+
staticKeys: {
|
|
79
|
+
MAX_COUNT: 'Max Count',
|
|
80
|
+
ALLOWED: 'Allowed',
|
|
81
|
+
DISABLED: 'Disabled',
|
|
82
|
+
UNLIMITED: 'Unlimited',
|
|
83
|
+
},
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Merge behaviour
|
|
88
|
+
|
|
89
|
+
When `merge: true` (default), existing translations are preserved. Only **new** keys (or keys with empty values) are updated. This prevents overwriting human-provided translations on re-extraction.
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Part of ai-localize-core
|
|
94
|
+
|
|
95
|
+
Install the CLI for the complete toolset: `npm install -g ai-localize-cli`
|
|
96
|
+
|
|
97
|
+
MIT © ai-localize-core contributors
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ai-localize-locale-engine",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.6",
|
|
4
4
|
"description": "Locale file generation, merging, deduplication and synchronization",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"module": "./dist/index.mjs",
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
"node": ">=18.0.0"
|
|
34
34
|
},
|
|
35
35
|
"dependencies": {
|
|
36
|
-
"ai-localize-shared": "2.0.
|
|
36
|
+
"ai-localize-shared": "2.0.6"
|
|
37
37
|
},
|
|
38
38
|
"devDependencies": {
|
|
39
39
|
"tsup": "^8.0.1",
|