Report stale translations and broken anchors

[helmihyo]

Closes #28. Closes #29.

Closes the gap that made translating 21 pages risky: nothing told us when a translation fell behind its source.

What is here

scripts/translation_status.py — sorts every page into missing, unstamped, stale or current. For stale pages it resolves the stamped blob back through git and prints the English diff since the translation was written, which turns "this page is stale" into the specific change to apply. It prints the stamp value to record, so nobody computes a hash by hand.

scripts/check_anchors.py — walks the built HTML and verifies every internal anchor resolves. This broke 16 links during the Finnish translation and mkdocs build --strict did not notice one of them.

scripts/stamp_translation.py — writes the stamp. Deriving the English source from the translation's own path and editing frontmatter by hand is the mechanical step that goes wrong quietly.

.github/workflows/translation-status.yml — comments on PRs touching docs/en/**, scoped to the pages that PR actually changed, and writes the full report to the job summary on every run so pre-existing drift stays visible after the PR that caused it has merged.

.claude/skills/translate-page/SKILL.md — translation as a repeatable operation. Encodes the glossary-first rule, structure and unit requirements, the two markdown traps neither --strict nor GitHub's preview catches, and anchor handling — including the delayed fault where a link in an already-translated page breaks only once its target page is translated.

All 21 Finnish pages stamped, currently all current.

Design, as settled on #25

Report, do not block: fallback_to_default means a lagging translation serves English, so nothing is broken while it lags. State, not commits: the English page carries no token to bump, so an English edit needs no ceremony — the edit changes the content, which changes the hash, which makes its translations report stale on their own.

One decision, since resolved

I implemented anchor validation as reporting, because #25 says "report, do not block" twice — while thinking anchors are a different class: a stale translation is not broken (the page serves English), a broken anchor is a link that goes nowhere and has already shipped. @mairas decided on this PR that it should fail, and it now does. The check runs last so the status report is still published when it fails.

Verified

• Unknown frontmatter key is inert in Material: does not render, does not reach the search index, builds clean under --strict. Checked rather than assumed.
• Detection works, tested against real edits: changed 1.1A → 1.3A in the English errata page and confirmed the report flags exactly that page and shows exactly that line.
• Re-stamp discipline holds: updating a translation alone does not clear the stale flag; only re-stamping does. The mechanism cannot go green by accident.
• Anchor checker catches a real breakage: deliberately broke one anchor, confirmed it was reported and the exit status was 1.
• Full loop end to end: English edit → stale + diff → translation updated → still stale → re-stamp → current.
• The skill's embedded verification snippet runs verbatim and correctly ignores frontmatter.

Not verified

The PR comment path is not exercised by this PR, because it only fires on docs/en/** changes and this PR touches none. The job summary is exercised; the comment logic stays unproven until a PR edits an English page. Flagging so a green run is not read as broader than it is.

🤖 Generated with Claude Code

[mairas]

Yeah, broken anchors should fail the run.

[helmihyo]

Re-review

Your call is implemented

Broken anchors now fail the run. One non-obvious consequence worth knowing: the anchor check had to move to the last step. It was second, and a failing step aborts the ones after it — so a broken anchor would have suppressed the staleness report and the PR comment, hiding one problem behind another. The report is published first, then the run fails.

Two defects found in this pass

Both came from probing the tools rather than re-reading them, and both are fixed in 84e3b6e.

Orphaned translations were invisible. The report walks the English sources, so deleting docs/en/faq.md simply made it stop counting that page — while docs/fi/faq.md stayed in the tree and kept being served. The report went from 21 pages to 20 and said everything was current. There is now an orphaned bucket; verified by deleting a source and watching it appear.

stamp_translation.py would stamp a source page. Given docs/en/faq.md it wrote a self-referential hash into the English page. That inverts the whole design — source pages carry no stamp, which is exactly what makes an English edit ceremony-free, and a stamped source would have been silently wrong forever. It now refuses, and reads the default language from mkdocs.yml rather than assuming en.

There was also a false green in the anchor checker: pointed at a missing or empty site directory it reported "All anchors resolve" and exited 0 — the one case where CI should be loudest. Fixed in 5486c71, exits 2 now.

Deviation from the spec, flagged deliberately

#28 lists three buckets: missing, stale, current. I report five. unstamped distinguishes "no translation" from "a translation whose currency we cannot prove", which matters while stamps are being rolled out; orphaned is the hole above. Say the word if you want them collapsed.

Verified in CI, not just locally

Three green runs on this branch. The report and the anchor output now appear in the job logs as well as the job summary — the first run put everything in the summary only, which meant nothing was visible where you look when it misbehaves.

Still not verified

The PR comment path. It only fires on docs/en/** changes and this PR touches none, so the step has only ever taken its early exit — No English pages touched; nothing to report, which is itself correct. The comment body, the marker lookup and the update-instead-of-duplicate logic stay unproven until a PR edits an English page.

Fork PRs. github.token is read-only for forks, so the comment step would fail and take the run with it. Internal repo, so not worth guarding speculatively — noting it so it is a known limit rather than a surprise.

🤖 Generated with Claude Code

[mairas]

LGTM!