The test fixture wrote its throwaway repo tree with the platform default
encoding, which cannot represent the Japanese fixtures on Windows; write it
(and the tool's own generated pages and state) explicitly as UTF-8 with LF
newlines so the output is identical everywhere.
Ship preview translations of the docs in Simplified Chinese, Japanese,
Korean and Brazilian Portuguese, served at /zh-CN/, /ja/, /ko/ and /pt-BR/
next to the English site (three pages each to start). English stays the
single source of truth; everything else is generated and never hand-edited.
scripts/docs/translations.py drives it (status / translate / stage /
languages). `translate` re-translates only the `##` sections whose English
changed and carries the rest of the page over byte-for-byte from the previous
translation, then gates the result: heading anchors and code blocks are
re-imposed from the English, the structure (sections, headings, fences, links,
inline code, admonitions, glossary rules) is checked with the findings fed
back for another attempt, and a stronger model reviews the meaning against the
English. Per-language inputs — instructions.md (register, voice, typography)
and glossary.json (termbase, keep-in-English list, banned renderings) — are the
human-edited part; the pages and state.json under i18n/<code>/ are generated,
so a correction goes into the inputs and holds across every future run.
The build stages each language over the English tree (translations overlaid,
notices stamped in — machine-translated, may be behind English, not translated
— and links into the API reference pointed at the English one) and builds it
strictly into site/<code>/. Heading ids are pinned into the translations from
the ids the English site renders, so #fragment links resolve on every language
site without touching the English pages. An outdated translation is served
with a warning unless the English page's links or anchors moved under it, so an
English edit can never break a language build. Every config carries the same
language switcher.
Max Isbey