claude-translator 1.3.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "claude-translator",
+  "version": "1.3.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",
+  "author": "ConveyThis (https://conveythis.com)",
+  "homepage": "https://github.com/ConveyThis/claude-translator",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ConveyThis/claude-translator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ConveyThis/claude-translator/issues"
+  },
+  "keywords": [
+    "i18n",
+    "l10n",
+    "localization",
+    "translation",
+    "static-site",
+    "hreflang",
+    "seo",
+    "astro",
+    "claude",
+    "anthropic",
+    "gemini",
+    "openai",
+    "ollama",
+    "multilingual"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "claude-translator": "bin/claude-translator.mjs"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "references",
+    "SKILL.md",
+    "LICENSING.md",
+    "CHANGELOG.md",
+    "i18n.config.example.json"
+  ],
+  "devDependencies": {
+    "parse5": "^7.3.0"
+  },
+  "scripts": {
+    "i18n:extract": "node scripts/extract.mjs",
+    "i18n:translate": "node scripts/translate.mjs",
+    "i18n:review": "node scripts/review.mjs",
+    "i18n:build": "node scripts/build-locales.mjs",
+    "i18n:verify": "node scripts/verify.mjs",
+    "i18n:audit": "node scripts/audit-seo.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"
+  }
+}

package/references/adapting-generators.md

