Repository navigation
docs: publish translated docs in twelve languages and the tool that maintains them - #3280
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
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
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
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
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
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