ext-localize 0.0.0-stage → 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ext-localize contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,539 @@
1
- # Temporary Holding Version
1
+ # ext-localize
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Translate, check and keep in sync the `_locales/*/messages.json` files of a Chrome (Manifest V3) extension, and the store listing text for the Chrome Web Store, Firefox Add-ons and Edge Add-ons.
4
+
5
+ - **Local-first.** Runs on your machine. Bring your own API key, or use a local model with Ollama.
6
+ - **Only changed strings.** It remembers what it translated. The next run sends only new or changed keys.
7
+ - **Safe placeholders.** `$NAME$`, `$1`..`$9` and `$$` always survive translation.
8
+ - **CI check.** `ext-localize check` exits with an error when a locale would break or is incomplete.
9
+ - **Store listings.** Translate the name, summary and long description once, then deliver them: one PATCH to Firefox, one paste for Chrome, copy-ready files for Edge.
10
+
11
+ > **Package name:** `ext-localize`. It was free on npm when checked on 2026-11-16
12
+ > (`extlocal` is taken). Not published yet.
13
+
14
+ ## Quick start
15
+
16
+ 1. Go to your extension folder (the one with `manifest.json`). It needs `"default_locale"` and `_locales/<default>/messages.json`.
17
+ 2. See what would happen. This makes no API calls and writes nothing:
18
+ ```bash
19
+ npx ext-localize translate --to de,fr,ja --dry-run
20
+ ```
21
+ 3. Set a key and translate:
22
+ ```bash
23
+ export DEEPL_API_KEY=... # or ANTHROPIC_API_KEY / OPENAI_API_KEY
24
+ npx ext-localize translate --provider deepl --to de,fr,ja
25
+ ```
26
+ 4. Check every locale:
27
+ ```bash
28
+ npx ext-localize check
29
+ ```
30
+ 5. Commit `_locales/` and `.localizer/state.json`. Next time, just run `npx ext-localize translate --provider deepl`. With no `--to`, it uses the locale folders that already exist.
31
+ 6. Optional, the store listing: write `listing/en.json` (see [Store listing](#store-listing)), then:
32
+ ```bash
33
+ npx ext-localize translate --listing --provider deepl
34
+ npx ext-localize push chrome --copy # paste into the dashboard, click Save draft
35
+ npx ext-localize push firefox --addon my-addon # dry run; add --send to send
36
+ ```
37
+
38
+ Until the package is published, run it from this folder:
39
+
40
+ ```bash
41
+ npm install
42
+ node src/cli.ts translate --dir ../path/to/extension --to de --dry-run
43
+ ```
44
+
45
+ (Running `.ts` files directly needs Node 22.18+ or 23.6+. The built `dist/` targets Node 20+: it is compiled for ES2022 and uses no Node API newer than 20, and the Anthropic SDK supports Node 20. It has only been run on Node 26 so far.)
46
+
47
+ ## Commands
48
+
49
+ ### `translate`
50
+
51
+ ```
52
+ ext-localize translate --provider <name> [--to <locales>] [options]
53
+ ```
54
+
55
+ | Option | Meaning |
56
+ | --- | --- |
57
+ | `--provider` | `anthropic`, `openai`, `deepl` or `ollama` |
58
+ | `--listing` | Translate the store listing (`listing/<locale>.json`) instead of `_locales`. See [Store listing](#store-listing). |
59
+ | `--store` | With `--listing`: stores whose length limits apply, for example `chrome,firefox`. Default: `stores` in the config file, else `chrome`. |
60
+ | `--json` | Print a machine-readable result on stdout. Progress lines go to stderr. See [translate --json](#translate---json). |
61
+ | `--to` | `all` (all 55 Chrome locales) or a list like `de,fr,pt-BR`. Codes are normalised: `pt-BR` becomes `pt_BR`. Default: the locale folders that already exist. The default locale is never written. |
62
+ | `--model` | Model id. Anthropic default: `claude-opus-5-5`. Required for `openai` and `ollama`. |
63
+ | `--effort` | Anthropic only: `low`, `medium` (default), `high`, `xhigh`, `max` |
64
+ | `--formality` | `default`, `more`, `less`, `prefer_more`, `prefer_less`. Formal or informal tone (German "Sie" or "du"). See [Formality](#formality). |
65
+ | `--glossary` | Glossary file. Default: `.localizer/glossary.json` if it exists. |
66
+ | `--dry-run` | Show what would be translated, the request count and a rough size. No API calls, no writes. |
67
+ | `--force` | Re-translate every key, even unchanged ones. |
68
+ | `--batch-size` | Max strings per request. |
69
+ | `--concurrency` | Locales translated at the same time (default 4). |
70
+ | `--dir` | Extension folder (default: current folder). |
71
+
72
+ Exit code: `0` when every string was translated, `1` when some failed (they are listed) or the run stopped, `2` for usage or setup errors, `3` when there are no target locales. See [Exit codes](#exit-codes).
73
+
74
+ **Files `translate` may write** (nothing else, except the generated `.localizer/out/` of the `push` commands):
75
+
76
+ | Command | Files |
77
+ | --- | --- |
78
+ | `translate` | `_locales/<locale>/messages.json` (never the default locale), `.localizer/state.json` |
79
+ | `translate --listing` | `<listing dir>/<locale>.json` (default `listing/`; never the source file), `.localizer/state.json` |
80
+
81
+ A file is only rewritten when its content changes. `--json` lists the files actually written in `filesWritten`, and this list as patterns in `mayWrite`. DeepL glossaries are created on your DeepL account, not as files.
82
+
83
+ #### `translate --json`
84
+
85
+ ```json
86
+ {
87
+ "command": "translate",
88
+ "target": "messages",
89
+ "dryRun": false,
90
+ "provider": "deepl",
91
+ "exitCode": 1,
92
+ "ok": false,
93
+ "noTargets": false,
94
+ "stopped": null,
95
+ "locales": [
96
+ {
97
+ "locale": "de",
98
+ "new": 2, "changed": 1, "invalid": 0, "forced": 0, "removed": 1, "kept": 22,
99
+ "adopted": 0, "manual": 0, "translated": 2, "failed": 1, "requests": 1,
100
+ "skipped": null,
101
+ "failedKeys": [{ "key": "actionTitle", "error": "marker 0 ($count$) is missing" }],
102
+ "written": ["_locales/de/messages.json"]
103
+ }
104
+ ],
105
+ "totals": { "strings": 3, "requests": 1, "characters": 120, "failed": 1 },
106
+ "filesWritten": [".localizer/state.json", "_locales/de/messages.json"],
107
+ "mayWrite": ["_locales/<locale>/messages.json", ".localizer/state.json"],
108
+ "check": { "errors": 0, "warnings": 2, "stale": 0 }
109
+ }
110
+ ```
111
+
112
+ | Field | Meaning |
113
+ | --- | --- |
114
+ | `target` | `messages`, or `listing` with `--listing` |
115
+ | `noTargets` | `true` when there was nothing to translate into (exit code 3) |
116
+ | `stopped` | `null`, or why the run stopped early (bad key, quota, 3 failures in a row) |
117
+ | `locales[].new` … `kept` | Same as the text table. `new` includes keys missing from a locale file. `adopted`/`manual`: kept keys that existed before the first run / were edited by hand. |
118
+ | `locales[].skipped` | `null`, or why the locale was not translated (for example the provider does not support it) |
119
+ | `locales[].failedKeys` | Every key that was not written, with the reason |
120
+ | `check` | Counts of a `check` run after translating (`null` for `--dry-run` or no targets) |
121
+
122
+ When the command fails with an error before it can produce a result (usage or setup error, exit 2; or, for example, a missing API key, exit 1), `--json` prints `{"command", "exitCode", "ok": false, "error"}` instead.
123
+
124
+ Example dry run:
125
+
126
+ ```
127
+ locale new changed invalid forced removed kept requests note
128
+ de 2 1 0 0 1 22 1
129
+ fr 25 0 0 0 0 0 1
130
+
131
+ Dry run: 28 string(s) to translate in 2 locale(s), about 2 request(s) to deepl, about 1190 characters billed.
132
+ Nothing was written.
133
+ ```
134
+
135
+ ### `check`
136
+
137
+ ```
138
+ ext-localize check [--dir <path>] [--json] [--strict] [--store chrome,firefox,edge] [--stale warning|error|off]
139
+ ```
140
+
141
+ Exit code `1` on any error. `--strict` also fails on warnings. `--json` prints a machine-readable report:
142
+
143
+ ```json
144
+ {
145
+ "defaultLocale": "en",
146
+ "locales": ["de", "en"],
147
+ "issues": [
148
+ {
149
+ "level": "warning",
150
+ "kind": "stale",
151
+ "locale": "de",
152
+ "key": "actionTitle",
153
+ "message": "source changed after translation (by deepl); run \"ext-localize translate\" to update",
154
+ "file": "_locales/de/messages.json",
155
+ "line": 12
156
+ }
157
+ ],
158
+ "errors": 0,
159
+ "warnings": 1,
160
+ "stale": 1,
161
+ "staleCheck": { "mode": "warning", "status": "ok", "stale": 1, "untracked": 0, "note": "1 translated string(s) are older than their source text." }
162
+ }
163
+ ```
164
+
165
+ - Every issue has `level`, `locale` (`null` for the manifest or the state file), `message` and `file` (relative to `--dir`, `/` separators). `key` is set when the issue is about one key; listing keys look like `listing.name`. `line` (1-based) is set when it can be found: the key's line, the `__MSG_key__` line in `manifest.json`, or the line of a JSON syntax error. A missing key has no line. (For `manifest.json` with block comments, a syntax-error line may be off.)
166
+ - `kind` is set only by the stale check: `"stale"` for one stale string, `"state"` when `.localizer/state.json` cannot be used.
167
+ - `errors` and `warnings` count all issues, stale ones included. `stale` counts issues with `kind: "stale"`.
168
+ - A project without a `listing/` folder gets no listing issues.
169
+
170
+ **Stale strings.** A translation is stale when its source text (or placeholders) changed after it was translated: the `sourceHash` in `.localizer/state.json` no longer matches the source. This is the same test `translate` uses for its `changed` column, so `translate` fixes exactly these. Listing fields are checked the same way (and fixed by `translate --listing`), except name and summary copied from `_locales`: those are re-copied on every `translate --listing` run, so only their `_locales` message can be stale.
171
+
172
+ | `--stale` | Effect |
173
+ | --- | --- |
174
+ | `warning` (default) | Stale strings are warnings. `check` still exits 0 unless `--strict`. The default keeps old CI setups passing. |
175
+ | `error` | Stale strings are errors (exit 1). An unreadable state file or an unknown state version is also an error. |
176
+ | `off` | Not checked. |
177
+
178
+ `staleCheck.status` says what happened: `ok`, `off`, `no-state` (no state file: nothing checked, no issue), `bad-state` / `unknown-version` (issue with kind `state`), `source-locale-changed` (warning; the next `translate` resets the state), `no-source`. `untracked` counts translated keys that have no state entry (written before the tool was used), whose age is unknown. A key that is stale **and** has broken placeholders is reported twice: as stale, and as a placeholder error (`translate` plans it as `invalid`).
179
+
180
+ `--store` picks whose listing limits apply (default: `stores` in the config file, else `chrome`). See [Listing checks](#listing-checks).
181
+
182
+ **Errors** (Chrome breaks, or the locale is incomplete):
183
+
184
+ - `messages.json` does not parse. Chrome drops that locale silently.
185
+ - A locale folder has no `messages.json`. Chrome refuses to load the extension.
186
+ - `_locales/` exists but the manifest has no `default_locale`, or the default locale folder is missing.
187
+ - A source key is missing, or a key is not in the source (extra key).
188
+ - The placeholder set of a message differs from the source: `$name$` (case-insensitive) or `$1`..`$9`.
189
+ - A `$name$` is used but not defined in that file's own `placeholders` block.
190
+ - Keys starting with `@@` (reserved by Chrome).
191
+ - Key names with characters other than `A-Z a-z 0-9 _ @`, or two keys that differ only in case.
192
+ - Empty messages, or entries without a `message` string.
193
+ - The manifest uses `__MSG_key__` but the key is missing from the default locale.
194
+
195
+ **Warnings:**
196
+
197
+ - RTL locales (`ar`, `he`, `fa`): a message with letters but no right-to-left letters (maybe untranslated).
198
+ - Localized manifest `name` over 75, `short_name` over 12, or `description` over 132 characters.
199
+ - The number of `$$` (literal dollar) differs from the source, or a new stray `$` appears. A human may do this on purpose (for example "4,99 €"), so it is only a warning. Machine translations with this problem are never written.
200
+ - Unknown locale folder names, a byte order mark (BOM), unused placeholders in the source, a stray `$` in the source.
201
+
202
+ Use it in CI:
203
+
204
+ ```yaml
205
+ - run: npx ext-localize check
206
+ ```
207
+
208
+ ## Providers
209
+
210
+ API keys are read from environment variables only. They are never written to disk.
211
+
212
+ | Provider | Key | Notes |
213
+ | --- | --- | --- |
214
+ | `anthropic` | `ANTHROPIC_API_KEY` (or an `ant auth login` profile) | Official SDK. Default model `claude-opus-5-5`. Use `--model claude-sonnet-5-5` or `--model claude-haiku-5-5` for lower cost. JSON output is enforced with a schema. Server-side refusal fallback is on. The SDK retries rate limits. |
215
+ | `openai` | `OPENAI_API_KEY` | Chat Completions with a strict JSON schema. Pass `--model` (or `OPENAI_MODEL`); there is no default. Set `OPENAI_BASE_URL` to use any OpenAI-compatible server, for example LM Studio or vLLM on your machine. |
216
+ | `deepl` | `DEEPL_API_KEY` | Keys ending in `:fx` use the free API host. For listing text, each line is sent as its own text (in XML mode DeepL does not treat a line break as a sentence end, so list items could merge); blank lines and indentation are kept locally. UI messages are sent whole. Supported languages are read from DeepL, and unsupported locales are skipped with a note (for example `am` and `kn` today; `--dry-run` does not know this yet and counts them). DeepL has one `context` per request, so descriptions are sent there only as loose background, each quoted with its source text. Supports `--formality` and glossary `terms` (see below). |
217
+ | `ollama` | none | Local model, nothing leaves your machine. Pass `--model` (see `ollama list`). `OLLAMA_HOST` defaults to `http://localhost:11434`. Smaller batches. |
218
+
219
+ **What is sent:** the message text (with placeholders replaced by markers), its `description`, notes about what each placeholder means (with the `example`), and the glossary terms for that locale. Nothing else from your extension is sent.
220
+
221
+ **Batching and retries:** many keys go in one request (40 for LLMs, 50 for DeepL, 15 for Ollama). Rate limits (HTTP 429) and server errors are retried with backoff, and `Retry-After` is respected. If an answer is cut off, the batch is split in two and sent again. Keys that come back missing or with broken placeholders are re-sent one by one; if they still fail, they are not written and are listed in the output. A request that fails on the network or HTTP level (after retries) is not re-sent key by key. The run stops at once on an auth error (401/403), a wrong model or URL (404) or DeepL quota (456), and after 3 failed requests in a row. Finished locales are kept.
222
+
223
+ **Adding a provider:** implement the `Provider` interface in `src/providers/types.ts` (`translateBatch` gets a list of `{key, text, description}` and returns `key -> text`), then register it in `src/providers/index.ts`.
224
+
225
+ ## How placeholders are protected
226
+
227
+ Before sending, every Chrome format token is replaced by a marker:
228
+
229
+ ```
230
+ Saved $count$ tabs to "$session_name$" for $$4.99
231
+ Saved <x id="0"/> tabs to "<x id="1"/>" for <x id="2"/>4.99
232
+ ```
233
+
234
+ After translation, the markers are replaced back. Each marker must appear exactly once. Then the result is checked again against the source (same placeholders, same `$$` count, no new stray `$`). A string that fails is never written.
235
+
236
+ Tokens are read left to right and `$$` is tried first, so `$$1` is a literal `$` followed by `1`.
237
+
238
+ The `placeholders` blocks are copied from the source unchanged.
239
+
240
+ ## Only changed strings: the diff state
241
+
242
+ `translate` stores a hash of every source message in `.localizer/state.json`, per locale. On the next run, for each locale and key:
243
+
244
+ | Situation | What happens |
245
+ | --- | --- |
246
+ | Key is not in the locale file | translated (`new`) |
247
+ | Locale message is broken (empty, or the placeholder set differs) | translated again (`invalid`) |
248
+ | Source text or placeholders changed since the last translation | translated again (`changed`) |
249
+ | Key is in the locale file but not in the state (first run on an existing project) | **kept**, and recorded as `adopted`. Existing translations are never overwritten on the first run. Use `--force` to re-translate. |
250
+ | Translation was edited by hand since we wrote it | kept, recorded as `manual` |
251
+ | Key was deleted from the source | removed from the locale file |
252
+ | Otherwise | kept |
253
+
254
+ Editing only a `description` does not trigger re-translation.
255
+
256
+ State is written after each locale finishes. If a run stops in the middle, the finished locales are saved and the next run continues with the rest.
257
+
258
+ ### State file format
259
+
260
+ `.localizer/state.json` (version 1). Keys are sorted so the file diffs cleanly. Commit it.
261
+
262
+ ```json
263
+ {
264
+ "version": 1,
265
+ "sourceLocale": "en",
266
+ "locales": {
267
+ "de": {
268
+ "messages": {
269
+ "extName": {
270
+ "sourceHash": "3332…0843",
271
+ "targetHash": "9c0f…1a06",
272
+ "by": "deepl"
273
+ }
274
+ }
275
+ }
276
+ }
277
+ }
278
+ ```
279
+
280
+ | Field | Meaning |
281
+ | --- | --- |
282
+ | `version` | Format version. Tools must refuse versions they do not know. |
283
+ | `sourceLocale` | The `default_locale` the hashes were made from. If it changes, the state is reset. |
284
+ | `locales.<locale>.listing.<field>` | Optional (added in 0.2, still version 1). Same three fields per listing field (`name`, `summary`, `description`). The hashes are made the same way, with an empty placeholder list. `by` may also be `_locales` (copied from `_locales`, not translated). Tools that do not know `listing` can ignore it. |
285
+ | `locales.<locale>.messages.<key>.sourceHash` | SHA-256 (hex) of `JSON.stringify({message, placeholders})`, where `placeholders` is a list of `[name in lower case, content]` pairs sorted by name. The description is not included. |
286
+ | `…targetHash` | SHA-256 (hex) of the translated `message` string as written. If the file's text no longer matches, someone edited it by hand. |
287
+ | `…by` | Who wrote the text: `deepl`, `anthropic/<model>`, `openai/<model>`, `ollama/<model>`, `adopted` (existed before the first run) or `manual` (edited by hand). |
288
+
289
+ A key with no entry has never been translated by this tool.
290
+
291
+ ## Glossary
292
+
293
+ `.localizer/glossary.json`:
294
+
295
+ ```json
296
+ {
297
+ "keep": ["TabNest", "Chrome", "Pro"],
298
+ "terms": {
299
+ "workspace": { "de": "Arbeitsbereich", "fr": "espace de travail" }
300
+ }
301
+ }
302
+ ```
303
+
304
+ - `keep`: words that must never be translated (brand and product names). They are protected like placeholders, so every provider keeps them. Matching is case-sensitive and whole-word.
305
+ - `terms`: a fixed translation per locale.
306
+ - LLM providers get them as instructions in the prompt.
307
+ - DeepL gets a real DeepL glossary, so the terms are enforced. ext-localize creates one glossary per target locale on your DeepL account, named `ext-localize en->de <hash>`. The hash comes from the terms, so the same terms reuse the same glossary, and a new one is made only when the terms change. Old glossaries are **not** deleted; remove them in your DeepL account if you change terms often (the limit is 1000 glossaries per account).
308
+ - DeepL rejects empty terms, tabs or line breaks inside a term, and duplicate source terms. Those are dropped with a note. Thai cannot use glossaries; you get a note and the terms are not applied.
309
+
310
+ ## Formality
311
+
312
+ `--formality` sets the tone and form of address, for example German "Sie" (formal) or "du" (informal).
313
+
314
+ | Value | DeepL | LLM providers |
315
+ | --- | --- | --- |
316
+ | `more` / `less` | Sent only to languages that support it (today: German, Spanish, French, Italian, Japanese, Dutch, Polish, Portuguese, Russian). Other locales use the default, with a note. | "Tone: formal" / "Tone: informal" in the prompt |
317
+ | `prefer_more` / `prefer_less` | Always sent. DeepL uses it where it can and falls back by itself. | same as `more` / `less` |
318
+ | `default` (or no flag) | DeepL's default | no tone line |
319
+
320
+ Example:
321
+
322
+ ```bash
323
+ npx ext-localize translate --provider deepl --to de,fr,ar --formality more
324
+ # ar: formality "more" is not supported for AR; using the default
325
+ # de: created DeepL glossary "ext-localize en->de 965861d7c05511be" (3 terms)
326
+ ```
327
+
328
+ Changing `--formality` or the glossary does not re-translate existing strings by itself (only source changes do). Add `--force` once to apply the new tone or terms to everything.
329
+
330
+ ## Exit codes
331
+
332
+ | Code | `translate` | `check` | `push` |
333
+ | --- | --- | --- | --- |
334
+ | `0` | every string written (or `--dry-run`) | no errors (and no warnings with `--strict`) | done (dry run, files written, or sent) |
335
+ | `1` | some strings failed, or the run stopped early (also a missing API key) | errors found | errors in the listing, the send failed, or `--auto` did not finish cleanly |
336
+ | `2` | usage error, bad config file, or the extension or listing cannot be loaded | usage error or bad config file | usage error, missing env vars for `--send`, or the listing cannot be loaded |
337
+ | `3` | no target locales (use `--to`, or create locale folders) | – | – |
338
+
339
+ ## Store listing
340
+
341
+ The listing pack is one JSON file per locale in `listing/` next to `manifest.json`:
342
+
343
+ ```
344
+ listing/en.json source (the default_locale), written by you
345
+ listing/de.json written by "translate --listing"
346
+ listing/pt_BR.json file names are Chrome locale codes
347
+ ```
348
+
349
+ Every file has the same shape (the same contract the store tools use):
350
+
351
+ ```json
352
+ { "name": "TabNest", "summary": "Save and restore tabs.", "description": "Long text..." }
353
+ ```
354
+
355
+ In the **source file only**, `description` may also be an array of lines. They are joined with line breaks. This is easier to edit and gives clean git diffs. Keep one sentence on one line: DeepL translates each line on its own, so a sentence split over two lines is translated as two pieces.
356
+
357
+ ```json
358
+ {
359
+ "description": [
360
+ "TabNest saves your tabs.",
361
+ "",
362
+ "- Save all open tabs as a session",
363
+ "- Restore them later"
364
+ ]
365
+ }
366
+ ```
367
+
368
+ **Name and summary stay in sync with `_locales`.** On Chrome, the store name and summary come from the manifest. When `manifest.json` uses `"name": "__MSG_extName__"` (or `"description": "__MSG_extDescription__"`):
369
+
370
+ - the source file may leave out `name` (or `summary`); it is read from `_locales/<default>/messages.json`;
371
+ - `translate --listing` copies the name and summary of each locale from `_locales/<locale>/messages.json`. They are not translated a second time (recorded as `"by": "_locales"`). Only when that locale has no `_locales` folder yet are they translated;
372
+ - `check` warns when a listing name or summary differs from `_locales`.
373
+
374
+ So run `translate` (messages) first, then `translate --listing`.
375
+
376
+ **Translating.** `translate --listing` uses the same providers, glossary, formality and diff state as messages. Only changed fields are sent again. With no `--to`, it uses the existing `_locales` folders and listing files. The rules differ a little from messages:
377
+
378
+ - `$` has no meaning in listing text. `$4.99` is plain text, and a hand edit like `4,99 €` is kept (not marked broken). Glossary `keep` terms are still protected.
379
+ - LLMs get a listing prompt (keep paragraphs, line breaks and list markers; natural marketing text; no added claims) and the length limit of each field.
380
+ - A translation longer than the limit of your stores is not written; it is listed as failed.
381
+ - A description too long for one model answer fails for that locale only and does not stop the run.
382
+
383
+ ### Listing checks
384
+
385
+ `check` validates `listing/` when the folder exists:
386
+
387
+ | Level | Rule |
388
+ | --- | --- |
389
+ | error | No source file `listing/<default_locale>.json`, a file that does not parse, a file name that is not a Chrome locale code, a field that is not a string, a missing or empty field |
390
+ | error | Over a store limit (characters, counted as Unicode code points) for the chosen stores |
391
+ | warning | Name or summary differs from `_locales` (when the manifest uses `__MSG_`) |
392
+ | warning | Unknown fields |
393
+ | warning | Firefox: `#` heading lines in the description (AMO drops Markdown headings), a URL in the summary |
394
+ | warning | Edge: description shorter than 250 characters |
395
+
396
+ | Store | name | summary | description |
397
+ | --- | --- | --- | --- |
398
+ | `chrome` | 75 | 132 | 16,000 (the dashboard field's `maxlength`; not in Google's docs) |
399
+ | `firefox` | 50 | 250 | 15,000 (AMO returns HTTP 400 above these) |
400
+ | `edge` | from the manifest | from the manifest | 250 to 10,000 (Partner Center) |
401
+
402
+ ## Delivering the listing to the stores
403
+
404
+ ### `push firefox` (Firefox Add-ons, real API)
405
+
406
+ ```bash
407
+ ext-localize push firefox --addon <id|slug|guid> # dry run: prints the request
408
+ AMO_JWT_ISSUER=... AMO_JWT_SECRET=... ext-localize push firefox --addon my-addon --send
409
+ ```
410
+
411
+ - **Dry run is the default.** It prints the `PATCH` URL, the JSON body, which listing file fed each AMO locale, and the locales that **cannot be sent**. A real send needs `--send` **and** both `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` (create them at https://addons.mozilla.org/en-US/developers/addon/api/key/). The secret is never printed or written.
412
+ - One `PATCH /api/v5/addons/addon/<id>/` sets `name`, `summary` and `description` for all locales. Locales you do not send are not changed.
413
+ - AMO accepts only 44 locales today. Of the 55 Chrome locales, 33 map and 22 are skipped with a reason (for example `ar`, `bg`, `id`, `hi`, `th`, `fil`, `en_AU`). `es_419` is copied to `es-AR`, `es-CL` and `es-MX`; `no` goes to `nb-NO`. Use `--extra-locales` if AMO adds more.
414
+ - Any error (too long, empty, two files for one AMO locale) stops the send before any request.
415
+ - `--remove de,fr` also deletes those AMO locales (sends `null`). The AMO default locale can never be removed; it is taken from `default_locale` (`en` becomes `en-US`), or set it with `--default-locale`.
416
+ - Changing `name` or `summary` starts an AMO content review. The new text is saved at once and reviewed later.
417
+ - The description is Markdown on AMO: `- item` lists become real lists, `# headings` are dropped.
418
+
419
+ ### `push chrome` (one paste, the default)
420
+
421
+ Chrome has no API for listing text. Name and summary come from your manifest (`_locales`). Only the "Detailed description" is typed per language in the dashboard.
422
+
423
+ ```bash
424
+ ext-localize push chrome --copy
425
+ ```
426
+
427
+ This writes `.localizer/out/chrome-paste.js` (and a read-only `chrome-diagnose.js`) and, with `--copy`, puts the script on the macOS clipboard. Then:
428
+
429
+ 1. In Chrome, open the Developer Dashboard, your item, and its "Store listing" tab.
430
+ 2. Open the DevTools console: Cmd+Option+J.
431
+ 3. Paste and press Enter. The first time, Chrome may ask you to type `allow pasting`.
432
+ 4. The script switches to each language, fills the description, then checks every language again and prints a report.
433
+ 5. Look at a few languages, then click **Save draft** yourself.
434
+
435
+ The script never clicks Submit for review or Publish. Use `--mode save-each` if the dashboard ever drops unsaved text when you switch language (then the script waits for your Save draft click after each language). `.localizer/out/` gets its own `.gitignore`.
436
+
437
+ ### `push chrome --auto` (EXPERIMENTAL)
438
+
439
+ > **Warning.** `--auto` drives the Chrome Web Store dashboard from a script over the Chrome DevTools Protocol. **Google has not confirmed that this is allowed.** The Developer Agreement (section 4.4.2) forbids access "by any means other than through the interface", and it is unclear whether a script that clicks the same interface counts. **Your publisher account is what is at risk.** The default above (one paste, you click Save) is the lower-risk way. Every `--auto` run prints this warning.
440
+
441
+ The spike this is ported from worked on a real test item (fill 16 languages, Save draft, reload, read back, a 15,000-character text). This CLI port has only run against a local mock of the dashboard so far. It needs Playwright, which is **not** installed by default:
442
+
443
+ ```bash
444
+ npm install playwright-core # uses your installed Google Chrome, no browser download
445
+ ```
446
+
447
+ Steps:
448
+
449
+ 1. Sign in once in a separate Chrome profile (Chrome blocks automation of your everyday profile):
450
+ ```bash
451
+ ext-localize push chrome --auto --login # opens plain Chrome on ~/.ext-localize/chrome-profile; sign in, then quit it
452
+ ```
453
+ 2. Fill only (nothing is saved; reload the page to undo):
454
+ ```bash
455
+ ext-localize push chrome --auto --item <32-letter item id>
456
+ ```
457
+ 3. Fill, save and check:
458
+ ```bash
459
+ ext-localize push chrome --auto --item <id> --save
460
+ ```
461
+
462
+ Guards:
463
+
464
+ - `--item` is required, and the tool only touches a tab that shows that item (on `chrome.google.com` or `chromewebstore.google.com`). If no tab shows it, a window opens and waits for you to open the item.
465
+ - It never clicks Publish or Submit for review. It clicks only one button named exactly "Save draft", and only with `--save`.
466
+ - **Every item counts as live** unless you list it in `chrome.testItems` in the config file. Saving on any other item also needs `--allow-live`.
467
+ - After saving, it reloads the page and reads every language back. The exit code is `1` if anything differs.
468
+ - A report goes to `.localizer/out/chrome-auto-<date>.json`. Network traffic is never recorded (the save request carries session tokens).
469
+ - `--browser port:9222` attaches to a Chrome you started with `--remote-debugging-port=9222 --user-data-dir=<separate folder>` instead. Quit that Chrome after the run: while the port is open, any program on your Mac can control it.
470
+
471
+ ### `push edge` (copy-ready files)
472
+
473
+ Edge has no API for listing text, so this writes `.localizer/out/edge/<locale>.txt` with the description of each locale, and `--print` prints copy-ready blocks. In Partner Center, open the extension, "Store listings", pick each language and paste. The extension name and short description are read from the manifest there, so they are not in these files. Descriptions under 250 or over 10,000 characters are reported (exit code `1`). How Partner Center names each language is not documented; match by language name.
474
+
475
+ ## Config file
476
+
477
+ Flags get long, so defaults can go in `.localizer/config.json`. Flags always win. Unknown keys are an error (so a typo does not silently do nothing).
478
+
479
+ ```json
480
+ {
481
+ "provider": "deepl",
482
+ "model": "claude-opus-5-5",
483
+ "effort": "medium",
484
+ "formality": "prefer_more",
485
+ "to": ["de", "fr", "pt-BR"],
486
+ "glossary": ".localizer/glossary.json",
487
+ "stores": ["chrome", "firefox"],
488
+ "listing": { "dir": "listing" },
489
+ "firefox": { "addon": "my-addon", "defaultLocale": "en-US", "extraLocales": [], "host": "https://addons.mozilla.org" },
490
+ "chrome": { "item": "<32-letter id>", "publisher": "<publisher id>", "testItems": ["<id>"], "browser": "launch", "profile": "~/.ext-localize/chrome-profile" }
491
+ }
492
+ ```
493
+
494
+ | Key | Used by | Meaning |
495
+ | --- | --- | --- |
496
+ | `provider`, `model`, `effort`, `formality`, `to` | `translate` | Same as the flags. `to` may be a string or a list. |
497
+ | `glossary` | `translate` | Path relative to the extension folder. |
498
+ | `stores` | `check`, `translate --listing` | Whose listing limits apply. Default `["chrome"]`. |
499
+ | `listing.dir` | all listing commands | Default `listing`. |
500
+ | `firefox.*` | `push firefox` | Add-on id, AMO default locale, extra accepted locales, host (for example the stage server). |
501
+ | `chrome.item`, `chrome.publisher` | `push chrome --auto` | Item id; with the publisher id the tool opens the item page itself. |
502
+ | `chrome.testItems` | `push chrome --auto --save` | Items you may save on without `--allow-live`. |
503
+ | `chrome.browser`, `chrome.profile` | `push chrome --auto` | `launch` or `port:<n>`; profile folder for `launch`. |
504
+
505
+ Keys (API keys, AMO secrets) never go in this file. They are read from the environment only.
506
+
507
+ ## Sample extension
508
+
509
+ `fixtures/sample-extension/` is a small realistic extension (a tab manager) with 25 messages. It has named and positional placeholders, `$$` prices, descriptions, a line break, comments in `manifest.json`, a glossary, a source listing (`listing/en.json`, description as lines, name and summary from `_locales`) and a config file. Try:
510
+
511
+ ```bash
512
+ node src/cli.ts translate --dir fixtures/sample-extension --to all --dry-run
513
+ node src/cli.ts translate --listing --dir fixtures/sample-extension --to de,fr --dry-run
514
+ node src/cli.ts check --dir fixtures/sample-extension --store chrome,firefox,edge
515
+ node src/cli.ts push firefox --dir fixtures/sample-extension
516
+ ```
517
+
518
+ ## Development
519
+
520
+ ```bash
521
+ npm install
522
+ npm test # node:test, no API calls (providers and AMO are mocked)
523
+ npm run typecheck
524
+ npm run build # writes dist/ (npm pack runs it too, via "prepack")
525
+ ```
526
+
527
+ The Chrome tests run the paste script and `--auto` against a local mock of the dashboard (`test/chrome-mock/`, a React page that copies only what makes automation hard). They need Google Chrome in `/Applications` and the `playwright-core` dev dependency; otherwise they are skipped.
528
+
529
+ ## Not done yet
530
+
531
+ - Tested live only with DeepL, and only for `_locales` messages. The Anthropic, OpenAI and Ollama providers are covered by unit tests with mocks, but have not been run against the real APIs yet. Listing translation (long descriptions, line-by-line DeepL) has only run against mocks.
532
+ - `push firefox --send` has never sent a real PATCH. The request shape comes from AMO's docs, source code and tests; the first real run should be on a test add-on.
533
+ - `push chrome --auto` in this CLI has only run against the local mock. The code is a port of the spike that worked on a real test item. Google has not answered whether it is allowed, so it stays experimental.
534
+ - The paste script is the spike's fixed version that worked on the real dashboard (16 languages, matched by language code); a later dashboard change can break it, and it fails loudly when it does.
535
+ - No screenshots: per-language store images are not handled.
536
+ - Edge: how Partner Center names languages is not documented, so files are named by Chrome code.
537
+ - `--dry-run` does not know which locales DeepL or AMO will skip, and counts them.
538
+ - `dist/` has not been run on a real Node 20 yet (checked by compiler settings and a code scan only).
539
+ - The GitHub Action (`action/`) and the sync service are separate work.