@@ -0,0 +1,76 @@
+# Adapting to different generators
+
+The method needs only three things:
+
+1. A **directory of built HTML** where each page is `<slug>/index.html` (or `<slug>.html`)
+2. A **list of pages** to localize
+3. A **list of locales**
+
+Nothing else is framework-specific. `config.mjs` is the only file that knows about a
+given site.
+
+---
+
+## Per generator
+
+| Generator | `buildDir` | Page list | Notes |
+| --- | --- | --- | --- |
+| **Astro** (`output: 'static'`) | `dist` | `"build"`, or a slug array | Reference implementation. Clean-URL output already matches. |
+| **Next.js** (`next export` / `output: 'export'`) | `out` | `"build"` | Check trailing-slash config — canonical rules must match what the server serves. |
+| **Hugo** | `public` | `"build"` | Hugo has native i18n; use it if content lives in Markdown front matter. This skill wins when translating *rendered* pages. |
+| **Eleventy** | `_site` | `"build"` | Straightforward. |
+| **Jekyll** | `_site` | `"build"` | Straightforward. |
+| **Gatsby** | `public` | `"build"` | Exclude `page-data/` and the JSON payloads. |
+| **Plain HTML** | wherever | `"build"` | Works as-is. |
+
+```json
+{ "buildDir": "out", "pages": { "source": "build", "exclude": ["404", "admin"] } }
+```
+
+`pages.source: "build"` derives the list from the output directory. Point it at a file
+instead when an explicit list exists (a sitemap slug array). For a `.ts`/`.js` file, set
+`pages.export` to the exported const name — **scoping matters**: scanning the whole file
+sweeps up every other quoted string in it. In one case that silently added the
+language-code array to the page-slug array and inflated the page count.
+
+---
+
+## What to check on a new generator
+
+**Clean URLs vs `.html`.** The scripts assume `<slug>/index.html`. If output is
+`about.html`, adjust the path construction in `build-locales.mjs` and `verify.mjs`
+together, and make canonicals match what the server actually serves.
+
+**Trailing slashes.** Canonical, hreflang and sitemap must agree with the server's
+redirect behaviour. A canonical pointing at a URL that 301-redirects is a real SEO defect
+(a real defect found in production).
+
+**Hydration payloads.** Frameworks that embed serialized state (`__NEXT_DATA__`,
+Gatsby's `page-data`) duplicate visible text inside `<script>`. The extractor already skips
+`<script>`, so those copies stay in the source language — **and the client may re-render
+from them**, overwriting your translations. Test one interactive page early. If it happens,
+either translate the payload too or exclude that route.
+
+**Framework-native i18n.** If the source content is structured (Markdown + front matter)
+and the generator has real i18n, prefer it — you get translated slugs and proper routing.
+This skill is for the case where content is *already rendered*, or where re-rendering every
+page is unacceptable (large sites, critical-CSS pipelines, proxy replacement).
+
+---
+
+## Locale identity to emit per page
+
+Whatever the generator, each localized page needs:
+
+| Element | Value |
+| --- | --- |
+| `<html lang>` | the locale's `hreflang` |
+| `<html dir>` | `rtl` for ar/fa/he/ur — **replace** any existing `dir`, don't append |
+| canonical | the page's own URL, `https`, no trailing slash |
+| `hreflang` self | identical to the canonical |
+| `hreflang` en / x-default | the **source** page, not self |
+| `og:url` / `og:locale` | page URL / locale code |
+| JSON-LD | `@id` = `<page-url>#webpage`, `url` per type, `inLanguage` = locale |
+
+`build-locales.mjs` does all of this and reports any rule that matched nothing — which is
+how attribute-order bugs surface. `audit-seo.mjs` then verifies it across every page.

package/references/failure-modes.md

@@ -0,0 +1,255 @@
+# Failure modes
+
+Every one of these was hit in production on a 55-locale rollout. They are listed because
+each **looked like working code**, and several produced wrong output that reported success.
+
+Read this before modifying any script.
+
+---
+
+## Extraction
+
+### A skipped element inside a block silently drops the whole block
+
+**Symptom:** coverage 100%, gates green, yet "Translate a Document", "Sign Up Free" and
+every `✓ feature` bullet render in the source language.
+
+**Cause:** the tokenizer treated `<svg>` as "skip", and skipping aborted the *entire*
+containing block. Every icon+label pair on the site — buttons, feature bullets, badges —
+was never offered for translation. **Thousands of segments, invisible.**
+
+**Fix:** an opaque element becomes **one void placeholder** carrying the element verbatim.
+Never abandon a unit because of a child.
+
+**Detection:** gate 6 in `verify.mjs`. Coverage cannot see this class of bug at all.
+
+### The extractor scans its own output
+
+**Symptom:** unit and segment counts roughly double; the memory starts filling with
+target-language strings keyed as source.
+
+**Cause:** locale directories live inside the build directory, so a naive recursive scan
+reads `dist/es/**` as if it were source.
+
+**Fix:** exclude every configured `pathCode` from the scan (`config.mjs` does this).
+
+### JSON-LD bare-value search matches substrings
+
+**Symptom:** `Overlapping segments … Aborting.`
+
+**Cause:** searching for a bare value finds it inside a longer sibling —
+`"name":"PDF Translator"` sits within `"name":"AI PDF Translator"` — producing overlapping
+byte ranges that would corrupt output.
+
+**Fix:** match the full `"key"\s*:\s*"value"` pair, never the value alone.
+
+### Language-switcher labels drift per locale
+
+**Symptom:** the picker reads differently on every locale — `English (English)` becomes
+`Inglés (English)` on Spanish while `Español (Spanish)` stays put.
+
+**Cause:** a language picker shows every language in **its own** language. These are data,
+not copy.
+
+**Fix:** treat `Native (EnglishName)` strings and bare native labels as do-not-translate.
+Apply the same rule in the verifier, or gate 6 will report them as holes.
+
+---
+
+## Translation API
+
+### Network exceptions bypass status-code retry
+
+**Symptom:** a run finishes "successfully" with several hundred units missing.
+
+**Cause:** `TypeError: fetch failed` (DNS, reset, socket timeout) throws **before** any
+response exists, so `if (!res.ok)` never sees it. Cost: **hundreds of units** lost silently in a single run.
+
+**Fix:** wrap the `fetch` itself and retry on the same backoff as 429/5xx.
+
+### A batch that exceeds the output limit returns truncated JSON
+
+**Symptom:** `SyntaxError: Unterminated string in JSON at position …`, 40 units gone.
+
+**Fix:** catch the parse error, split the batch in half, recurse. Only a single oversized
+unit can then be unrecoverable.
+
+### The safety filter blocks the whole request
+
+**Symptom:** `promptFeedback.blockReason: PROHIBITED_CONTENT`, no candidates, 40 units gone.
+
+**Cause:** one string the filter dislikes takes the other 39 with it.
+
+**Fix:** same split-and-recurse path.
+
+### Memory written only at the end
+
+**Symptom:** a 40-minute run is interrupted and *everything* is lost.
+
+**Fix:** checkpoint every ~10 batches. This later saved thousands of units when a long run
+had to be killed and restarted.
+
+### The model silently returns the source language
+
+Not an API error — a **quality** failure that every structural gate passes. See
+`quality-review.md`; word-overlap detection is what catches it.
+
+---
+
+### `output_config.effort` is rejected on Haiku
+
+**Symptom.** Every Anthropic request fails with a 400 naming `effort`, on a model that
+otherwise works.
+
+**Cause.** Claude tiers do not take the same parameters. `claude-haiku-4-5` rejects
+`output_config.effort` outright; the Opus and Sonnet tiers accept it.
+
+**Fix.** `providers/anthropic.mjs` keeps a capability table and sends the parameter only
+where it is accepted. Adding a model means adding it to `ACCEPTS_EFFORT`, not assuming.
+
+### Adaptive thinking is on by default, and translation pays for it
+
+**Symptom.** A run on Opus or Sonnet costs several times the estimate, with output token
+counts far above what the translated text can account for.
+
+**Cause.** Those models run adaptive thinking unless told otherwise. Segment translation
+has no use for it, but it is billed all the same.
+
+**Fix.** The adapter pins `output_config.effort: 'low'` on the tiers that support it.
+Do **not** "fix" this by setting `thinking: {type: 'disabled'}` — on Opus 5 that has its
+own failure modes, including writing a tool call into visible text.
+
+### Local models wrap JSON in a code fence
+
+**Symptom.** Works on a hosted provider, fails on Ollama or LM Studio with
+`Unexpected token \`` on every batch.
+
+**Cause.** Smaller models emit ` ```json … ``` ` regardless of instructions, and some
+prepend a sentence of preamble.
+
+**Fix.** `extractJson()` in `providers/index.mjs` strips fences and falls back to the
+outermost bracket pair. Never assume the response body starts with `[`.
+
+### A server rejects `response_format` and the run dies
+
+**Symptom.** An OpenAI-compatible endpoint returns 400 mentioning `response_format` or
+`json_schema`, and nothing translates.
+
+**Cause.** The structured-output field is not universal across "OpenAI-compatible"
+servers. Many implement `json_object` only; some implement neither.
+
+**Fix.** `unsupportedJsonMode()` distinguishes that rejection from a genuine bad request,
+and `translate.mjs` drops one rung — `json_schema` → `json_object` → prompt only — rather
+than failing. Placeholder validation still guards the output, so the weaker mode costs
+retries and not correctness. A real error (bad key, unknown model) must **not** match this
+path, which is why the pattern is narrow.
+
+### Locale pages built from a stale source build
+
+**Symptom.** The locale pages' inlined critical CSS no longer matches the source page's, and
+each carries rules for classes the other one uses. Tag sequence and `class` attributes still
+match perfectly, so substitution clearly worked — but the two pages disagree about their CSS.
+
+**Cause.** The source site was rebuilt *after* the locale pages were generated, and
+critical-CSS extraction is not stable across builds. Observed live on a production site: two
+builds three hours apart, identical markup, and the later build's critical CSS gained
+`.bg-sky-500`, `.bg-slate-100`, `.object-cover` and `.scale-150` while losing `.aspect-video`.
+Neither build's CSS was a correct match for its own markup.
+
+This is the same instability that makes per-locale re-rendering a bad idea, showing up in a
+different place — and it is a useful reminder that the tooling is the unreliable part, not the
+substitution.
+
+**Fix.** Re-run `build-locales.mjs` after any rebuild that changes markup. It is nearly free:
+the translation memory is keyed by source text, so nothing is re-translated and no API call is
+made. Cheap enough to put in the same CI step as the build itself.
+
+**How to spot it.** Compare an inlined `<style>` block between a source page and its locale
+twin. Substitution never touches `<style>` contents, so if they differ, the locale page was
+built from a different snapshot than the one you are looking at.
+
+### A model id sent to the wrong provider
+
+**Symptom.** After upgrading to 1.2, an existing project fails with an unhelpful
+"unknown model" from an API it never used before.
+
+**Cause.** 1.2 changed the default provider to Anthropic. A config from 1.0/1.1 pins a
+Gemini model id and has no `provider` key.
+
+**Fix.** `inferProvider()` derives the provider from the model id when `provider` is
+absent, so those configs keep working. Only a config with neither key gets the default.
+The run prints which provider it resolved and whether it was inferred — read that line
+before debugging anything else.
+
+## Building locale pages
+
+### Attribute order is not guaranteed
+
+**Symptom:** canonical/hreflang/og rewrites do nothing, build reports success.
+
+**Cause:** a builder emitted `<link href="…" rel="canonical">`; the regex assumed `rel`
+first. Every identity rule silently no-opped.
+
+**Fix:** parse attributes into a map rather than matching positionally, **and report any
+rule that matched zero occurrences**. That report is what surfaced it.
+
+### Not every schema `url` is the page URL
+
+**Symptom:** `Organization.url` becomes `/es/about` — the company relocated to a subpage.
+
+**Cause:** blanket rewriting of every `url` in JSON-LD.
+
+**Fix:** only page-level types (`WebPage`, `AboutPage`, `FAQPage`, `ContactPage`, …) get
+the page URL. `WebSite.url` gets the **locale root**. `Organization` is one entity across
+all languages — leave it alone.
+
+### The home link gains a trailing slash
+
+`href="/"` naively prefixed becomes `/es/`, which 301-redirects back to `/es` — a
+needless redirect on the logo of every page, contradicting the canonical. Special-case the
+empty path.
+
+### One component, two instances
+
+A non-global regex patches only the first. If a component is mounted twice (mobile +
+desktop header), every per-locale rewrite needs the `g` flag.
+
+### Concurrent builds of the same locale race
+
+Each build starts by deleting the locale directory, so two overlapping runs leave a
+half-written tree — pages missing while both runs report success. Caught by URL parity.
+Never build the same locale twice concurrently.
+
+---
+
+## Verification
+
+### Coverage above 100%
+
+Numerator and denominator used different page sets (one counted every segment file,
+the other only sitemap pages). A percentage that can exceed 100 is a broken measurement,
+not a good result.
+
+### Coverage is not completeness
+
+The single most important lesson. Coverage answers *"how much of what I extracted did I
+translate?"* — it is structurally incapable of seeing text the extractor never offered.
+
+Gate 6 answers the real question by comparing built output against the source page and
+failing on strings that were never translation candidates. It must **not** fail merely
+because a string is identical in both languages: `e-Learning`, `PowerPoint (.PPT)` and
+`Google Translate PDF` are correct unchanged. Report those separately as "identical but
+offered".
+
+---
+
+## Operating the pipeline
+
+- **`nohup … &` does not survive a tool-call shell.** Use the harness's background
+  mechanism. A killed run loses everything since the last checkpoint.
+- **macOS ships `openrsync`**, which rejects `--info=progress2` by printing usage and
+  **exiting 0**. The sync silently transfers nothing. Verify destination state.
+- **`pgrep -f 'script.sh'` matches the polling shell itself** → the waiter waits forever.
+  Poll a state file, or match interpreter + script path.
+- **Running the same expensive command twice in one line** (once to count, once to grep)
+  doubles a 20-minute build. Redirect to a file and inspect the file.

package/references/providers.md

@@ -0,0 +1,157 @@
+# Providers
+
+The translation step is the only part of this pipeline that talks to a model, and it
+talks through a small adapter. Three ship with the project; anything else is one file.
+
+---
+
+## Choosing one
+
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-haiku-4-5"
+}
+```
+
+| `provider` | Default model | Key | Notes |
+| --- | --- | --- | --- |
+| `anthropic` | `claude-haiku-4-5` | `ANTHROPIC_API_KEY` | The default. |
+| `gemini` | `gemini-2.5-flash-lite` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | Roughly a tenth the cost — see [throughput-and-cost.md](throughput-and-cost.md). |
+| `openai` | `gpt-4o-mini` | `OPENAI_API_KEY` | Any OpenAI-compatible endpoint, including local ones. |
+| `./my-provider.mjs` | — | yours | A path is imported directly. See below. |
+
+`--provider` and `--model` on the command line override the config for one run.
+
+**If you omit `provider`, it is inferred from the model id** — `gemini-*` → `gemini`,
+`claude-*` → `anthropic`, `gpt-*` → `openai`. This is what keeps configs written for
+1.0 and 1.1 working after the 1.2 default changed to Claude. Omit both and you get
+`claude-haiku-4-5`. The run prints which provider it resolved and whether it guessed.
+
+---
+
+## Running on a local model
+
+The `openai` adapter speaks `/v1/chat/completions`, which Ollama, LM Studio and vLLM
+all implement. Point it at one and the whole pipeline runs on your own hardware for
+nothing:
+
+```json
+{
+  "provider": "openai",
+  "apiBaseUrl": "http://localhost:11434/v1",
+  "model": "qwen2.5:14b"
+}
+```
+
+No key is needed — the adapter omits the `Authorization` header when there isn't one.
+
+> `apiBaseUrl` is the **model** host. It is deliberately a different key from `baseUrl`,
+> which is your **site's** canonical origin. Confusing them would point your canonical
+> tags at a language model.
+
+Two things to expect from smaller local models. They emit JSON wrapped in a
+` ```json ` fence, which the parser strips. And they often do not implement
+`response_format`; when a server rejects it, the adapter drops to the next rung —
+`json_schema` → `json_object` → prompt only — and says so. Placeholder validation runs
+regardless, so a weaker guarantee costs retries rather than correctness. Force a rung
+with `"jsonMode": "object"` if you already know what your server supports.
+
+The same adapter covers OpenAI, Azure OpenAI, Groq, DeepSeek, Mistral, OpenRouter,
+Together and Fireworks. Set `apiBaseUrl` and `model`; some need `apiKeyEnv` to point at
+a differently-named variable.
+
+---
+
+## Which Claude model
+
+`claude-haiku-4-5` is the default because bulk segment translation is a high-volume,
+low-reasoning task and Haiku is the tier priced for it. Moving up is one line:
+
+| Model | $/Mtok in/out | Relative cost |
+| --- | --- | --- |
+| `claude-haiku-4-5` | 1 / 5 | baseline |
+| `claude-sonnet-5` | 3 / 15 | ~3x |
+| `claude-opus-5` | 5 / 25 | ~5x |
+
+Rates checked 2026-08-25. The larger models are better on idiom and register, which
+matters for marketing copy and much less for UI strings.
+
+One implementation detail worth knowing: the models that support adaptive thinking have
+it **on by default**, and a translation run has no use for it. The adapter pins
+`output_config.effort: "low"` on those tiers so you are not billed for reasoning you did
+not ask for. Haiku takes no effort parameter at all — the API rejects it — so it is sent
+nothing.
+
+---
+
+## Writing your own
+
+A provider is a module with two required exports.
+
+```js
+// my-provider.mjs
+export const id = 'my-provider';
+export const label = 'My Provider';          // shown in logs and errors
+export const defaultModel = 'my-model-v1';
+export const envKeys = ['MY_PROVIDER_KEY'];  // checked in order, env then .env
+export const keyOptional = false;            // true for local servers
+
+/** Build one HTTP request. */
+export function request({ model, system, items, temperature, key, baseUrl, jsonMode }) {
+  return {
+    url: `${baseUrl ?? 'https://api.example.com/v1'}/translate`,
+    headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+    body: { model, system, items, temperature },
+  };
+}
+
+/** Read one response. */
+export function parse(data) {
+  return {
+    text: data.output,                              // the raw JSON string, or null
+    usage: { inTok: data.in ?? 0, outTok: data.out ?? 0 },
+    retryable: null,                                // 'safety' | 'truncated' | null
+    detail: data.reason,                            // shown when splitting
+  };
+}
+
+/** Optional: the units are nested in your response envelope. */
+export const unwrap = (parsed) => parsed.translations ?? parsed;
+
+/** Optional: USD per million tokens, [in, out]. Omit if unknown. */
+export function pricing(model) { return [0.5, 1.5]; }
+```
+
+Then:
+
+```json
+{ "provider": "./scripts/my-provider.mjs", "model": "my-model-v1" }
+```
+
+`request` returns what to send; `parse` says what came back. Everything else —
+exponential backoff, retrying network errors, halving a batch that was refused or
+truncated, validating that placeholders survived, checkpointing the memory — is handled
+by `translate.mjs` and applies to your adapter automatically.
+
+**`retryable` is the important field.** Return `'safety'` when the provider refused the
+whole request because of one string in it, and `'truncated'` when the output hit a
+length limit. Both cause the batch to be halved and retried, which is what turns a lost
+batch of forty units into one unusable unit. Return `null` and a failure takes all forty
+with it.
+
+Run `node --test scripts/providers/providers.test.mjs` — the contract tests there are
+the clearest specification of what an adapter must do.
+
+---
+
+## Switching providers mid-project
+
+The translation memory is keyed by a hash of the **source** text, not by model. So
+changing provider translates only what is missing and reuses everything already there.
+That makes a cheap first pass and a selective re-run practical: delete the units you
+want redone from `i18n/tm/{lang}.json` and translate again on a better model.
+
+The flip side is that one locale can end up part-translated by two models, with a
+visible seam in voice. If that matters, delete the whole memory for that locale rather
+than topping it up.

