claude-translator 1.3.0 → 2.0.0

package/README.md

@@ -8,13 +8,14 @@ static pages — without re-rendering it, and without breaking Core Web Vitals.*
 [![Claude Skill](https://img.shields.io/badge/Claude-Skill-8A63D2.svg)](#using-it-as-a-claude-code-skill)
 
 Point it at a built site, give it a list of locales and your own model API key, and it
-produces a complete localized copy of every page — with correct `hreflang`, canonicals,
-`dir="rtl"`, per-locale JSON-LD and sitemaps — then proves the result with six gates and a
-full SEO audit.
+produces a complete localized copy of every page — correcting `hreflang`, canonicals,
+`dir="rtl"` and per-locale JSON-LD as it goes — then proves the result with eight gates and
+a full SEO audit. It holds your terminology, protects your brand names, and writes numbers
+the way each locale writes them.
 
 Built and maintained by **[ConveyThis](https://www.conveythis.com/open-source/claude-translator?utm_source=claude-skill&utm_medium=readme-byline&utm_campaign=claude-translator)**.
 This is the pipeline that runs **www.conveythis.com itself** — a 238-page Astro site,
-live in 55 languages, on the same six scripts in this repo.
+live in 55 languages, on the same scripts in this repo.
 
 > Not affiliated with or endorsed by Anthropic. "Claude" is a trademark of Anthropic, PBC.
 > This project is named for the model family it ships configured to use; it works just as
@@ -121,7 +122,8 @@ against each other rather than against a number in a README.
 
 > This project ships **no API key and makes no calls on your behalf**. Your key is read
 > from your environment, used to call your chosen provider directly from your machine, and
-> never transmitted anywhere else. There is no telemetry.
+> never transmitted anywhere else. There is no telemetry — see [PRIVACY.md](PRIVACY.md),
+> which shows how to verify that against the source.
 
 ---
 
@@ -144,8 +146,9 @@ npm run build                                        # your normal build
 node scripts/i18n/extract.mjs                        # find translatable units
 node scripts/i18n/translate.mjs --lang es,fr,de      # translate (uses your key)
 node scripts/i18n/build-locales.mjs --lang all       # write localized pages
-node scripts/i18n/verify.mjs --lang all              # six gates
+node scripts/i18n/verify.mjs --lang all              # eight gates
 node scripts/i18n/audit-seo.mjs                      # full SEO audit
+node scripts/i18n/tqa.mjs --lang es                  # MQM quality score (optional)
 ```
 
 Deploy the resulting build directory exactly as you deploy it today.
@@ -215,6 +218,8 @@ read, and this is AGPL software whose point is that you can change them.
 | `pages.source` | `"build"` to derive from output, or a path to a slug list |
 | `pages.exclude` | First path segments never to localize — 404 pages, CMS admin shells |
 | `doNotTranslate` | Brand names and formats that must survive unchanged |
+| `glossary` | Term base — an array, or a path to a JSON file. See [Terminology](#terminology-and-brand-names) |
+| `localeFormat` | Number, percent and currency **formatting**. See [Numbers and money](#numbers-and-money) |
 | `provider` | `anthropic` (default), `gemini`, `openai`, or a path to your own adapter |
 | `model` | Any model id for that provider — defaults to the provider's own |
 | `apiBaseUrl` | Model API host. Set this for local models, Azure or a gateway. **Not** `baseUrl`, which is your site |
@@ -228,24 +233,163 @@ read, and this is AGPL software whose point is that you can change them.
 
 ## What you get
 
-For every page, in every locale:
+**Read this section as "corrected", not "created".** With one exception, this tool does not
+add tags to your pages — it rewrites the values on tags your template already emits. That is
+deliberate: inserting markup would break the byte-identical guarantee that
+[Does it hold?](#does-it-hold) rests on. It also means **your template has to emit the tags
+in the first place**, and the two lists below are the difference between what we fix and
+what you must supply.
+
+### Rewritten for you, on every page, in every locale
+
+- `<html lang>`, and `dir` flipped to `rtl` where the script requires it — the `lang` and
+  `dir` **attributes must already be present** on `<html>`; the value is replaced, never added
+- The canonical `href` → this locale's page, `https`, no trailing slash
+- The `x-default` and source-language `hreflang` hrefs → pointed at the **original** page,
+  not at self. These two are the ones people get wrong; they are also **the only two
+  `hreflang` links this tool touches**
+- `og:url` / `og:locale` `content` values
+- JSON-LD `@id`, `url` and `inLanguage`, per locale — with `Organization` left alone,
+  because a company is one entity in every language, and anything unparseable returned
+  byte-for-byte
+- Internal links, locale-prefixed — assets and anchors left alone
+- Your language picker's current-language label and `aria-current`, if it ships the
+  `data-i18n-current-lang` / `data-i18n-lang` markers
+
+The only thing ever *inserted* is the ~150-byte attribution described under
+[Attribution](#attribution), and you can turn it off.
+
+### Your template must supply these — we audit them, we do not generate them
+
+- **The full `hreflang` mesh.** One `<link rel="alternate">` per locale, plus `x-default`
+  and the source language. We rewrite two of those hrefs and check all of them; we emit
+  none of them. A site with no alternates gets no alternates.
+- **`sitemap.xml`, and any per-locale sitemaps it indexes.** `audit-seo.mjs` validates that
+  every sitemap lists the right URLs, that they are `https`, and that each resolves to a
+  built page — but nothing in this repo writes a sitemap file.
+- **`robots.txt`.** Never read, never written.
+- **`og:image`, `twitter:card`, `twitter:site`.** Left untouched. The *text* fields
+  (`og:title`, `og:description`, `twitter:title`, image `alt`) are translated.
+
+**Nothing here fails silently.** Every rewrite rule reports when it matched nothing, so a
+template change turns into a printed miss rather than a quiet no-op, and `audit-seo.mjs`
+checks the whole mesh on *every* page rather than a sample. If your template is missing the
+alternates, you will hear about it on the first run — see
+[`references/adapting-generators.md`](skills/translate-site/references/adapting-generators.md).
+
+## Terminology and brand names
+
+Two different problems, one file.
+
+**Consistency.** Identical strings are already consistent for free: units are keyed by the
+hash of the source text, so a header translated once is reused on every page and across
+runs. What that cannot do is hold a *term inside varying sentences* — "Dashboard" in two
+different paragraphs is two different units, in two different batches, in two stateless
+requests. A glossary fixes that.
+
+**Sense.** `Apple` the company must survive; `apple` the fruit must be translated. A flat
+list of names cannot express the difference.
 
-- `<html lang>` and `dir="rtl"` where the script requires it
-- A self-referencing canonical — `https`, no trailing slash
-- A complete `hreflang` set: every locale, plus `x-default` and the source language
-  pointing at the **original** page, not at self
-- `og:url` / `og:locale`
-- JSON-LD with per-locale `@id`, `url` and `inLanguage` — and `Organization` left alone,
-  because a company is one entity in every language
-- Locale-prefixed internal links
-- Per-locale sitemaps
+```json
+// glossary.json
+[
+  { "source": "Acme",      "rule": "keep", "matchCase": true },
+  { "source": "Dashboard", "rule": "translate",
+    "targets": { "es": "Panel de control", "pt-br": "Painel" } }
+]
+```
+
+| Field | Meaning |
+| --- | --- |
+| `rule: "keep"` | Leave it in the source language. Defaults to **case-sensitive** |
+| `rule: "translate"` | Pin the wording per locale via `targets` |
+| `matchCase` | Override the default. `true` means `Apple` is protected and `apple` is not |
+| `note` | Free text, passed to the translator and to the quality judge as context |
+
+Matching is **whole-word**, always — `Apple` never matches inside `Applesauce` or
+`Appleton`. Only the terms that actually occur in a batch are sent to the model, so a
+500-term glossary does not inflate the prompt of every request.
+
+Your existing `doNotTranslate.brands` is folded in automatically as case-sensitive `keep`
+rules, so upgrading gains you word-boundary matching and, for the first time, **gate 7**,
+which checks the terms actually survived. Before 2.0 nothing verified that: a brand could
+be translated away and every gate still passed.
+
+Editing a glossary target re-translates **only** the units containing that term. A
+fingerprint sidecar next to the memory records what it was built against.
+
+## Register: buttons are not paragraphs
+
+The prompt has always ended with *"Headings stay headings; button labels stay short."* Until
+2.0 the model had no way to obey it — it received the string and nothing else, so a button
+label and a body paragraph were indistinguishable.
+
+The extractor always knew the answer and discarded it. Now each unit carries a short label
+where the answer changes the translation:
+
+| The string came from | It is told |
+| --- | --- |
+| `<button>`, or an `<a>` standing on its own | a control — keep it near the source length, no final period |
+| `<h1>`–`<h6>` | a headline — do not expand it into a sentence |
+| `<title>` | the tab and search-result title |
+| `<label>`, `<th>`, `<option>` | short, nominal furniture |
+| `alt`, `placeholder`, `aria-label` | described for a screen reader, or shown inside an empty field |
+| `<meta name="description">` | search-result copy, roughly 155 characters |
+
+Ordinary prose carries **no label at all**, so a site of nothing but paragraphs sends a
+payload byte-identical to 1.x and pays nothing for the feature. The prompt describes only the
+roles that actually appear in each batch.
+
+Two things it deliberately does not do. It does **not** demand the imperative for buttons —
+German UI prefers a verbal noun, French the infinitive, and ordering a literal command in
+every language is the defect this exists to prevent; it tells the model to use whatever
+construction that language puts on buttons. And when the same string appears as both a button
+and a paragraph it **clears** the hint rather than guessing, because one hash means one
+translation and a confident wrong answer is worse than none.
+
+There is no length *enforcement* — no character budget, no retry on overflow. Failed units
+ship in the source language, so a hard gate here would replace a slightly-long German button
+with an English one. That is a worse page.
+
+## Numbers and money
+
+`1,234.56` is `1.234,56` in German and `1 234,56` in French. `$5` is `5,00 $US` in French.
+Getting this wrong is one of the most visible marks of a machine translation, and models
+are unreliable at it — so the model is told to leave numbers **alone** (rule 4), and the
+formatting is applied deterministically afterwards with `Intl`.
+
+```json
+"localeFormat": { "numbers": true, "percent": true, "currency": "format", "units": "off" }
+```
+
+**Currency is formatted, never converted, and there is no option to convert it.** A price
+is a commercial commitment. Converting one at a rate baked into a build — a rate that is
+stale the day after it is written — is how a translation tool starts publishing wrong
+offers. What you get instead is `i18n/locale-format.json`, listing every monetary amount
+found, so a human can decide per market.
+
+**Gate 8 backs this up**: if the *value* of a number changes between source and
+translation, the build fails. A model that quietly ships `$39` where the source said `$49`
+passes every other check — the markup is identical, the placeholders match, the length is
+plausible and the Spanish is fluent.
+
+Things it deliberately leaves alone, because a "fix" here is a corruption: version numbers
+(`Node 20.5.1`), times (`10:30`), IP addresses, ISO dates, phone numbers, fractions, and
+any ungrouped number. Only unambiguous quantities are touched.
+
+Unit conversion (in→cm, °F→°C) is **not implemented**. The `units` key is accepted and
+ignored so a config written today keeps parsing when it lands.
+
+> One thing that looks like a bug and is not: Spanish does not group four-digit numbers,
+> so `1,234.50` correctly becomes `1234,50` in `es` and `1.234,50` in `de`. That is CLDR,
+> and there is a test pinning it.
 
 ## Trusting the output
 
 Machine translation at scale fails in ways that look like success. Two commands exist to
 catch that.
 
-**`verify.mjs` — six gates**
+**`verify.mjs` — eight gates**
 
 | # | Gate | Catches |
 | --- | --- | --- |
@@ -255,6 +399,8 @@ catch that.
 | 4 | Locale identity | wrong `lang`, canonical, `hreflang` or JSON-LD |
 | 5 | Coverage | share of extracted segments present in the memory |
 | 6 | **Never offered** | visible text the extractor never picked up |
+| 7 | Glossary | a protected brand that got translated, or a pinned term rendered some other way |
+| 8 | Numeric integrity | a number whose **value** changed — `$49` shipped as `$39` |
 
 Gate 6 exists because **coverage is not completeness**. Coverage measures
 translated-of-*extracted*, so it is structurally blind to extraction bugs. A single bug has
@@ -264,9 +410,45 @@ untranslated. Gate 6 compares built output against the source instead.
 **`audit-seo.mjs`** then checks canonicals, the full hreflang mesh, `og` tags, JSON-LD and
 sitemaps across *every* page — not a sample.
 
+**`tqa.mjs` — a quality score you can reproduce**
+
+The gates prove the plumbing. They say nothing about whether the Spanish is any *good*.
+That is what `tqa.mjs` is for.
+
+```bash
+node scripts/i18n/tqa.mjs --lang es --dry      # sample size and cost, no API call
+node scripts/i18n/tqa.mjs --lang es,fr,de      # writes i18n/tqa/{lang}.json + scorecard.md
+node scripts/i18n/tqa.mjs --lang es --repeat   # judge the same sample twice, report the gap
+```
+
+It scores a **stratified sample** — weighted by how often each string appears on the site,
+so the header everyone reads counts for more than a one-off footnote — using the **MQM**
+error typology the localization industry already uses:
+
+```
+score = 100 − (weighted error points ÷ words) × 100      minor 1 · major 5 · critical 10
+```
+
+Four things make the number honest rather than decorative:
+
+- **The judge defaults to a different provider than the translator.** Models prefer their
+  own output. If no second key is configured it says so, loudly, in the run and in the
+  report.
+- **The sample is seeded.** `--seed` reproduces a score exactly. A quality figure nobody
+  can re-derive is a marketing figure.
+- **`--repeat` reports the judge's own variance** by scoring the same sample twice. A score
+  quoted without its noise invites people to over-read a decimal place.
+- **A unit the judge cannot assess is excluded, not counted as clean.** During development
+  a misconfigured endpoint failed every single unit and the run printed `100.00 / 100` from
+  an empty sample. It now refuses to report a score at all in that case.
+
+Read it as a comparison — between locales, between models, between runs — and not as a
+grade. It is one model's opinion of another's work, it is not a human review, and the
+report says so on its face.
+
 **`review.mjs`** flags likely translation defects: dropped placeholders, wholesale
 source-language returns, wrong target language, truncated output. Read
-[`references/quality-review.md`](references/quality-review.md) before acting on its output —
+[`skills/translate-site/references/quality-review.md`](skills/translate-site/references/quality-review.md) before acting on its output —
 purging is destructive and its heuristics have known blind spots.
 
 ---
@@ -276,16 +458,49 @@ purging is destructive and its heuristics have known blind spots.
 The translation step is the only part that talks to a model, and it talks through a small
 adapter. Three ship with the project, and anything else is one file.
 
-| `provider` | Default model | Key |
-| --- | --- | --- |
-| `anthropic` *(default)* | `claude-haiku-4-5` | `ANTHROPIC_API_KEY` |
-| `gemini` | `gemini-2.5-flash-lite` | `GEMINI_API_KEY` |
-| `openai` | `gpt-4o-mini` | `OPENAI_API_KEY` |
-| `./my-provider.mjs` | — | yours |
+| `provider` | Default model | Key | Last verified against the live API |
+| --- | --- | --- | --- |
+| `anthropic` *(default)* | `claude-haiku-4-5` | `ANTHROPIC_API_KEY` | 2026-08-25 |
+| `gemini` | `gemini-2.5-flash-lite` | `GEMINI_API_KEY` | 2026-08-25 |
+| `openai` | `gpt-5.6-luna` | `OPENAI_API_KEY` | 2026-08-25 |
+| `./my-provider.mjs` | — | yours | — |
 
 Omit `provider` and it is inferred from the model id, so configs written before 1.2 keep
 working unchanged.
 
+**What "verified" means in that last column.** On 2026-08-25 each of the three adapters
+translated the same 98-unit, 1,381-word English site into Russian at its default model, as a
+real billed API call, with the translation memory deleted between runs so no provider could
+reuse another's work. Every run cleared all gates in `verify.mjs` and produced a clean
+`audit-seo.mjs` — 0 findings — and no run had a single failed unit. Measured cost: $0.025
+(Claude), $0.002 (Gemini), and 3,453/2,855 tokens on OpenAI, which the adapter deliberately
+does not price because it points at dozens of endpoints, some of them free and local.
+
+The three memories agreed on only 28–36% of units pairwise, and the ones all three agreed on
+were short labels like "Три плана". That divergence is the evidence the runs were independent.
+
+This column is a freshness marker, not a guarantee. Model ids get retired; if a default stops
+working, that is what this date is for. The contract tests in `scripts/providers/` still run
+on every commit with no network and no key — they catch a malformed request, not a rejected
+one.
+
+**Reasoning models and `temperature`.** The `openai` default is a reasoning model, and those
+reject sampling parameters — GPT-5.x answers a `temperature: 0.2` with
+`400 Unsupported value: 'temperature' … Only the default (1) value is supported`. The adapter
+handles this twice over: it omits `temperature` and sends `reasoning_effort: 'none'` for model
+ids it recognises as reasoning models, and if a server rejects a parameter anyway, the run drops
+that one parameter and retries instead of failing. A pinned `gpt-4o-mini`, and every local model,
+still get `temperature` exactly as before.
+
+`reasoning_effort` is `'none'` because bulk segment translation is a low-reasoning task — the
+same reason the Anthropic adapter pins its thinking tiers to `effort: 'low'`. Paying for a
+reasoning pass on every batch of forty segments is the one cost here worth engineering away.
+
+**Pricing.** `gpt-5.6-luna` is $0.20 in / $1.20 out per million tokens. The adapter reports no
+cost, deliberately — `pricing()` cannot see `baseUrl`, so it cannot tell OpenAI itself from
+OpenRouter or a local server offering the same model id. Set `pricing` in `i18n.config.json` to
+get a figure in the run summary.
+
 **The `openai` adapter is the interesting one**, because `/v1/chat/completions` is what
 everything speaks. That one adapter covers OpenAI, Azure, Groq, DeepSeek, Mistral,
 OpenRouter, Together and Fireworks — and Ollama, LM Studio and vLLM, which means the whole
@@ -303,9 +518,9 @@ No key, no quota, no request leaving the machine.
 
 **Claude is the default, not a requirement.** It is roughly ten times the cost of the
 Gemini option, which is a real difference on a large site and is spelled out in
-[`references/throughput-and-cost.md`](references/throughput-and-cost.md). Changing it is
+[`skills/translate-site/references/throughput-and-cost.md`](skills/translate-site/references/throughput-and-cost.md). Changing it is
 one line. Writing your own adapter is about thirty — see
-[`references/providers.md`](references/providers.md).
+[`skills/translate-site/references/providers.md`](skills/translate-site/references/providers.md).
 
 ---
 
@@ -343,7 +558,7 @@ Turn either off in `i18n.config.json`:
 Setting all five to `false` produces output with no trace of us in it, and nothing anywhere
 in this repo checks whether you did.
 
-### The visible credit is opt-in, and paid for
+### The visible credit is opt-in
 
 If you *want* to show a credit, set `visibleLink: true` and place the slot yourself, wherever
 you want it:
@@ -353,12 +568,14 @@ you want it:
 ```
 
 Nothing is injected anywhere else, and if the flag is on and no slot exists the build tells
-you rather than guessing. In exchange we will credit free translation words to a ConveyThis
-account — [details here](https://www.conveythis.com/open-source/claude-translator?utm_source=claude-skill&utm_medium=readme-visible-credit&utm_campaign=claude-translator).
+you rather than guessing. Nothing is asked of you for it and nothing is given in return — it
+exists because some people want to credit the tools they use, and for no other reason.
 
-The link is `rel="nofollow"`. Because you are compensated for it, it is a paid link under
-Google's guidelines and must not pass ranking signal. It is worth referral traffic, not
-backlinks, and anyone telling you otherwise is selling you a penalty.
+The link is `rel="nofollow"`. Not because it is paid — it is not — but because it is a link a
+build script would otherwise add across every page of a site, and sitewide links that appear
+because of tooling rather than editorial choice are the shape Google's link-scheme guidance is
+aimed at. It is worth referral traffic, not backlinks, and anyone telling you otherwise is
+selling you a penalty.
 
 ---
 
@@ -383,17 +600,34 @@ needs a build to hook and files to write. Where that shape doesn't fit,
 
 ---
 
-## Using it as a Claude Code skill
+## Using it as a Claude Code plugin
+
+This repo is also a self-contained [Claude Code](https://claude.com/claude-code) plugin, named
+`conveythis-translator`. Once it is approved for the community directory:
+
+```bash
+/plugin marketplace add anthropics/claude-plugins-community
+/plugin install conveythis-translator@claude-community
+```
+
+Plugin skills are namespaced, so it is invoked as `/conveythis-translator:translate-site` — or
+just ask Claude to "localize this site" and it will pick the skill up on its own. It follows
+`skills/translate-site/SKILL.md`, including the failure modes in `references/` and the routing
+rules for when this is the wrong tool entirely.
 
-This repo doubles as a [Claude Code](https://claude.com/claude-code) skill:
+To run it before it is listed, clone the repo anywhere and point Claude Code at it:
 
 ```bash
-git clone https://github.com/ConveyThis/claude-translator.git \
-  ~/.claude/skills/claude-translator
+git clone https://github.com/ConveyThis/claude-translator.git
+claude --plugin-dir ./claude-translator
 ```
 
-Then ask Claude to "localize this site". It follows `SKILL.md`, including the failure modes in
-`references/` and the routing rules for when this is the wrong tool entirely.
+To keep it permanently available without installing, symlink the **skill directory itself** into
+your personal skills folder — it is self-contained, references included:
+
+```bash
+ln -s "$PWD/claude-translator/skills/translate-site" ~/.claude/skills/translate-site
+```
 
 ---
 
@@ -401,18 +635,19 @@ Then ask Claude to "localize this site". It follows `SKILL.md`, including the fa
 
 | Document | Read it when |
 | --- | --- |
-| [`references/failure-modes.md`](references/failure-modes.md) | **Before modifying any script.** Every known bug: symptom → cause → fix |
-| [`references/quality-review.md`](references/quality-review.md) | Before purging anything the reviewer flags |
-| [`references/throughput-and-cost.md`](references/throughput-and-cost.md) | Budgeting a run, or making it faster |
-| [`references/adapting-generators.md`](references/adapting-generators.md) | Using anything other than Astro |
-| [`references/providers.md`](references/providers.md) | Changing model, running locally, or writing an adapter |
+| [`skills/translate-site/references/failure-modes.md`](skills/translate-site/references/failure-modes.md) | **Before modifying any script.** Every known bug: symptom → cause → fix |
+| [`skills/translate-site/references/quality-review.md`](skills/translate-site/references/quality-review.md) | Before purging anything the reviewer flags, or reading a TQA score |
+| [`skills/translate-site/references/throughput-and-cost.md`](skills/translate-site/references/throughput-and-cost.md) | Budgeting a run, or making it faster |
+| [`skills/translate-site/references/adapting-generators.md`](skills/translate-site/references/adapting-generators.md) | Using anything other than Astro |
+| [`skills/translate-site/references/providers.md`](skills/translate-site/references/providers.md) | Changing model, running locally, or writing an adapter |
+| [`PRIVACY.md`](PRIVACY.md) | You want to know exactly what leaves your machine, and how to check |
 | [`LICENSING.md`](LICENSING.md) | You are wrapping a modified copy in a hosted service |
 
 ## Supported generators
 
 Anything that emits static HTML: **Astro**, **Next.js** (`output: 'export'`), **Hugo**,
 **Eleventy**, **Jekyll**, **Gatsby**, or hand-written HTML. See
-[`references/adapting-generators.md`](references/adapting-generators.md) for per-generator
+[`skills/translate-site/references/adapting-generators.md`](skills/translate-site/references/adapting-generators.md) for per-generator
 notes — particularly around hydration payloads, which can re-render over your translations.
 
 ## Contributing

package/bin/claude-translator.mjs

@@ -59,11 +59,13 @@ ${c.bold}OPTIONS${c.reset}
 ${c.bold}AFTER INIT${c.reset}
   npm install                                    install parse5, the only dependency
   \$EDITOR i18n.config.json                       set baseUrl, locales, provider
+  \$EDITOR glossary.json                          protect brands, pin terminology
   node <dir>/extract.mjs                         find translatable units
   node <dir>/translate.mjs --lang es,fr          translate
   node <dir>/build-locales.mjs --lang all        write the localized pages
-  node <dir>/verify.mjs --lang all               six gates
+  node <dir>/verify.mjs --lang all               eight gates
   node <dir>/audit-seo.mjs                       full SEO audit
+  node <dir>/tqa.mjs --lang es                   MQM quality score
 
 ${c.bold}DOCS${c.reset}  https://github.com/ConveyThis/claude-translator
 `;
@@ -132,17 +134,22 @@ for (const entry of readdirSync(srcDir)) {
   const from = join(srcDir, entry);
   if (statSync(from).isDirectory()) {
     for (const sub of readdirSync(from)) {
+      if (/\.test\.mjs$/.test(sub)) continue;
       place(join(from, sub), join(targetDir, entry, sub));
     }
     continue;
   }
   if (!/\.(mjs|sh)$/.test(entry)) continue;
+  // Contract tests belong to this repo, not to the user's project — they import a test
+  // runner and assert on our own internals.
+  if (/\.test\.mjs$/.test(entry)) continue;
   place(from, join(targetDir, entry));
 }
 
 // ── 2. The config ────────────────────────────────────────────────────────────
 
 place(join(PKG_ROOT, 'i18n.config.example.json'), join(CWD, 'i18n.config.json'), 'i18n.config.json');
+place(join(PKG_ROOT, 'glossary.example.json'), join(CWD, 'glossary.json'), 'glossary.json');
 
 // ── 3. The one dependency ────────────────────────────────────────────────────
 // Written into package.json rather than installed here: running npm from inside npx is
@@ -209,13 +216,15 @@ if (skipped.length) {
 const rows = [
   ...(needsInstall ? [['npm install', 'parse5, the only dependency']] : []),
   ['$EDITOR i18n.config.json', 'baseUrl, locales, provider'],
+  ['$EDITOR glossary.json', 'brands to protect, terms to pin (optional)'],
   [],
   ['npm run build', 'your normal build, source language only'],
   [`node ${DIR}/extract.mjs`, 'find translatable units'],
   [`node ${DIR}/translate.mjs --lang es,fr`, 'translate (needs a provider key)'],
   [`node ${DIR}/build-locales.mjs --lang all`, 'write the localized pages'],
-  [`node ${DIR}/verify.mjs --lang all`, 'six gates'],
+  [`node ${DIR}/verify.mjs --lang all`, 'eight gates'],
   [`node ${DIR}/audit-seo.mjs`, 'full SEO audit'],
+  [`node ${DIR}/tqa.mjs --lang es`, 'translation quality score (optional)'],
 ];
 const width = Math.max(...rows.filter((r) => r.length).map(([cmd]) => cmd.length)) + 2;
 

package/bin/cli.test.mjs

@@ -90,7 +90,12 @@ test('init scaffolds a runnable pipeline', () => {
     'scripts/i18n/credit.mjs',
     'scripts/i18n/providers/index.mjs',
     'scripts/i18n/providers/anthropic.mjs',
+    'scripts/i18n/glossary.mjs',
+    'scripts/i18n/format-locale.mjs',
+    'scripts/i18n/tqa.mjs',
+    'scripts/i18n/tqa-score.mjs',
     'i18n.config.json',
+    'glossary.json',
   ]) {
     assert.ok(existsSync(join(cwd, f)), `init did not write ${f}`);
     assert.ok(stdout.includes(f.split('/').pop()), `init wrote ${f} without reporting it`);
@@ -157,9 +162,23 @@ test('an existing .gitignore is appended to, not replaced', () => {
 
 test('package.json "files" ships everything init needs to copy', () => {
   const root = resolve(dirname(CLI), '..');
-  for (const needed of ['bin', 'scripts', 'i18n.config.example.json']) {
+  for (const needed of ['bin', 'scripts', 'i18n.config.example.json', 'glossary.example.json']) {
     assert.ok(PKG.files.includes(needed), `"files" omits ${needed}; npx would install a broken package`);
   }
   assert.equal(PKG.bin['claude-translator'], 'bin/claude-translator.mjs');
   assert.ok(existsSync(join(root, PKG.bin['claude-translator'])), 'bin path does not exist');
 });
+
+test('init does not vendor our own contract tests into the user project', () => {
+  // scripts/*.test.mjs import node:test and assert on internals. Copying them into
+  // someone else's repo puts failing, irrelevant tests in their suite.
+  const { cwd } = run(['init']);
+  const leaked = [
+    'scripts/i18n/glossary.test.mjs',
+    'scripts/i18n/format-locale.test.mjs',
+    'scripts/i18n/tqa-score.test.mjs',
+    'scripts/i18n/providers/providers.test.mjs',
+  ].filter((f) => existsSync(join(cwd, f)));
+  assert.deepEqual(leaked, [], `init leaked test files: ${leaked.join(', ')}`);
+  rmSync(cwd, { recursive: true, force: true });
+});

package/glossary.example.json

@@ -0,0 +1,23 @@
+[
+  {
+    "source": "Acme",
+    "rule": "keep",
+    "matchCase": true,
+    "note": "the company; lowercase 'acme' is an ordinary word and should be translated"
+  },
+  {
+    "source": "Acme Cloud Inc",
+    "rule": "keep",
+    "matchCase": true
+  },
+  {
+    "source": "Dashboard",
+    "rule": "translate",
+    "targets": {
+      "es": "Panel de control",
+      "pt-br": "Painel",
+      "ar": "لوحة التحكم"
+    },
+    "note": "product surface — must read the same on every page"
+  }
+]

package/i18n.config.example.json

@@ -55,6 +55,13 @@
       "EPUB"
     ]
   },
+  "glossary": "glossary.json",
+  "localeFormat": {
+    "numbers": true,
+    "percent": true,
+    "currency": "format",
+    "units": "off"
+  },
   "provider": "anthropic",
   "model": "claude-haiku-4-5",
   "credit": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-translator",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "Translate a static website into dozens of languages as real static pages, by substituting into built HTML instead of re-rendering.",
   "type": "module",
   "license": "AGPL-3.0-or-later",
@@ -36,13 +36,16 @@
     "claude-translator": "bin/claude-translator.mjs"
   },
   "files": [
+    ".claude-plugin",
     "bin",
     "scripts",
-    "references",
-    "SKILL.md",
+
+    "skills",
     "LICENSING.md",
+    "PRIVACY.md",
     "CHANGELOG.md",
-    "i18n.config.example.json"
+    "i18n.config.example.json",
+    "glossary.example.json"
   ],
   "devDependencies": {
     "parse5": "^7.3.0"
@@ -54,7 +57,8 @@
     "i18n:build": "node scripts/build-locales.mjs",
     "i18n:verify": "node scripts/verify.mjs",
     "i18n:audit": "node scripts/audit-seo.mjs",
+    "i18n:tqa": "node scripts/tqa.mjs",
     "check": "for f in scripts/*.mjs scripts/providers/*.mjs bin/*.mjs; do node --check \"$f\" || exit 1; done && echo 'all scripts parse'",
-    "test": "node --test scripts/providers/providers.test.mjs bin/cli.test.mjs"
+    "test": "node --test scripts/providers/providers.test.mjs scripts/glossary.test.mjs scripts/format-locale.test.mjs scripts/tqa-score.test.mjs scripts/roles.test.mjs bin/cli.test.mjs"
   }
 }

package/scripts/audit-seo.mjs

@@ -26,10 +26,13 @@ import { readFileSync, existsSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { fileURLToPath } from 'url';
 
-import { BUILD_DIR as DIST, BASE_URL as BASE, LOCALES as LANG_ROWS, BY_PATH, RTL, getPages, I18N_DIR } from './config.mjs';
+import {
+  BUILD_DIR as DIST, BASE_URL as BASE, LOCALES as LANG_ROWS,
+  BY_PATH, RTL, getPages, I18N_DIR, ROOT_DIR,
+} from './config.mjs';
 import { creditBlock } from './credit.mjs';
 
-const ROOT = process.cwd();
+const ROOT = ROOT_DIR;
 
 const args = Object.fromEntries(
   process.argv
@@ -249,7 +252,7 @@ for (const [check, list] of Object.entries(byCheck).sort((a, b) => b[1].length -
   if (list.length > 3) console.log(`      … and ${(list.length - 3).toLocaleString()} more`);
 }
 
-writeFileSync(join(ROOT, 'i18n/seo-audit.json'), JSON.stringify({ counts, findings }, null, 2));
+writeFileSync(join(I18N_DIR, 'seo-audit.json'), JSON.stringify({ counts, findings }, null, 2));
 console.log(`\nwrote i18n/seo-audit.json (${findings.length.toLocaleString()} findings)`);
 
 creditBlock(