Skip to content

docs: publish translated docs in twelve languages and the tool that maintains them - #3280

Merged
maxisbey merged 7 commits into
mainfrom
docs/translations
Aug 14, 2026
Merged

maxisbey merged 7 commits into
mainfrom
docs/translations

Address review comments on the translation tooling

00e9565
Select commit
Loading
Failed to load commit list.
Claude / Claude Code Review completed Aug 11, 2026 in 24m 49s

Code review found 2 important issues

Found 5 candidates, confirmed 18. See review comments for details.

Details

Severity Count
🔴 Important 2
🟡 Nit 16
🟣 Pre-existing 0
Severity File:Line Issue
🔴 Important i18n/README.md:16 serve() still cross-wires anchors/fences when an English change both edits and reorders sections
🟡 Nit i18n/README.md:18 Surplus trailing newlines in a model reply are baked in and surface as mid-page blank-line drift
🟡 Nit docs/js/language-switch.js:26-31 Language switcher carries the API page fragment/query onto the language-site home page
🟡 Nit i18n/README.md:7 load_glossary accepts a bare string for avoid/keep, exploding it into per-character banned renderings that fail every pa
🟡 Nit i18n/de/instructions.md:169-170 Six instructions.md files still claim hand edits are overwritten by the next run

Annotations

Check failure on line 16 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

serve() still cross-wires anchors/fences when an English change both edits and reorders sections

The 00e9565 fix for reorder cross-wiring covers only serve()'s changed==[] branch (scripts/docs/translations.py:944-948): when one English commit both edits a section and reorders others, the changed-non-empty branch still lays the stored translation out in its old positional order, so reimpose() pins today's heading ids (and copies fences) onto the wrong sections, and the staged site serves cross-wired anchors on all 12 language sites until someone runs translate. Fix: in the changed-non-empty 

Check warning on line 18 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

Surplus trailing newlines in a model reply are baked in and surface as mid-page blank-line drift

unwrap() in scripts/docs/translations.py (lines 682-689) appends a missing trailing newline to a model reply but never trims a surplus one, and no later validator inspects blank-line structure, so a reply ending with an extra newline is written and recorded as current under the English section hashes. When a later English edit appends or reorders sections, carry_forward()/serve() splice the stored last section into a middle position and its surplus newline becomes a doubled blank line mid-page, 

Check warning on line 31 in docs/js/language-switch.js

See this annotation in the file changed.

@claude claude / Claude Code Review

Language switcher carries the API page fragment/query onto the language-site home page

The click-time href enrichment in aim() appends location.search + location.hash unconditionally, but samePage() deliberately maps api/ pages to the bare language root (the API reference is English-only) — so switching language from an API deep link like /api/mcp/index/#mcp.ClientSession sends the reader to /de/#mcp.ClientSession, the language home page with a dangling fragment (and any ?h= highlight query carried along). Fix: skip the append when the current page is under api/, e.g. guard on !lo

Check warning on line 7 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

load_glossary accepts a bare string for avoid/keep, exploding it into per-character banned renderings that fail every page of a paid run

load_glossary silently accepts a bare string for a term's `avoid` (or the top-level `keep`) — e.g. `"avoid": "Gastgeber"` instead of `["Gastgeber"]` — because a str satisfies `Sequence[str]` by iterating its characters, so every letter becomes a banned rendering and every page of the next paid translate run fails validation with baffling per-letter findings. Add an isinstance shape check in load_glossary so this raises ConfigError (exit 2, before any API call), as its docstring already promises.

Check warning on line 170 in i18n/de/instructions.md

See this annotation in the file changed.

@claude claude / Claude Code Review

Six instructions.md files still claim hand edits are overwritten by the next run

The head commit fixed the inverted never-edit rationale in CONTRIBUTING.md, but the same false "the next translation run overwrites" claim survives verbatim in six hand-written style guides: i18n/de/instructions.md:169-170, i18n/fr/instructions.md:169-170, i18n/pt/instructions.md:189-190, i18n/ru/instructions.md:169-170, i18n/zh/instructions.md:157-158, and i18n/zh-hant/instructions.md:169-170. The tool never overwrites a hand-edited page — classify() only hashes the English source, so the edit