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

Serve stored translations as generated; make site links relative

8ed9da1
Select commit
Loading
Failed to load commit list.
Claude / Claude Code Review completed Aug 14, 2026 in 25m 12s

Code review found 2 important issues

Found 4 candidates, confirmed 9. See review comments for details.

Details

Severity Count
🔴 Important 2
🟡 Nit 7
🟣 Pre-existing 0
Severity File:Line Issue
🔴 Important i18n/README.md:16-18 Stale staged translations keep deleted --8<--snippet paths; SnippetMissingError aborts the whole docs build on an Englis
🟡 Nit i18n/README.md:6 render_notice placeholder substitution is byte-exact while validators only guarantee the link target, so a validated not
🟡 Nit i18n/README.md:5 load_registry silently accepts a bare-string exclude in languages.yml, voiding the exclusion
🟡 Nit i18n/README.md:18 Update-path repair loop fails a page over drift in carried sections that carry_forward is about to discard

Annotations

Check failure on line 18 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

Stale staged translations keep deleted --8<--snippet paths; SnippetMissingError aborts the whole docs build on an English-only docs_src rename

Since 8ed9da1, `stage` serves an outdated translation exactly as generated — including its English code fences' old `--8<--` snippet paths — so an ordinary English-only PR that renames or deletes a `docs_src` file leaves every language's staged page pointing at the now-deleted path, and `pymdownx.snippets` (`check_paths: true`) raises `SnippetMissingError`, aborting the whole docs build (docs-preview goes red, `deploy-docs` stops deploying even the English site) until a paid `translate` run acro

Check warning on line 6 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

render_notice placeholder substitution is byte-exact while validators only guarantee the link target, so a validated notices translation can ship a literal ENGLISH_PAGE link site-wide

render_notice() fills the notice placeholders by byte-exact replacement of `(ENGLISH_PAGE)` / `(TRANSLATIONS_PAGE)`, but the validators only guarantee the link *target* — a reply rendering the link as `[englische Seite](ENGLISH_PAGE "…")` or with trailing whitespace passes reimpose() and validate() with zero findings, is accepted as a current translation, and then ships a literal dead `ENGLISH_PAGE` href in the notice stamped on every page of that language site. Fix by substituting by target (e.

Check warning on line 5 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

load_registry silently accepts a bare-string exclude in languages.yml, voiding the exclusion

load_registry (scripts/docs/build_config.py:74-79) silently accepts a bare string for exclude in languages.yml — the natural slip `exclude: migration.md` iterates per character into ['m','i','g',...], voiding the exclusion so the 198 KB migration guide (deliberately never translated) is reported 'missing' and selected as a paid translation job for all 12 languages, with no fail-fast. Apply the same isinstance shape check that 8ed9da1 added to load_glossary so this raises ValueError (exit 2) befo

Check warning on line 18 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

Update-path repair loop fails a page over drift in carried sections that carry_forward is about to discard

In translate_page() (scripts/docs/translations.py:910-918), the first reimpose() pass validates the model's full reply — including closed sections that carry_forward() is about to overwrite byte-for-byte with the stored prior translation — so a benign reproduction drift in a carried section (a dropped link, a merged fence) blocks assembly, burns paid repair turns, and if it persists fails the page (exit 1, all 1+MAX_REPAIRS calls consumed) with a diagnostic blaming a section this run never rewro