Adopt the client's translation pipeline: glossaries, MQM review, and a fail-closed write

[emooreatx]

The site already mirrors our language set — src/i18n/config.ts says so outright ("Language set + native names mirror CIRISAgent's localization manifest so the site and the app agree"), and dictionaries/ and chrome/ carry the same 29 codes as the client bundles.

What is missing is everything that produces and defends those translations. .github/workflows/ has sonar.yml and nothing else.

CIRISClient has run that machinery for several releases now and it is repo-agnostic in principle. This is an offer to hand it over, plus an honest account of what ports cleanly and what does not.

What you would get

29 glossaries — 3,045 canonical term pairs. localization/glossaries/{code}_glossary.md. Each is a table of CIRIS terms of art with their agreed rendering per language, plus that language's standing prose rules (use the formal እርስዎ; never omit Yoruba's dot-below). These are the same terms the site uses — OBSERVE, DEFER, Wise Authority, accord holder — so the glossaries are not merely reusable here, they are the thing that keeps the site and the app from drifting apart in 29 languages at once.

Translation memory: ~3,853 keys × 29 locales of shipped strings. A model asked to translate "node" cold will pick something; the corpus already knows what we picked, and picked it consistently.

Three lanes — --lane translate | evaluate | repair:

• translate fills missing keys, glossary-first
• evaluate is MQM, not a vibe: reference-free span-level review over {accuracy, fluency, terminology, style, locale} × {critical, major, minor}, scored by severity weight (10/5/1), emitting the error spans and deriving the score rather than emitting a number nobody can act on
• repair takes what evaluate rejected and fixes it

A fail-closed write. Only accepted values ever land:

withheld = set(rejected.get(lang, {})) | set(unrepaired)
writable = {k: v for k, v in values.items() if k not in withheld}

A rejected translation is not written. Not written-with-a-warning — not written.

Terminology fails at any severity. Critical and major reject for the obvious reasons; terminology joins them even as a minor, because the glossary makes it objective — the canonical term is written down, so "disagrees with the glossary" is a fact rather than a judgement, and letting it ship is how terminology consistency stops being true.

Why I think this is worth your time specifically

ACCORD_TERMINOLOGY_NOTES.md is a hand-maintained file tracking whether v6–v9 say "Section" or "Book", with a status column and ⚠️ markers. That is a glossary, kept by hand, in one language, with no enforcement — and it is the exact failure the terminology rule above turns into a build error. In 29 languages that file does not scale; the machinery already exists.

What ports cleanly, and what does not

Ports directly — src/i18n/dictionaries/*.json and src/i18n/chrome/*.json. Flat key-value bundles keyed off an English source are precisely what the pipeline is built for. Writes are position-preserving against en.json so the diff stays reviewable.

Does NOT port as-is — content/docs/**/*.mdx. The pipeline translates strings, not long-form prose with JSX in it. Machine-translating the Constitution is a different problem with a different risk profile, and I would not claim this tool solves it. Two honest options: keep long-form English-only for now, or run the evaluate lane over human translations of it — the MQM review and the glossary checks work fine on prose the tool did not write.

Needs generalising — the write path. insert() writes four byte-identical mirrors because that is the client's layout (android/desktop/ios/shared). Yours is two trees, not four. That is a config change, not a redesign, and it is the main piece of work in adopting this.

Suggested sequencing

1. Lift localize.py's mirror list into config; point it at dictionaries/ + chrome/
2. Copy the 29 glossaries over as-is
3. Run --lane evaluate --check against what you already have — this tells you the current state before changing anything, and is the cheapest way to see whether this is worth continuing
4. Port i18n-lane.yml for CI, running fail-closed
5. Decide the MDX question separately, on its own merits

Happy to do the porting rather than just hand you a link — say the word. The client-side lane is at localization/localize.py and .github/workflows/i18n-{translate,evaluate,repair,lane}.yml in CIRISAI/CIRISClient, and localization/TRANSLATION_GUIDE.md documents what the pipeline does and does not guarantee.

[emooreatx]

What the lane needs to run: two secrets

localize.py picks its provider from the environment (localization/localize.py:136-141) and needs one of:

secret	drives
OPENROUTER_API_KEY	the OpenRouter path — the model ladder ids are OpenRouter slugs, and :batch halves the cost
ANTHROPIC_API_KEY	the Anthropic path

