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

What the bug is. serve() in scripts/docs/translations.py has two layout strategies. When state.changed is empty (pure reorder/removal), commit 00e9565 made it hash-correct: stored = recorded_sections(state.translation); body = "".join(stored[value] for value in state.hashes). But when state.changed is non-empty — an ordinary docs-restructure commit that edits one section and moves others — the first branch runs body = state.translation.body, i.e. the stored translation in its old positional order, against today's reordered English. reimpose() then pins today's English heading ids onto the translation purely by position (_pin_headings) and copies English fences by position (_restore_fences), cross-wiring both.\n\nStep-by-step proof (reproduced by three independent verifiers executing the module's own functions at PR head). (1) English page with sections [Alpha, Beta, Gamma], faithfully translated; provenance records the three hashes in that order. (2) One English commit edits Alpha and swaps Beta/Gamma → English is now [Alpha', Gamma, Beta]. (3) classify(): h(Beta) and h(Gamma) are both still in the recorded set, so only the edited index lands in changed — changed=[0], status outdated. (4) serve() takes the if state.changed: branch, so body is [tAlpha, tBeta, tGamma] against English [Alpha', Gamma, Beta]. (5) reimpose() returns a clean str: the staged page contains ## Beta-DE {#gamma} and ## Gamma-DE {#beta} — every cross-page link to #gamma lands on the Beta translation's text. When the swapped sections each carry one fence, _restore_fences splices Gamma's code block into the Beta section (per-position counts 1==1), silently.\n\nWhy the existing safety net misses it. The Mismatch → serve-English fallback fires only on heading count/level differences, per-position fence-count differences, or per-position link-target differences. Two swapped prose-shaped sections with the same internal structure match on all three checks, so the reply sails through and stage exits 0 with only the generic "outdated" notice. The regression test added in 00e9565 (test_stage_lays_out_reordered_and_removed_sections_by_their_recorded_hashes_never_by_position) exercises only the pure-reorder case (changed==[]), so the commit's claim that "a reordered English page can no longer pair code blocks or heading ids with the wrong section" does not hold for the edit+reorder combination.\n\nImpact. deploy-docs.yml rebuilds on any docs/** merge, so from the moment the English restructure merges until someone manually runs translate, all 12 language sites serve pages whose anchors point at the wrong section's text (and, in the fence variant, whose code blocks sit under the wrong headings) — an unbounded window, with no diagnostic beyond the generic outdated notice. The window closes on the next translate run because carry_forward() is already hash-correct (it keys prior sections by recorded hash via recorded_sections(job.previous)), so only the staged/deployed output is wrong, never the committed translation files.\n\nHow to fix. In the changed-non-empty branch, lay out sections by recorded hash exactly as the else branch does, substituting the positional text only for the indices in state.changed (whose sections have no stored counterpart): e.g. build stored = recorded_sections(state.translation) plus a positional list of the stored body's sections, then for each index in state.hashes take stored[hash] when the hash is recorded and the positional stored section otherwise. Alternatively, fall back to English whenever the recorded hashes of the unchanged sections are not in the same relative order as in state.hashes. Extending the 00e9565 regression test with an edit+reorder case would lock the behavior in.\n\nWhy normal severity. This is not a latent corner case: editing a section while moving others is a routine docs-restructure commit shape, the failure ships incorrect published content (wrong anchor targets, potentially wrong code blocks) on every language site, and it is specifically the surviving half of a defect class the author already judged fix-worthy during this PR's review — 00e9565 fixed the sibling pure-reorder case and its test now gives false confidence that the whole class is closed. The fix is small and local to serve().

What the bug is. unwrap() in scripts/docs/translations.py (lines 682-689) normalizes the tail of a model reply in one direction only: if english.endswith("\n") and not reply.endswith("\n"): reply += "\n". A reply that ends with a surplus newline (...\n\n where the English ends ...\n) is left untouched. No downstream check catches it either: reimpose() verifies fences, heading counts/ids and link targets, and validate() checks code spans, !!!/===/??? markers, list-item and table-row counts, banned glossary renderings and English placeholder patterns — a bare extra newline trips none of them. This was reproduced end-to-end by three independent verifiers executing the module's own functions on this head.\n\nWhy it persists forever. The accepted page is written with the surplus newline in its last section's bytes (sections() assigns trailing newlines to the last section), but with_provenance() records only the English section hashes (job.state.hashes) — never a digest of the translated bytes. classify() therefore reports the page current indefinitely; nothing ever flags the drifted section for re-translation, and carry_forward() reproduces it byte-for-byte on every subsequent run. update_request() even presents the drifted body to the model as the previous translation to reproduce line by line, so the drift self-propagates.\n\nHow it surfaces mid-page. The surplus newline is invisible while the section stays last. But when a later English edit appends a new section after it (or reorders sections), carry_forward()/serve() splice the stored section into a middle position via recorded_sections(). Because sections() assigns the blank line above a heading to the following section, the assembled body reads ...text.\n\n\n## Next where the English has ...text.\n\n## Next — a doubled blank line mid-page. The second reimpose/validate pass accepts this too (carried sections are exempt from validation anyway), the file re-records clean English hashes, and the drift is permanent.\n\nStep-by-step proof (as reproduced by the verifiers): (1) the model's reply for a two-section page ends Inhalt eins.\n\n against English Content one.\n; unwrap() leaves it, reimpose() and validate() return clean, the page is written and classified current. (2) The English page gains a new ## Two section after the last one; the page becomes outdated for that section only. (3) carry_forward() maps the stored first-section bytes (tail \n\n) ahead of the freshly translated new section (which starts \n## ), producing Inhalt eins.\n\n\n## Zwei — one blank line in the English, two in the translation. (4) All checks pass again; recorded_sections() stores the drifted bytes keyed by the clean English hash, so every future run carries them and status never reports anything wrong.\n\nImpact and why this is a nit. Rendered HTML is identical — Markdown collapses blank-line runs — so no reader ever sees the drift. The harm is that it permanently violates the tool's own contract (i18n/README.md line 18: sections are kept "byte for byte"; the PR description: "a one-line English edit is a one-line translated diff"; general-prompt.md: "the same blank lines between blocks"), producing unrelated whitespace hunks in generated-page diffs on every later partial update, with no detection or self-healing short of a full --pages retranslation of the affected page. The trigger also requires the model to emit a surplus trailing newline — plausible but not guaranteed — and this is docs-publishing tooling, not the shipped library.\n\nHow to fix. In unwrap(), when the English body ends with a single trailing newline, replace the append-only branch with reply = reply.rstrip("\n") + "\n" so both a missing and a surplus tail newline normalize to the English shape. (Alternatively, emit a findings entry for tail blank-line mismatches so the existing repair loop handles it, but the one-liner is simpler and mechanical.) A small unit test pairing an English page ending \n with replies ending `` (no newline), \n and `\n\n` would pin the behavior.

What the bug is. docs/js/language-switch.js rewrites the theme's language-switcher entries to point at the current page on each language site. The path half already handles the one exception: samePage() (lines 12-15) computes entry.dataset.site + (page.startsWith("api/") ? "" : page), deliberately sending a reader on an API page to the bare language root, because the API reference exists only on the English site — the file's own header comment says so ("The API reference is English-only, so from there the entries keep pointing at the site roots"). But the click-time enrichment added in 00e9565, aim() (lines 26-31), sets entry.href = samePage(entry) + location.search + location.hash with no such guard, so the fragment and query are appended even when samePage() just resolved to the site root.\n\nThe code path that triggers it. aim is registered as a capture-phase listener for click, auxclick, and keydown (Enter). A reader on an English API deep link — e.g. /api/mcp/index/#mcp.ClientSession, which is the standard shape of shared mkdocstrings anchors — opens the language switcher and clicks a language entry. aim() fires before navigation, calls samePage(entry) (which returns /de/ because the page is under api/), then appends location.hash, producing /de/#mcp.ClientSession. Any ?h= search-highlight query is carried the same way.\n\nWhy existing code doesn't prevent it. The api/ special case lives entirely inside samePage()'s path computation; the fragment/query append happens outside it, in aim(). The subscribe-time href (document$.subscribe, line 20) appends nothing, so inspecting the rendered hrefs shows correct targets — the defect appears only on real clicks/auxclicks/Enter, which is exactly why it's easy to miss. The comment justifying the append ("Headings carry the same ids on every site") is true only for prose pages, which exist at the same path on every language site; it doesn't hold for the API-reference-to-root mapping.\n\nStep-by-step proof.\n1. Reader is on https://py.sdk.modelcontextprotocol.io/api/mcp/index/#mcp.ClientSession.\n2. On document$, each switcher entry gets entry.dataset.site = "/de/" (etc.) and entry.href = samePage(entry) → /de/ — correct, per the API special case.\n3. Reader clicks the "de - Deutsch" entry. aim() runs in the capture phase: samePage(entry) → /de/ (page api/mcp/index/ starts with api/, so "" is appended), then + location.search + location.hash → /de/#mcp.ClientSession.\n4. The browser navigates to the German home page with a fragment for a heading id that only exists on the English API page. The browser ignores the unmatched fragment; the URL in the address bar carries the dangling #mcp.ClientSession (and any ?h= query lands on the home page too).\n\nImpact and fix. Impact is cosmetic — the reader still lands on the intended page (the language home), nothing 404s, the fragment simply dangles and a stray highlight query may ride along — hence nit severity. The fix is one line either way: guard the append in aim() (e.g. const onApi = location.pathname.slice(site.length).startsWith("api/") and skip location.search + location.hash when onApi), or have samePage() return both the target and whether the page path carried over, and append only when it did.

What the bug is. load_glossary (scripts/docs/translations.py:307-317) promises in its docstring to raise ConfigError when glossary.json is "not that shape", but its exception net only catches OSError/JSONDecodeError/TypeError/KeyError from Term(**entry) and tuple(raw['keep']). Term is a plain frozen dataclass with avoid: Sequence[str] = () — dataclasses do not enforce annotations at runtime, and a Python str structurally is a Sequence[str]: iterating it yields its characters. So the natural singular slip "avoid": "Gastgeber" loads without error, and tuple("MCP") for a bare-string keep silently becomes ('M', 'C', 'P').\n\nThe code path that triggers it. Once loaded, glossary_prompt() renders the exploded string into every request's system prompt — - host → Host (never: G, a, s, t, g, e, b, e, r) — and validate()'s banned-rendering scan (translations.py:788-794, for avoid in term.avoid if avoid.casefold() in folded) checks each single letter as a banned substring of the translated output. A bare-string keep likewise lists single letters (- M, - C, - P) as "terms that stay in English" in every cached system prompt.\n\nStep-by-step proof (reproduced by verifiers executing the module's own functions on this head):\n\n1. Write glossary.json with {"keep": "MCP", "terms": [{"source": "host", "target": "Host", "avoid": "Gastgeber"}]}.\n2. load_glossary(path) returns successfully — no exception in the net fires, so the documented ConfigError never happens.\n3. glossary_prompt(g) renders - host → Host (never: G, a, s, t, g, e, b, e, r) into the system prompt for every page.\n4. validate('The server is great.', 'Der Server ist gut.', g, 'test') returns 7 findings of the form banned rendering 'e' of 'host' appears: use 'Host' — one per distinct character of "Gastgeber" present in the output.\n5. Since single letters like 'e' occur on essentially every page in every target language, the constraint is unsatisfiable: every open page of the next translate run burns its full 1 + MAX_REPAIRS paid model calls (no reply can avoid the letter 'e'), then fails with per-letter diagnostics that never point at the malformed glossary field.\n\nWhy existing code doesn't prevent it. The type annotation Sequence[str] is exactly the type that makes this slip invisible: it is satisfied at runtime by the wrong value, pyright doesn't check JSON-derived dicts, and no test exercises a bare-string shape. The failure surfaces two steps removed from its cause — in validate()'s output during a paid run — which is the opposite of the tool's documented fail-fast contract (offline exit 2 before any API call).\n\nWhy it's realistic and what the impact is. glossary.json is exactly the file this PR routes contributor and native-reviewer corrections into (CONTRIBUTING.md, docs/translations.md, and the i18n/README.md line this comment anchors on all direct edits there), and the singular "avoid": "X" is a natural mistake for a one-item ban list. The cost if it lands: one wasted paid run across all open pages, exit 1, and diagnostics that actively mislead. It's a nit rather than blocking because this is docs tooling, not the shipped mcp package — nothing in CI calls the API, the committed glossaries are well-formed, and recovery is just fixing the JSON and rerunning.\n\nHow to fix. In load_glossary, reject the string shape explicitly before constructing the dataclasses, e.g.:\n\npython\nif isinstance(raw["keep"], str) or any(isinstance(e.get("avoid"), str) for e in raw["terms"]):\n raise ConfigError(f"{path}: 'keep' and 'avoid' must be lists of strings, not a bare string")\n\n\nThis preserves the exit-2 fail-fast contract the docstring already documents.

What the bug is. Six of the twelve hand-written per-language style guides end with a sentence telling contributors never to edit the generated pages/ (and, in most, notices.md) "which the next translation run overwrites." That rationale is inverted for the shipped tool: a hand edit is sticky, not transient. The de, fr, pt, ru, zh, and zh-hant files all carry the sentence verbatim (de/fr/ru/zh-hant at lines 169-170, pt at 189-190, zh at 157-158), while the other six languages (es, hi, ja, ko, tr, uk) state the same never-edit policy without the false mechanism claim.

Why the claim is factually wrong. classify() in scripts/docs/translations.py (~line 500) computes a page's status purely by comparing the recorded English section hashes in the page's front matter against the current English source — tuple(hashes) == recorded. The translated body is never hashed or inspected. So a hand-edited generated page whose English source is unchanged stays current, is never selected by select_jobs() (which, absent --pages, picks only non-current pages), and no translation run ever touches it. Worse, when the English does later change in some other section, carry_forward() (~line 843) rebuilds every unchanged section byte-for-byte from recorded_sections(job.previous) — i.e. from the on-disk hand-edited body — and _validate_open() exempts carried sections from validation. The hand edit is thereby laundered into fresh tool output, permanently escaping the glossary and parity checks.

Why this survived the head commit. An earlier review comment flagged exactly this inverted rationale on CONTRIBUTING.md line 131, and the head commit (00e9565) accepted it, rewriting that sentence to the accurate mechanism: "the tool can't tell a hand edit from its own output, so the edit persists unchecked, is carried forward into future runs, and hides the real fix." But the commit touched no instructions.md files, so the same false claim survives in six of the seven places it appeared. This is not a duplicate of that earlier finding — that comment named only CONTRIBUTING.md and was resolved there; these six occurrences are the residual sites the fix missed.

Why it matters. These files are the very documents the PR's recommended reading order sends contributors to (i18n/general-prompt.md → i18n/<lang>/instructions.md → ...), and the "it gets overwritten anyway" justification actively invites the failure mode it is meant to prevent: a contributor who trusts it may hand-edit a generated page believing the edit is harmless and temporary, when in fact it persists indefinitely, undetected, and gets reproduced as future tool output. The corrected CONTRIBUTING.md wording exists precisely to close that trap, so leaving the old wording in the per-language guides undercuts the fix the author already made.

Step-by-step proof. (1) A contributor reads i18n/de/instructions.md:169-170, sees "never edit the generated pages/ ... which the next translation run overwrites," and hand-edits a sentence in i18n/de/pages/servers/tools.md, assuming the tool will replace it anyway. (2) On the next translate run, classify() re-hashes the English docs/servers/tools.md, finds tuple(hashes) == recorded, and reports the page current — it is never re-run; the "overwrite" never happens. (3) Months later a different ## section of the English page changes; the page becomes outdated and translate runs, but carry_forward() copies the hand-edited section byte-for-byte into the regenerated file, skipping validation for it. (4) The edit is now indistinguishable from tool output, and no command (status records only English hashes) can ever surface it.

How to fix. A mechanical rewording of six sentences: replace the "which the next translation run overwrites" clause in each of the six files with either the corrected CONTRIBUTING.md rationale (the tool can't tell a hand edit from its own output, so the edit persists unchecked and is carried forward) or the neutral phrasing the other six language guides already use (the generated pages are never edited by hand; corrections go into this file or the glossary). Docs-accuracy only — nothing breaks at merge time — hence nit severity.