ai-i18n-tools 1.5.0 → 1.5.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.
Files changed (4) hide show
  1. package/README.md +85 -35
  2. package/dist/build-info.generated.d.ts +1 -1
  3. package/dist/build-info.generated.js +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -7,26 +7,38 @@
7
7
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
8
8
  [![CI](https://github.com/wsj-br/ai-i18n-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/wsj-br/ai-i18n-tools/actions/workflows/ci.yml)
9
9
 
10
- CLI and toolkit for internationalising JavaScript/TypeScript applications and documentation sites using large language models via [OpenRouter](https://openrouter.ai/). Two independent workflows: **UI Translation** extracts `t("…")` calls and writes locale-ready JSON for i18next; **Document Translation** translates markdown, MDX, and SVG files with a smart SQLite cache so only changed segments are re-sent to the LLM.
10
+ A CLI and toolkit for internationalizing JavaScript/TypeScript applications and documentation sites using large language models via [OpenRouter](https://openrouter.ai/). Three modular workflows, all sharing a single config file, support different translation needs:
11
11
 
12
+ - **Workflow 1 — UI Translation:** Extracts `t("…")` calls from JS/TS (and optionally from `.astro` files) and generates flat, per-locale JSON for i18next or static SSG lookup.
13
+ - **Workflow 2 — Document Translation:** Translates markdown, MDX, and `.astro` pages (for websites and Starlight) listed in `docs[].contentPaths` using `translate-docs`.
14
+ - **Workflow 3 — JSON File Translation:** Translates arbitrary nested JSON bundles defined in `json[]`. Use `translate-json` when UI copy is stored in per-locale JSON files instead of using `t()` in source.
15
+
16
+ **SVG** assets are translated using `features.translateSVG`, the top-level `svg` block, and `translate-svg`—not `docs[].contentPaths`.
17
+
18
+ **Which workflow should I use?**
19
+ - Source uses `t()` → **Workflow 1** (`extract` / `translate-ui`)
20
+ - Localized pages or Docusaurus catalog JSON → **Workflow 2** (`translate-docs`)
21
+ - Only standalone, nested JSON locale files → **Workflow 3** (`translate-json`)
22
+
23
+ All workflows maintain a file/SQLite cache to ensure that only new or changed segments (strings or text chunks) are sent to the LLM.
12
24
 
13
25
  <small>**Read in other languages:** </small>
14
26
  <small id="lang-list">[English (GB)](./README.md) · [Deutsch](./translated-docs/README.de.md) · [Español](./translated-docs/README.es.md) · [Français](./translated-docs/README.fr.md) · [हिन्दी](./translated-docs/README.hi.md) · [日本語](./translated-docs/README.ja.md) · [한국어](./translated-docs/README.ko.md) · [Português (Brasil)](./translated-docs/README.pt-BR.md) · [中文 (中国大陆)](./translated-docs/README.zh-CN.md) · [中文 (台灣)](./translated-docs/README.zh-TW.md)</small>
15
27
 
16
- <small>Translated READMEs and docs are committed under [`translated-docs/`](https://github.com/wsj-br/ai-i18n-tools/tree/main/translated-docs) on GitHub; the npm package ships English `docs/` only.</small>
17
28
 
18
29
  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
19
30
  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
20
31
  **Table of Contents**
21
32
 
22
- - [Two core workflows](#two-core-workflows)
33
+ - [Core workflows](#core-workflows)
23
34
  - [Installation](#installation)
24
35
  - [Using the CLI](#using-the-cli)
25
36
  - [OpenRouter](#openrouter)
26
37
  - [Quick start](#quick-start)
27
38
  - [Workflow 1 - UI Translation](#workflow-1---ui-translation)
28
39
  - [Workflow 2 - Document Translation](#workflow-2---document-translation)
29
- - [Both workflows](#both-workflows)
40
+ - [Astro (plain Astro & Starlight)](#astro-plain-astro--starlight)
41
+ - [Combined workflow](#combined-workflow)
30
42
  - [Runtime helpers](#runtime-helpers)
31
43
  - [CLI commands](#cli-commands)
32
44
  - [Documentation](#documentation)
@@ -38,18 +50,22 @@ CLI and toolkit for internationalising JavaScript/TypeScript applications and do
38
50
 
39
51
 
40
52
 
41
- <a id="two-core-workflows"></a>
42
- ## Two core workflows
53
+ <a id="core-workflows"></a>
54
+ ## Core workflows
55
+
56
+ **Workflow 1 - UI Translation** — for any JS/TS project using i18next (React, Next.js, Node.js, CLIs) or static Astro SSG
43
57
 
44
- **Workflow 1 - UI Translation** — for any JS/TS project using i18next (React, Next.js, Node.js, CLIs)
58
+ Scans source files for `t("…")` / `i18n.t("…")` literals (add `.astro` to `ui.uiExtractor.extensions` for Astro frontmatter and template expressions), builds a master catalog (`strings.json`), translates missing entries per locale via OpenRouter, and writes flat JSON files (`de.json`, `pt-BR.json`, …). English source text is the runtime lookup key in those bundles — `strings.json` is the extraction cache, not the runtime bundle.
45
59
 
46
- Scans source files for `t("…")` / `i18n.t("…")` literals, builds a master catalog (`strings.json`), translates missing entries per locale via OpenRouter, and writes flat JSON files (`de.json`, `pt-BR.json`, …) ready for i18next.
60
+ **Workflow 2 - Document Translation** — for markdown, MDX, and `.astro` under `docs[].contentPaths`
47
61
 
48
- **Workflow 2 - Document Translation** — for markdown/MDX docs (Docusaurus, Astro Starlight, plain README files) and `.astro` page HTML (plain Astro marketing sites)
62
+ Designed primarily for **markdown, MDX, and `.astro` documentation** (Docusaurus, [Astro Starlight](https://starlight.astro.build/), plain README files, and plain Astro marketing pages). `translate-docs` writes localised copies with a shared SQLite cache. On Docusaurus sites, set `docs[].docusaurusCatalogDir` to the `write-translations` catalog folder so shell JSON (navbar, footer, theme strings) is translated in the same command. `docs[].docsOutput.style` supports `"nested"`, `"flat"`, `"doc-system"`, and aliases `"docusaurus"` / `"astro-starlight"` (see [Output layouts](docs/GETTING_STARTED.md#output-layouts) in Getting Started). Arbitrary nested UI JSON that is not a Docusaurus catalog belongs in Workflow 3 (`json[]` / `translate-json`), not `docs[]`.
49
63
 
50
- Translates `.md`, `.mdx`, and `.astro` source files to every target locale with a shared SQLite cache — only new or changed segments are sent to the LLM. Optional Docusaurus shell JSON (`jsonSource`, from `write-translations`) covers navbar, footer, and theme UI strings. SVG file translation is enabled via `features.translateSVG` and the top-level `svg` block. For plain Astro sites, see [`examples/astro-website`](examples/astro-website/) (hybrid: `translate-docs` for page HTML plus `t()` for frontmatter strings).
64
+ **Workflow 3 - JSON file translation** — nested locale JSON without `t()` in source
51
65
 
52
- Both workflows share a single `ai-i18n-tools.config.json` file and can be used independently or together.
66
+ Translate files such as `src/i18n/en/translation.json` via top-level `json[]`, `features.translateJson`, and `translate-json`. Scaffold with `init -t ui-json-bundles`.
67
+
68
+ All workflows share `ai-i18n-tools.config.json` and can be combined; `sync` runs extract, UI translation, translate SVG, `translate-docs`, and `translate-json` in order according to your `features` flags.
53
69
 
54
70
  ---
55
71
 
@@ -76,11 +92,19 @@ npx ai-i18n-tools sync # or: pnpm exec ai-i18n-tools sync
76
92
 
77
93
  ```json
78
94
  "scripts": {
95
+ "i18n:extract": "ai-i18n-tools extract",
79
96
  "i18n:sync": "ai-i18n-tools sync",
97
+ "i18n:translate:ui": "ai-i18n-tools translate-ui",
98
+ "i18n:translate:docs": "ai-i18n-tools translate-docs",
80
99
  "i18n:translate": "ai-i18n-tools translate-docs"
81
100
  }
82
101
  ```
83
102
 
103
+ You can also use the ai-i18n-tools CLI commands directly, for instance `ai-i18n-tools sync`.
104
+
105
+
106
+ Prefer `sync` over hand-chaining `extract`, `translate-ui`, `translate-svg`, `translate-docs`, and `translate-json` — order and feature flags are easy to get wrong when run manually. See [Recommended `package.json` scripts](docs/GETTING_STARTED.md#recommended-packagejson-scripts) in Getting Started.
107
+
84
108
  **Zero-install one-off** — `npx ai-i18n-tools <cmd>` or `pnpm dlx ai-i18n-tools <cmd>` (downloads for that invocation only).
85
109
 
86
110
  > **Tip:** To run `ai-i18n-tools` bare in an interactive shell without `npx`, add `node_modules/.bin` to your `PATH` (bash/zsh: `export PATH="$PWD/node_modules/.bin:$PATH"`). See [Getting Started](docs/GETTING_STARTED.md#installation) for direnv and Windows instructions.
@@ -96,7 +120,7 @@ export OPENROUTER_API_KEY=sk-or-v1-your-key-here
96
120
  <a id="openrouter"></a>
97
121
  ## OpenRouter
98
122
 
99
- Commands that call OpenRouter (`translate-ui`, `translate-docs`, `sync`, `check-models`, and related scripts) need `OPENROUTER_API_KEY` in the environment. `check-markdown` does not use OpenRouter.
123
+ Commands that call OpenRouter (`translate-ui`, `translate-docs`, `translate-json`, `sync`, `check-models`, and related scripts) need `OPENROUTER_API_KEY` in the environment. `check-markdown` does not use OpenRouter.
100
124
 
101
125
  In `ai-i18n-tools.config.json`, the `openrouter` object includes model lists, `baseUrl`, `maxTokens`, `temperature`, and `requestTimeoutMs`: the maximum time in milliseconds to wait for each HTTP request to OpenRouter (chat completions and internal `GET /models` calls). The default is `30000` (30 seconds).
102
126
 
@@ -111,7 +135,7 @@ Run `ai-i18n-tools check-models` to verify each configured model id against Open
111
135
  ### Workflow 1 - UI Translation
112
136
 
113
137
  ```bash
114
- # 1. Create config
138
+ # 1. Create config (default ui-markdown; plain Astro: init -t ui-astro-website)
115
139
  npx ai-i18n-tools init
116
140
 
117
141
  # 2. Extract UI strings to strings.json
@@ -126,24 +150,48 @@ Then wire i18next in your app using the helpers from `'ai-i18n-tools/runtime'`.
126
150
  <a id="workflow-2---document-translation"></a>
127
151
  ### Workflow 2 - Document Translation
128
152
 
153
+ The default `init` template (`ui-markdown`) enables UI extraction only. Use a docs-oriented template (or enable `features.translateDocs` and add `docs[]`) before `translate-docs`:
154
+
129
155
  ```bash
130
- # 1. Create config for Docusaurus
156
+ # Docusaurus docs + optional write-translations catalog
131
157
  npx ai-i18n-tools init -t ui-docusaurus
132
- # Astro Starlight: npx ai-i18n-tools init -t ui-starlight
133
- # Plain Astro website (UI + optional page HTML): npx ai-i18n-tools init -t ui-astro-website
134
158
 
135
- # 2. Translate all docs
136
- npx ai-i18n-tools translate-docs
159
+ # Astro Starlight documentation
160
+ # npx ai-i18n-tools init -t ui-starlight
161
+
162
+ # Plain Astro website — UI extraction for t() in .astro; add docs[] for page HTML (see Astro below)
163
+ # npx ai-i18n-tools init -t ui-astro-website
137
164
 
138
- # 3. Check status
165
+ npx ai-i18n-tools translate-docs
139
166
  npx ai-i18n-tools status
167
+ # npx ai-i18n-tools translate-docs --locale de # single locale
140
168
  ```
141
169
 
142
- <a id="both-workflows"></a>
143
- ### Both workflows
170
+ Edit `ai-i18n-tools.config.json`: set `docs[].contentPaths` to markdown, MDX, and/or `.astro` sources; `docs[].outputDir` and `docs[].docsOutput.style` (`"docusaurus"`, `"astro-starlight"`, `"flat"`, etc.). Full field reference: [Workflow 2 - Document Translation](docs/GETTING_STARTED.md#workflow-2---document-translation).
171
+
172
+ <a id="astro-plain-astro--starlight"></a>
173
+ ### Astro (plain Astro & Starlight)
174
+
175
+ **Astro Starlight** — `init -t ui-starlight`, then `translate-docs`. Starlight UI overrides can use `src/content/i18n/en.json` with `jsonPathTemplate` in a separate `docs[]` block when needed ([Getting Started → Workflow 2](docs/GETTING_STARTED.md#step-1-initialise-for-documentation)).
176
+
177
+ **Plain Astro** (marketing or app sites, not Starlight) — combine [Astro built-in i18n routing](https://docs.astro.build/en/guides/internationalization/) with ai-i18n-tools. Reference project: [`examples/astro-website`](examples/astro-website/) (English at `/`, locales at `/{locale}/`).
178
+
179
+ Most teams use a **hybrid** of two pipelines:
180
+
181
+ | Pipeline | Use for | Commands | Output |
182
+ |----------|---------|----------|--------|
183
+ | **Page HTML** | Headings, paragraphs, nav labels, inline arrays in the template body | `translate-docs` | `src/pages/{locale}/index.astro` per locale |
184
+ | **UI strings (`t()`)** | Frontmatter data, tab labels, shared arrays | `extract` → `translate-ui` | `public/locales/{locale}.json` (English source as key) |
185
+
186
+ Scaffold UI with `init -t ui-astro-website`. For hardcoded HTML in `.astro` pages, enable `features.translateDocs` and add a `docs[]` block with `docsOutput.style: "astro-starlight"` (see [Astro website pages (parse-and-replace)](docs/GETTING_STARTED.md#astro-website-pages-parse-and-replace)). Keep `targetLocales`, `i18n.locales` in `astro.config.mjs`, and `ui-languages.json` aligned (Astro routes use lowercase codes such as `pt-br`; flat bundle filenames follow config casing, e.g. `pt-BR.json`).
187
+
188
+ Wire `t()` at build time without i18next unless you add client islands — see [Astro website UI strings (SSG)](docs/GETTING_STARTED.md#astro-website-ui-strings-ssg) and the example’s `src/i18n/t.ts`.
189
+
190
+ <a id="combined-workflow"></a>
191
+ ### Combined workflow
144
192
 
145
193
  ```bash
146
- npx ai-i18n-tools sync # Extract UI strings, then translate UI strings, SVG, and docs
194
+ npx ai-i18n-tools sync # extract → translate-ui → translate-svg → translate-docs → translate-json (per features)
147
195
  ```
148
196
 
149
197
  ---
@@ -174,39 +222,41 @@ The following helpers are exported from `'ai-i18n-tools/runtime'` and work in an
174
222
 
175
223
  ```bash
176
224
  ai-i18n-tools version
177
- ai-i18n-tools help [command]
178
- ai-i18n-tools init [-t ui-markdown|ui-docusaurus] [-o path] [--with-translate-ignore]
179
225
  ai-i18n-tools check-models
180
- ai-i18n-tools generate-ui-languages [--master path] [--dry-run]
181
- ai-i18n-tools extract
182
- ai-i18n-tools translate-docs …
226
+ ai-i18n-tools init [-t ui-markdown|ui-docusaurus|ui-starlight|ui-astro-website|ui-json-bundles] [-o path] [--with-translate-ignore]
183
227
  ai-i18n-tools write-heading-ids …
184
228
  ai-i18n-tools strip-md-bold-inline …
185
- ai-i18n-tools check-markdown [-p|--path <path>] [--json] [--no-cache]
229
+ ai-i18n-tools extract
230
+ ai-i18n-tools translate-docs …
231
+ ai-i18n-tools translate-json …
186
232
  ai-i18n-tools translate-svg …
187
233
  ai-i18n-tools translate-ui …
234
+ ai-i18n-tools sync-ui …
188
235
  ai-i18n-tools lint-source …
236
+ ai-i18n-tools check-markdown [-p|--path <path>] [-f|--file <path>] [--json] [--no-cache]
189
237
  ai-i18n-tools export-ui-xliff …
190
238
  ai-i18n-tools sync …
191
- ai-i18n-tools status [--max-columns <n>]
192
- ai-i18n-tools statistics [--max-columns <n>]
193
- ai-i18n-tools dashboard
194
- ai-i18n-tools cleanup [--dry-run] [--no-backup] [--backup <path>]
195
- ai-i18n-tools clean-temp [-r|--root <path>] [-f|--force] [--dry-run]
239
+ ai-i18n-tools status …
240
+ ai-i18n-tools statistics …
241
+ ai-i18n-tools cleanup …
242
+ ai-i18n-tools clean-temp …
243
+ ai-i18n-tools dashboard …
244
+ ai-i18n-tools generate-ui-languages [--master path] [--dry-run]
196
245
  ai-i18n-tools glossary-generate
246
+ ai-i18n-tools help [command]
197
247
  ```
198
248
 
199
249
 
200
250
  Complete per-command flag lists are in [Getting Started — CLI reference](docs/GETTING_STARTED.md#cli-reference). Run `ai-i18n-tools <command> --help` for built-in usage text.
201
251
 
202
- Global options on every command: `-c <config>` (default: `ai-i18n-tools.config.json`), `-v` (verbose), optional `-w` / `--write-logs [path]` to tee console output to a log file (default: under the translation cache directory), `-V` / `--version`, and `-h` / `--help`. See [Getting Started](docs/GETTING_STARTED.md#cli-reference) for the command overview table.
252
+ Global options on every command: `-c <config>` (default: `ai-i18n-tools.config.json`), `-v` (verbose), optional `-w` / `--write-logs [path]` to tee console output to a log file (default: under the translation cache directory), `-V` / `--version`, and `-h` / `--help`. Several commands accept `-l` / `--locale <codes>` (comma-separated BCP-47) to limit target locales; `lint-source` uses a single source locale. See [Getting Started](docs/GETTING_STARTED.md#cli-reference) for the command overview table.
203
253
 
204
254
  ---
205
255
 
206
256
  <a id="documentation"></a>
207
257
  ## Documentation
208
258
 
209
- - [Getting Started](docs/GETTING_STARTED.md) - full setup guide for both workflows, CLI reference, and config field reference.
259
+ - [Getting Started](docs/GETTING_STARTED.md) - full setup for all workflows (UI, docs/`.astro`, JSON bundles, Astro Starlight and plain Astro), CLI reference, and config field reference.
210
260
  - [Locale assets guide](docs/LOCALE-ASSETS-GUIDE.md) - screenshots and illustrated SVGs in translated docs (Patterns A–E, flat link rewriter, screenshot scripts).
211
261
  - [Package Overview](docs/PACKAGE_OVERVIEW.md) - architecture, internals, programmatic API, and extension points.
212
262
  - [AI Agent Context](docs/ai-i18n-tools-context.md) - **for apps using the package:** integration prompts for downstream projects (copy into your repo’s agent rules).
package/dist/build-info.generated.d.ts CHANGED
@@ -1,3 +1,3 @@
1
1
  /** Auto-generated by scripts/write-build-info.mjs — do not edit */
2
- export declare const BUILD_TIMESTAMP_ISO = "2026-05-24T19:52:06.081Z";
2
+ export declare const BUILD_TIMESTAMP_ISO = "2026-05-24T20:45:03.021Z";
3
3
  //# sourceMappingURL=build-info.generated.d.ts.map
package/dist/build-info.generated.js CHANGED
@@ -1,3 +1,3 @@
1
1
  /** Auto-generated by scripts/write-build-info.mjs — do not edit */
2
- export const BUILD_TIMESTAMP_ISO = "2026-05-24T19:52:06.081Z";
2
+ export const BUILD_TIMESTAMP_ISO = "2026-05-24T20:45:03.021Z";
3
3
  //# sourceMappingURL=build-info.generated.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-i18n-tools",
3
- "version": "1.5.0",
3
+ "version": "1.5.1",
4
4
  "packageManager": "pnpm@11.1.1",
5
5
  "description": "Unified internationalization toolkit for Node.js apps and documentation with AI translation",
6
6
  "type": "module",