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

Extend the translated docs to twelve languages

4c0a8bb
Select commit
Loading
Failed to load commit list.
Claude / Claude Code Review completed Aug 11, 2026 in 42m 48s

Code review found 7 potential issues

Found 8 candidates, confirmed 7. See review comments for details.

Details

Severity Count
🔴 Important 0
🟡 Nit 7
🟣 Pre-existing 0
Severity File:Line Issue
🟡 Nit i18n/README.md:14 [quality] translate constructs the API client (credentials + anthropic package) even for runs that make zero model calls
🟡 Nit i18n/README.md:18 Code-fence placement validated only page-wide: cross-section fence moves publish silently wrong or abort updates without
🟡 Nit i18n/README.md:11-16 stage() leaves a stale titles.json behind, breaking build_config.py's completeness check after a failed run
🟡 Nit i18n/README.md:13-15 [quality] translations.py re-declares llms_txt.py's code-span and front-matter regexes instead of importing them
🟡 Nit i18n/README.md:8 [quality] 204 committed generated pages (ja/ko/pt/zh) carry a legacy 'inputs:' provenance key the shipped tool no longer
🟡 Nit docs/js/language-switch.js:11-18 language-switch.js drops the URL fragment (and query) when switching languages
🟡 Nit docs/translations.md:13-16 stage/serve() pairs a stale translation positionally with reordered English, cross-wiring fences and heading anchors

Annotations

Check warning on line 14 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

[quality] translate constructs the API client (credentials + anthropic package) even for runs that make zero model calls

`command_translate` constructs the Anthropic client (`translator = translator or anthropic_translator()`, scripts/docs/translations.py:869) before the job loop, so a run whose jobs are all no-call reassembly jobs (English sections only reordered/removed) still exits 2 with ConfigError when the `translate` dependency group or `ANTHROPIC_API_KEY` is absent — even though it would make zero API requests. Constructing the client lazily, e.g. `if any(job.open for job in jobs): translator = translator 

Check warning on line 18 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

Code-fence placement validated only page-wide: cross-section fence moves publish silently wrong or abort updates without repair turns

In `scripts/docs/translations.py` (anchored here because the tool's contract is documented on this line), code-fence placement is validated only page-wide: `_restore_fences` compares fence *counts* across the whole page and restores English fences positionally, while links get per-section checks. A model reply that keeps the fence count but moves a fence across a `##` section boundary is therefore (a) published silently with code under the wrong section on a fresh translation, and (b) on a parti

Check warning on line 16 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

stage() leaves a stale titles.json behind, breaking build_config.py's completeness check after a failed run

stage() deletes only the staged docs tree at the top and writes titles.json only at the very end, so a stage run that fails partway leaves the previous run's titles.json behind — and build_config.py --lang treats that file's presence as "the tree beside it is complete". A subsequent manual build_config then either dies with a confusing nav-validation error or silently builds a half-staged tree. One-line fix: unlink the titles file next to the rmtree at the top of stage() (e.g. staged_titles_file

Check warning on line 15 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

[quality] translations.py re-declares llms_txt.py's code-span and front-matter regexes instead of importing them

scripts/docs/translations.py re-declares two subtle regexes that already exist in llms_txt.py, from which it already imports: CODE_SPAN is byte-identical to llms_txt._CODE_SPAN, and FRONT_MATTER differs from llms_txt._FRONTMATTER only in the capture-group name. Consider exporting the two patterns from llms_txt (or a small shared module) and importing them, as page_url already is, so a future fix to either pattern cannot silently diverge between the translation tool and the llms.txt pipeline.

Check warning on line 8 in i18n/README.md

See this annotation in the file changed.

@claude claude / Claude Code Review

[quality] 204 committed generated pages (ja/ko/pt/zh) carry a legacy 'inputs:' provenance key the shipped tool no longer writes

The 200 generated pages under i18n/ja/, i18n/ko/, i18n/pt/ and i18n/zh/ (49 pages + notices.md per language) still carry a legacy `inputs: <hash>` front-matter key from intermediate commit c65a026, which the shipped tool's `with_provenance()` no longer writes — the other eight languages have no such key. Nothing breaks (`read_provenance()` tolerates it), but half the committed corpus isn't reproducible by the shipped tool, and the first translate run touching each of these pages silently drops t

Check warning on line 18 in docs/js/language-switch.js

See this annotation in the file changed.

@claude claude / Claude Code Review

language-switch.js drops the URL fragment (and query) when switching languages

The language switcher rewrites each entry using only `location.pathname`, so `location.hash` (and `location.search`) are dropped — a reader deep-linked to a section like `/servers/tools/#structured-output` who switches language lands at the top of the target page. Since the translation pipeline pins identical heading ids across all language sites, appending the hash (read at click time) would keep the reader on the same section.

Check warning on line 16 in docs/translations.md

See this annotation in the file changed.

@claude claude / Claude Code Review

stage/serve() pairs a stale translation positionally with reordered English, cross-wiring fences and heading anchors

A pure reorder of `##` sections on an English page makes `classify()` keep the stale translation (status='outdated', changed=[]), and `serve()` in scripts/docs/translations.py then reimposes today's English onto that stale body purely positionally — splicing each code fence under the wrong section's prose and cross-wiring the pinned heading anchors ({#install}/{#test} swapped) — instead of the documented 'served in English until refreshed' fallback. Fix: reorder the stored sections by their reco