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