Either alone is enough; with both present OpenRouter wins. LOCALIZE_PROVIDER forces the choice.

Current state: this repo has no Actions secrets. It inherits SONAR_TOKEN from the org, so the org-secret path already reaches here — which is the cleaner way to do this than a third per-repo copy. CIRISClient and CIRISAgent each carry their own copies today, so a key rotation is currently three places instead of one.

Two suggestions for whoever wires this up:

1. Prefer an org-level secret scoped to the repos that need it over adding a third copy. SONAR_TOKEN shows the mechanism already works for this repo.
2. Consider a separate, budget-capped key for the website rather than sharing the client's. These keys bill, and the translate lane is the expensive one — a full 29-language fan-out is not a cheap accident to make twice. A distinct key means the site's spend is visible and bounded on its own line, and a runaway lane here cannot exhaust the client's budget mid-release.

No blocker for step 3 in the issue above, incidentally — --lane evaluate --check reports what is missing without calling a model, so you can see the current state before any key is provisioned.

[emooreatx]

Adopted in 0a49b7f, following the issue's own sequencing:

1. The mirror list is config — the port is exactly one file: a website localization/check_localization_sync.py shim supplying the five symbols localize.py imports (CANONICAL_BUNDLE, MIRROR_BUNDLES, flat_values, manifest_languages, _PLACEHOLDER), with LOCALIZE_BUNDLE=dictionaries|chrome selecting between the site's two single-copy trees. localize.py, glossary.py and the guide came over verbatim, so upstream improvements keep porting cleanly.
2. The 28 glossaries copied as-is.
3. --check run against both bundles: all languages at parity. The evaluate lane dry-runs cleanly against the real dictionaries (104-key sample plan: ladder resolved, glossary terms in scope, cacheable prefix computed).
4. i18n-lane.yml ported as a single workflow_dispatch with a bundle input, the client-specific stages removed (no emitter checkout, no vendoring digest — en.json is the canonical surface here), the parity check as the gate, and the bank-accepted-values-on-failure commit behavior preserved.
5. The MDX question resolved itself: content/docs/** was retired wholesale in ae11785; /sections/** now 301s to /constitution.

Blocked on one thing only: OPENROUTER_API_KEY (or ANTHROPIC_API_KEY) as a repo secret, after which the full-site evaluate is one workflow dispatch per bundle. Known scope edge, same as the client's: flat_values treats arrays as single leaves, so array contents (lobby.doors, stats, parts) remain outside the addressable surface until the write path grows array support.

[emooreatx]

Bug in drive.sh that you'll inherit if you adopt it as-is — worth fixing before it hides something on your side.

python3 localization/localize.py --lane "$LANE" ... 2>&1 | tail -20
rc=$?

$? in a pipeline is the LAST command's status. That's tail, which exits 0 no matter what it was handed. So rc has never once been localize.py's exit code: every refusal, every crash and every 402 has reported

DONE after 1 attempt(s): lane clean

and the retry-with-backoff loop underneath — the entire reason the driver exists over calling localize.py directly — has never fired.

How it surfaced. Translating eleven new chat ids into 29 languages, the lane refused:

[refuse] 616 > --max-keys 500. A run this large should be deliberate...

It translated nothing, and drive.sh printed DONE ... lane clean and exited 0. Had I trusted the driver, eleven ids would have shipped as English in 29 languages with a green log saying they hadn't.

Worth stressing that the refusal itself was good — localize.py did exactly the right thing and said so clearly. Only the wrapper's reading of it was wrong. That's the more dangerous shape: the safety check fires, and the layer above reports success anyway.

The fix is one line — rc=${PIPESTATUS[0]} instead of rc=$? (bash-only, and the script is already #!/usr/bin/env bash). Ours is at CIRISClient cad07d3. Verified by re-running the same refusing case: it now reports lane exit 2, backs off, and exits 1.

Two things this might be worth checking on your side:

1. Any log you have that says "lane clean" proves nothing about whether the lane did anything. If you've run this during evaluation, the parity check (localize.py --check) is the honest signal, not the driver's exit.
2. The same shape elsewhere. cmd | tee log and cmd | tail in CI steps have this bug wherever the exit code is then read. We hit an identical class in our PyPI publish gate, where retries were dead code under bash -e — a status that was never the one under test.

Not urgent for you unless you're already driving lanes; the sooner it's in, the smaller the window where a green run means nothing.