package/references/quality-review.md

@@ -0,0 +1,91 @@
+# Quality review
+
+Structural gates prove the *plumbing* is correct — right pages, right markup, no broken
+placeholders. They say nothing about whether the text is actually translated, or
+translated into the right language. That is what `review.mjs` is for.
+
+**The governing lesson: a heuristic that over-flags is worse than none.** The remedy for a
+flag is purge-and-retranslate, which costs money and time. A noisy check either burns both
+or trains you to ignore it.
+
+---
+
+## Verdicts
+
+| Check | Reliable? | Notes |
+| --- | --- | --- |
+| Placeholder multiset mismatch | **Yes** — hard gate | Would corrupt HTML; validated at translate time and re-checked |
+| Word overlap vs source | **Yes** | Catches wholesale-source returns *and* wrong-target-language |
+| Length ratio | **Only script-aware** | See calibration below |
+| Latin-script ratio | **Only brand-stripped** | Non-Latin locales only |
+| Identical to source | Yes, with a content-word floor | Brand-only strings are correct unchanged |
+| Adjacent word repetition | **No — disabled** | Three narrowing attempts, still mostly false positives |
+
+---
+
+## Calibration failures worth remembering
+
+**Length ratio, flat floor → mass false positives on CJK.** A 0.4× floor flagged roughly
+half of a Traditional Chinese locale, because CJK encodes far more meaning per character:
+a 100-character English sentence is routinely ~30 characters of Chinese. Those units were
+purged and re-translated for nothing.
+
+Use script-aware bounds:
+
+| Script group | Floor | Ceiling |
+| --- | --- | --- |
+| CJK, Thai, Lao, Khmer, Burmese | 0.12 | 1.2 |
+| Everything else | 0.4 | 2.5 |
+
+**Latin-ratio counting brand names → dozens of false positives per non-Latin locale.**
+A heading like `"BrandName: лучше, чем Competitor?"` is mostly Latin characters and
+perfectly translated. Strip brand and format tokens *before* computing the ratio, require ≥6 content
+words, and set the threshold at 0.8. The check is aimed at "the model returned the source
+language wholesale", not at short brand-heavy labels.
+
+**Tautology detection — abandoned.** The real defect looks like `prueba una prueba`
+("try a try", from "try a 7-day trial"). Three successive narrowings were tried:
+distance-1 only; require the source not to repeat the word; restrict to within a sentence.
+It still could not separate that from `de inglés y de inglés a armenio`, which is correct
+Spanish with an identical shape — the connectors between the repeats are shorter than the
+token filter. Distinguishing them needs meaning, not shape. Shipped behind `--tautology`,
+never gating.
+
+---
+
+## What review actually caught
+
+These are real defects that **no structural gate could see**, because the text *was*
+offered for translation and *was* returned:
+
+- **Whole paragraphs returned in the source language**, with one word changed — a paragraph came back with only the language
+  name changed. Not byte-identical, so an equality check missed it; word overlap caught it.
+- **Wrong target language.** `"Is Bahasa Melayu the same as Bahasa Indonesia?"` came back
+  in **Malay** on the Spanish locale — the model latched onto "Bahasa". One FAQ heading
+  among hundreds of pages; visual review would never have reached it.
+- **Truncated output.** A 713-character Hebrew passage came back at 267 characters, cut
+  mid-word, because the batch exceeded the output limit. Coverage counted it as done.
+
+Typical healthy flag rate after correction: **0.05–0.15% per locale**, and the remainder
+are legitimate — postal addresses, image filenames used as alt text, proper nouns.
+
+---
+
+## Workflow
+
+```bash
+node scripts/review.mjs --lang es            # inspect first
+node scripts/review.mjs --lang es --purge    # only once you believe the flags
+node scripts/translate.mjs --lang es --batch 6   # smaller batches for the awkward units
+node scripts/review.mjs --lang es            # confirm the rate dropped
+```
+
+Always run the inspect step and **read the samples** before purging. Both known
+purge disasters happened because purge followed detection automatically — which is why
+`finalize.sh` requires an explicit `--purge` flag rather than doing it for you.
+
+A concrete example of the danger: a set of postal-address blocks was flagged
+"untranslated / high-overlap" (false positives — addresses are mostly proper nouns).
+Purging and re-translating them replaced *correct* localised text with the source
+language: `"Correo electrónico"` came back as `"Email:"`. The flags were right that the
+strings looked unusual, and wrong that they needed fixing.