docs: translated documentation sites and the tooling behind them

[maxisbey]

First of a small series that ships the SDK docs in other languages. This one
lays the groundwork and includes machine-translated preview sites for
Simplified Chinese, Japanese, Korean, and Brazilian Portuguese (a few pages
each to start), served at /zh-CN/, /ja/, /ko/, and /pt-BR/ next to
the English site. English stays the single source of truth; everything else is
generated and never hand-edited.

• How translation works — scripts/docs/i18n is a manually-run tool
  (status, translate, check, verify, prune, stage). It splits a
  page into sections, translates only what changed, carries unchanged
  sections forward byte-for-byte from the previous translation, validates
  structure (headings/anchors, code, links, admonitions, tables, glossary
  terms) with retries, and runs a second-model adversarial pass hunting
  meaning inversions before a page is written. Per-language inputs live in
  i18n/languages/<lang>/: instructions.md (register, voice, typography)
  and glossary.json (termbase + keep-in-English list + banned renderings) are
  the human-edited part; pages/, nav.yml, state.json are generated.
• Corrections are inputs, not edits — fixing a translation means changing
  the instructions or glossary and regenerating; corrections then hold across
  every page and every future run instead of being clobbered by the next one.
  docs/translations.md explains this to readers, with an issue form for
  reports.
• The build — scripts/docs/build.sh builds English, then each language:
  stage the tree (English overlaid with that language's translations, plus
  status banners — machine-translated / possibly-behind-English / not yet
  translated / English-only), generate its config (translated nav labels,
  language switcher, hreflang alternates), build it strictly. Language sites
  link the one English API reference rather than rebuilding it; four languages
  add ~25s to the ~50s English build.
• Heading anchors are now explicit on every prose heading ({#id},
  seeded from the ids the current build already renders, so no link changes)
  and a check keeps it that way — that's what makes anchors stable across
  languages and across heading rewording.
• Staleness contract — each language records the English commit/content
  hashes it was translated from; status shows missing/outdated/current,
  check validates offline without ever failing on staleness (stale pages
  are bannered, not build errors), and a later PR adds the scheduled job that
  keeps things fresh.

Intentional behavior changes

None to the SDK. Docs builds now also produce the four language sites, and
every prose heading in docs/ carries an explicit anchor.

Notes for reviewers

• Suggested reading order: i18n/general-prompt.md →
  i18n/languages/ja/instructions.md → docs/translations.md →
  i18n/README.md → the sample pages under i18n/languages/*/pages/ (the
  first real output — a couple of known slips are listed below and are
  fixed via the correction loop, not by editing the pages) → the tool.
• Known follow-ups (not blockers): search on the CJK sites has no
  language-aware tokenisation (theme limitation); the tool prints no
  token/cost usage yet; the semantic gate scored one actor-swap in a pt-BR
  sample as a warning where it should have blocked, so its calibration gets a
  pass; a couple of register slips in the samples (ja italics on emphasis,
  two pt-BR pronouns) become instruction-file rules.
• Merge checklist: create the translation label the issue form applies.
• Model access: running the tool needs ANTHROPIC_API_KEY (or an auth
  token); nothing in CI calls the API in this PR.

_{AI Disclaimer}

[github-actions]

📚 Documentation preview

Preview	https://pr-3231.mcp-python-docs.pages.dev
Deployment	https://6efe4dc4.mcp-python-docs.pages.dev
Commit	e3929bf
Triggered by	@maxisbey
Updated	2026-07-31 17:51:34 UTC