docs: preserve English heading anchors in translated pages - #4580

Summary

Translating a heading changes the id mkdocs derives from it. The links inside the translated pages still point at the English ids, so once translate_docs.py has run, every #... link on those pages stops resolving. A build of current main reports 273 of them across docs/ja, docs/ko and docs/zh, and none in the English pages. I could not find an issue for it.

attr_list is already on, so a heading can carry its id explicitly. This change makes the translation script do that.

After a page is translated, each heading gets {#<id>}, where <id> is the id the site renders for the English heading at the same position. The ids come from the parser itself: the script builds a Markdown instance from the markdown_extensions in mkdocs.yml (plus the toc, tables and fenced_code builtins mkdocs adds) and reads them off the toc tokens, so reference links, entities, inline HTML and repeated headings (example, then example_1) all come out the way mkdocs produces them. The H1 is left alone, since mkdocs takes the page title from it.

When a page is skipped as up to date, the same step runs over its existing translations, so the next make translate repairs the current pages without sending anything back through the model.

The contract is the shape the docs already use: one ATX heading in the translation per English heading, carrying no attribute list other than the {#id} written here. Translated headings are located with the parser's own hash-heading grammar and any existing attribute list is recognised with the attr_list extension's own grammar. A page outside that shape is reported by name and left as it is. Before a rewritten page is returned it is parsed again with the same extensions and has to render exactly the English ids, so a page that gets written is a page the site will link correctly. All 114 generated pages on main are inside the contract today.

The regenerated pages are not in this PR. AGENTS.md treats them as generated output, so producing them stays with make translate.

Why

These links are easy to miss. make build-docs does not run in strict mode, and the warnings sit in a log that already carries several thousand lines of autorefs and griffe output. A reader on the Japanese, Korean or Chinese site who clicks "see the dynamic instructions section" lands nowhere.

I also checked whether any of the 273 pointed at an H1. Once each warning is resolved to its target page, and same-named H2s on other pages are ruled out, none do. Skipping the H1 costs nothing.

Validation

• uv run pytest tests/docs/test_translate_docs.py: 4 new tests, failing on main with AttributeError, passing here
• ruff check and ruff format --check on both files; pyright tests/docs reports 0 errors
• Ran the script on the up-to-date path over all 37 English sources with a placeholder API key (that path makes no model calls): 37 skipped, 102 translated pages refreshed
• git diff of the refreshed pages: 1365 changed lines, every one of them an H2 to H6 heading; no H1 and no non-heading line touched; line endings preserved byte for byte
• uv run mkdocs build before and after: anchor warnings 273 to 0, total warnings 9783 to 9510 (the difference is exactly 273), no new warning kinds
• Rendered output: site/ja/agents/index.html has <h2 id="dynamic-instructions">, site/ko/running_agents/index.html has <h3 id="choose-a-memory-strategy">, and the page <title> elements are unchanged
• The refreshed pages were then discarded; only the script and the test are committed

Not run: a translation through the model. The hook in translate_file sits after the existing placeholder checks and before the search-exclusion front matter goes on, so it sees the same text that gets written to disk.

Notes for reviewers

The part I am least sure about is refreshing existing translations on the "skipped, up to date" path. A skip can now write files, which it never did before. The alternative is a separate flag, but then the 273 stay broken until someone remembers to run it, and the refresh is cheap and idempotent. If you would rather keep the skip path read-only, moving this behind a flag is a small change.

Two things I noticed and did not touch. docs/ja/sessions.md, docs/ko/sessions.md and docs/zh/sessions.md no longer have an English source; docs/sessions.md is gone from main, so those three are stale generated pages the script will never revisit. And on Windows, "ref/" in relative_path in translate_single_source_file does not match the backslash form that os.path.relpath returns, so the ref/ pages get picked up for translation there. Neither is related to this change, and the second only matters on Windows, which is presumably not where the translations are produced.