Symptom
When translating a section that has a MyST label anchor placed immediately before its heading, the translator drops the (label)= line. The heading is translated correctly, but cross-references targeting the label become unresolved, which fails the Jupyter Book build (CI uses -W and converts warnings to errors).
Example
Upstream source (lecture-python-programming/lectures/jax_intro.md):
(jax_at_workaround)=
#### A Workaround
Translation output (lecture-python-programming.zh-cn/lectures/jax_intro.md on main, before fix):
The (jax_at_workaround)= line was silently dropped. A later sync (numpy_vs_numba_vs_jax.md) introduced a {ref}\jax_at_workaround`` cross-reference, which then failed to resolve and broke the build in PR #57.
Fix applied downstream
lecture-python-programming.zh-cn@5718949 — restored the anchor manually.
Source SHA for repro
- Source:
QuantEcon/lecture-python-programming @ 450bafecd23db638602150b47f4272b98aad3146
- Target:
QuantEcon/lecture-python-programming.zh-cn
- Model:
claude-sonnet-4-6
Suggested fix
Preserve any (label)= lines verbatim when translating the heading that follows. These are MyST cross-reference anchors and must be kept identical to the source — the label itself is not translatable content.
This pattern is likely systematic; worth scanning past translation outputs for other dropped anchors.
Symptom
When translating a section that has a MyST label anchor placed immediately before its heading, the translator drops the
(label)=line. The heading is translated correctly, but cross-references targeting the label become unresolved, which fails the Jupyter Book build (CI uses-Wand converts warnings to errors).Example
Upstream source (
lecture-python-programming/lectures/jax_intro.md):(jax_at_workaround)= #### A WorkaroundTranslation output (
lecture-python-programming.zh-cn/lectures/jax_intro.mdonmain, before fix):#### 变通方法The
(jax_at_workaround)=line was silently dropped. A later sync (numpy_vs_numba_vs_jax.md) introduced a{ref}\jax_at_workaround`` cross-reference, which then failed to resolve and broke the build in PR #57.Fix applied downstream
lecture-python-programming.zh-cn@5718949 — restored the anchor manually.
Source SHA for repro
QuantEcon/lecture-python-programming@450bafecd23db638602150b47f4272b98aad3146QuantEcon/lecture-python-programming.zh-cnclaude-sonnet-4-6Suggested fix
Preserve any
(label)=lines verbatim when translating the heading that follows. These are MyST cross-reference anchors and must be kept identical to the source — the label itself is not translatable content.This pattern is likely systematic; worth scanning past translation outputs for other dropped anchors.