Fix: repair 139 broken relative links across the nine translations

[0xLeif]

Summary

A user reported one broken link in a translated document. A repo-wide scan found 139.

Every translated document lives in docs/i18n/, two directories below the English source it was translated from. The relative paths were carried over verbatim, so each resolved two levels too shallow:

pattern	count	resolved to
](docs/X.md) in all 9 README.<lang>.md	54	docs/i18n/docs/X.md
](../X) in all 9 getting_started.<lang>.md	81	docs/X instead of the repo root
](i18n/X.pt-BR.md) in 4 files	4	docs/i18n/i18n/X.pt-BR.md

Same defect class as the License badge repaired earlier, which was fixed as a single symptom rather than generalised.

Repair policy

Links follow the reader rather than being mechanically re-rooted:

• a document that has a translation → the translated sibling, so a reader who opened the Japanese page stays in Japanese
• code, spec and example paths → the repo root via ../../
• releasing.md → English, because it is deliberately untranslated as an internal maintainer doc

Three defects a path scan cannot see

Independent per-language review ran after the path repair, which is how it caught one this repair introduced:

1. The repair introduced a text/target mismatch. In English, [docs/sessions.md](docs/sessions.md) has text equal to target. Retargeting left the visible text reading docs/sessions.md while the target became sessions.<lang>.md — a working link with a lying label, in all 9 files.
2. README.ru.md had a CommonMark bug unique to Russian — --- sat directly under a paragraph with no blank line, making it a setext H2 underline rather than a horizontal rule. The paragraph rendered as a giant heading and the section rule vanished.
3. Four stale one-language index blocks (pty_architecture.{ar,es,zh-CN}.md, sessions.fr.md) listed 1 of 9 languages, sent readers to the Portuguese document, and asserted the translation itself was authoritative — contradicting line 1 of the same file. The path repair had turned these into working links to the wrong place.

Measured

• 139 broken before → 0 broken across 296 links after (22 in-document anchors, 193 relative paths, 81 external)
• All 8 external URLs return 200, including the shields.io ruby badge whose & needed separate handling
• All 9 translated READMEs retain their 3 badges

The checker recomputes GitHub heading slugs and was validated against two known-working English anchors before being trusted against Arabic, Devanagari, CJK and Cyrillic headings — a slug function wrong about non-ASCII would silently report every translated anchor as broken.

Left open deliberately

34 of 36 translated files carry no language index at all. Only the four English sources have the 9-language block, so a reader on a translated page cannot reach a sibling language. Two independent reviewers flagged it. That is a convention decision across 36 files, not a broken link, so it is not folded into a repair.

Untranslated link text also remains in README.hi.md (7 labels) and README.ru.md (4), where every target is correct — translation completeness, not link breakage.

Test Plan

• Link scan: 0 broken across 296
• specsync change verify passed (4 commands)
• specsync check: lifecycle valid, 32/32 file coverage, 7440/7440 LOC coverage
• Full suite green (611 examples, 0 failures)

CHG-0075, accepted, documentation kind, no spec change.

🤖 Generated with Claude Code

https://claude.ai/code/session_018rf59AtQmJcodUJ6vXDZNY