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