Report stale translations and broken anchors

.claude/skills/translate-page/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: translate-page
+description: Translate a documentation page from docs/en/ into another language and stamp it. Use when asked to translate a page, add a language, or bring a stale translation up to date in this repo.
+---
+
+# Translate a documentation page
+
+Translation here is a repeatable operation, not an ad-hoc prompt. The rules below
+exist because each of them was broken once and cost real work.
+
+## Inputs
+
+- A page path under `docs/en/`, or a page reported by
+  `uv run python scripts/translation_status.py` as `missing` or `stale`.
+- A target language directory, e.g. `docs/fi/`.
+
+## Before translating
+
+1. **Read the glossary for the target language** —
+   `solutions/translation/finnish-glossary.md` for Finnish, and its equivalent
+   for other languages. It fixes terminology, unit formatting, address form and
+   what stays in English. Follow it exactly.
+2. If the page introduces a term the glossary does not cover, **add it to the
+   glossary** in the same change. Do not invent a one-off translation: the whole
+   point is that the same English term reads the same way on every page.
+3. If the page is `stale` rather than `missing`, read the English diff the
+   status report prints. Translate the change, not the whole page.
+
+## Translating
+
+The translation lives at the mirrored path — `docs/en/user-guide/hardware.md`
+becomes `docs/fi/user-guide/hardware.md`. Only markdown goes under the language
+directory; images stay with the English source and are shared.
+
+**Preserve structure exactly.** Same headings, list items, numbered steps,
+images, admonitions, table rows, footnotes and code fences, in the same order.
+
+**Never touch:**
+
+- Code fences and their contents, including comments inside them
+- Inline code: commands, file paths, hostnames, config keys
+- UI strings the reader will see on their own screen in English
+- Product, protocol and hardware names
+- Image filenames and paths
+
+**Always convert:** units to SI spacing and decimal comma (`0.9A` → `0,9 A`,
+`5.5 x 2.1 mm` → `5,5 × 2,1 mm`). This is not optional formatting; it is the
+correct way to write the value.
+
+**Two markdown traps** that neither `--strict` nor GitHub's preview catches —
+both are documented in `solutions/best-practices/`:
+
+- A blank line before the first item of a list
+- Four spaces, not three, for a sub-list under a numbered step
+
+**Never write an `en/` or `fi/` segment into a path inside a page.** The
+language comes from which directory the file lives in.
+
+## Anchors
+
+Anchors derive from heading text, so translating a heading changes its slug.
+Slugs strip diacritics and lowercase: `Mikä HALPI2 on?` → `mika-halpi2-on`.
+
+Two distinct jobs:
+
+1. **Inside the page you are translating** — rewrite every `](#…)` to the
+   translated heading's slug.
+2. **In pages you are not touching** — a link like
+   `](./operation.md#status-led-indicators)` in an already-translated page keeps
+   working until `operation.md` is translated, and breaks the moment it is. This
+   is a delayed fault. After translating, run the anchor check across the whole
+   built site, not just your page.
+
+Do not guess slugs. Build, then read the real ids out of the generated HTML.
+
+## Stamping
+
+The stamp records the git blob hash of the English source the translation was
+written against. Write it with the helper, never by hand:
+
+```bash
+uv run python scripts/stamp_translation.py docs/fi/user-guide/hardware.md
+```
+
+**Stamp only when you have actually translated.** A stamp updated without real
+translation work reports green and makes the staleness invisible — that is the
+one failure the status check cannot detect, and this skill is where the
+discipline lives. If you touched only the target language (fixing wording,
+fixing a typo), the English source did not change: leave the stamp alone.
+
+## Verifying
+
+All four, every time:
+
+```bash
+uv run mkdocs build --strict
+uv run python scripts/check_anchors.py site
+uv run python scripts/translation_status.py
+```
+
+and a structure comparison against the source:
+
+```bash
+python3 - <<'PY'
+import re
+en = 'docs/en/user-guide/hardware.md'; fi = 'docs/fi/user-guide/hardware.md'
+def stats(p):
+    t = re.sub(r'^---\n.*?\n---\n', '', open(p, encoding='utf-8').read(), flags=re.S)
+    return {k: len(re.findall(v, t, re.M)) for k, v in {
+        'headings': r'^#{1,6} ', 'bullets': r'^\s*[-*] ', 'numbered': r'^\s*\d+\. ',
+        'images': r'!\[', 'admonitions': r'^!!! ', 'table rows': r'^\|',
+        'fences': r'^```'}.items()}
+a, b = stats(en), stats(fi)
+print(a); print(b); print('match' if a == b else 'MISMATCH')
+PY
+```
+
+A mismatch means content was dropped or merged. Find it before committing.
+
+Finally, confirm no numeric value drifted: every number in the English text
+should appear in the translation, unless it was deliberately spelled out as a
+word. A wrong voltage or current in an installation guide is a safety problem,
+not a typo.
+
+## Committing
+
+One commit per logical group of pages. If pages cross-link each other, translate
+and commit them together — otherwise the intermediate commit has links pointing
+at headings that do not exist yet.

.github/workflows/translation-status.yml

@@ -0,0 +1,95 @@
+name: Translation Status
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'scripts/**'
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: translation-status-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  status:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history: the report resolves the stamped blob to show the
+          # English diff since a translation was written.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+
+      - name: Report translation status
+        run: |
+          # tee, not plain redirection: a report only in the job summary is
+          # invisible in the logs, which is where you look when it misbehaves.
+          uv run python scripts/translation_status.py --format markdown --diff \
+            | tee report.md
+          cat report.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Comment on the pull request
+        if: github.event_name == 'pull_request'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.number }}
+        run: |
+          # Only the English pages this PR actually touches. Which paths a PR
+          # touched is a fact, so a PR editing only translations says nothing.
+          pages=$(git diff --name-only \
+            "origin/${{ github.base_ref }}...HEAD" -- 'docs/en/**/*.md' \
+            | sed 's|^docs/en/||')
+          if [ -z "$pages" ]; then
+            echo "No English pages touched; nothing to report."
+            exit 0
+          fi
+
+          # shellcheck disable=SC2086
+          uv run python scripts/translation_status.py \
+            --format markdown --diff --only-pages $pages > comment.md
+          printf '\n<!-- translation-status -->\n' >> comment.md
+
+          existing=$(gh api "repos/${{ github.repository }}/issues/$PR/comments" \
+            --jq 'map(select(.body | contains("<!-- translation-status -->"))) | .[0].id // empty')
+          if [ -n "$existing" ]; then
+            gh api "repos/${{ github.repository }}/issues/comments/$existing" \
+              -X PATCH -F body=@comment.md --silent
+            echo "Updated comment $existing"
+          else
+            gh api "repos/${{ github.repository }}/issues/$PR/comments" \
+              -F body=@comment.md --silent
+            echo "Created comment"
+          fi
+
+      # Last, because unlike a stale translation a broken anchor is actual
+      # breakage and fails the run — and the report above must still be
+      # published when it does.
+      - name: Check anchors
+        run: |
+          uv run mkdocs build --strict
+          # PIPESTATUS, not $?: piping into tee would otherwise mask the
+          # checker's exit status behind tee's.
+          set +e
+          uv run python scripts/check_anchors.py site | tee anchors.txt
+          broken=${PIPESTATUS[0]}
+          set -e
+          {
+            echo ""
+            echo "## Anchor check"
+            echo ""
+            echo '```'
+            cat anchors.txt
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit "$broken"

.gitignore

@@ -1,2 +1,3 @@
 site/
 .venv/
+__pycache__/

docs/fi/appendices/compliance.md

@@ -1,3 +1,7 @@
+---
+translated_from: 75cd8c1d6a07b1e062e9cdb4a082d31038fc622c
+---
+
 # Vaatimustenmukaisuus ja sertifioinnit
 
 - CE-merkintä ja vaatimustenmukaisuusvakuutukset

docs/fi/appendices/design-files.md

@@ -1,3 +1,7 @@
+---
+translated_from: fc7ea79249b080c0f717303d066b9f6ea6d64795
+---
+
 # Suunnittelutiedostot ja kytkentäkaaviot
 
 Tällä sivulla ovat HALPI2:n kytkentäkaaviot ja mekaniikkasuunnittelun tiedostot.

docs/fi/appendices/errata.md

@@ -1,3 +1,7 @@
+---
+translated_from: 930b506809e4abe2b54e4fea058658a9d6d94461
+---
+
 # Tunnetut virheet
 
 Tällä sivulla on lueteltu eri HALPI2-versioiden tunnetut laitteisto-ongelmat.

docs/fi/appendices/resources.md

@@ -1,3 +1,7 @@
+---
+translated_from: 991d6882660454e7737c452f574d858ffdeb3b93
+---
+
 # Lisätietoja
 
 - Keskustelupalstat ja tuki

docs/fi/faq.md

@@ -1 +1,5 @@
+---
+translated_from: 4514b4c10652208edff9229b29c132b6f61399f0
+---
+
 # UKK

docs/fi/getting-started/getting-started.md

@@ -1,3 +1,7 @@
+---
+translated_from: a51e1cfe53d070c073a563641f9301fd3383a418
+---
+
 # Aloitusopas
 
 Tämä opas saa HALPI2:n toimintaan alle 30 minuutissa ja käsittelee myös kiinteän asennuksen. Seuraa vaiheita järjestyksessä: aloita pöytäkokoonpanolla ja varmista että kaikki toimii, ja siirry vasta sitten kiinteään asennukseen.

docs/fi/index.md

@@ -1,3 +1,7 @@
+---
+translated_from: e4d4a4c5108676be9c19bdd2a82a321b24b14191
+---
+
 # Johdanto
 
 HALPI2 on käyttövalmis venetietokone, joka perustuu Raspberry Pi Compute Module 5 -moduuliin (CM5). Siinä on kattava valikoima ominaisuuksia, jotka sopivat hyvin vene-, ajoneuvo- ja moniin teollisuussovelluksiin.

docs/fi/software-development/advanced-config.md

@@ -1,3 +1,7 @@
+---
+translated_from: 7cd96fcdbd05d13cf6d7a0aece5e788de8ca9c62
+---
+
 # Lisäasetukset
 
 - Suorituskyvyn viritys

docs/fi/software-development/daemon.md

@@ -1,3 +1,7 @@
+---
+translated_from: 4312a0e2c31bc8816de0a9735b84742671efda43
+---
+
 # HALPI2-daemon
 
 - Asennus ja asetukset

docs/fi/software-development/integration.md

@@ -1,3 +1,7 @@
+---
+translated_from: 0ef15a1b16d45ab5bbb343c19900513802350f96
+---
+
 # Järjestelmäintegraatio
 
 - Device tree -overlayt

docs/fi/software-development/ubuntu-installation.md

@@ -1,3 +1,7 @@
+---
+translated_from: 8c2d1560ad56e730c3fe6476cd5cf075b632b539
+---
+
 # Muiden Debian-pohjaisten jakeluiden käyttö
 
 !!! warning "Huomio"

docs/fi/technical-reference/controller.md

@@ -1,3 +1,7 @@
+---
+translated_from: c10fce7935a4a3da34e1ce003c5a924eed68b8be
+---
+
 # Emolevyn ohjain
 
 - RP2040-firmwaren toiminnot

docs/fi/technical-reference/hardware.md

@@ -1,3 +1,7 @@
+---
+translated_from: c237d8b6a74b99528445a8bb38aa5473b824b52e
+---
+
 # Laitteiston tekniset tiedot
 
 Tällä sivulla ovat HALPI2:n sähköiset, mekaaniset ja ympäristöä koskevat tekniset tiedot. Toimintaohjeet (asennus, huolto, osien vaihto) löytyvät [Laitteisto-oppaasta](../user-guide/hardware.md). Liitäntöjen protokollatiedot ovat sivulla [Liitännät ja tiedonsiirto](./interfaces.md).

docs/fi/technical-reference/interfaces.md

@@ -1,3 +1,7 @@
+---
+translated_from: 9497de10027831b20a1e2278a32df0c12d9a4a39
+---
+
 # Liitännät ja tiedonsiirto
 
 Tällä sivulla kuvataan, miten CM5:n liitännät on tuotu HALPI2:n emolevylle.

docs/fi/technical-reference/power-supply.md

@@ -1,3 +1,7 @@
+---
+translated_from: 5229ab5363e54a19e4330c30051e4787ece5806e
+---
+
 # Virransyöttö tarkemmin
 
 - Syöttöjännitealueet ja suojaus

docs/fi/user-guide/hardware.md

@@ -1,3 +1,7 @@
+---
+translated_from: 9741366021074655d667fcf3a93a634f86f3519a
+---
+
 # Laitteisto-opas
 
 ## Kotelon käsittely

docs/fi/user-guide/interfaces.md

@@ -1,3 +1,7 @@
+---
+translated_from: da8aa35c462e57bc7c0b00d50046a1df518e97dd
+---
+
 # Liitännät ja tiedonsiirto
 
 ## CAN FD / NMEA 2000

docs/fi/user-guide/operation.md

@@ -1,3 +1,7 @@
+---
+translated_from: 3ad6bd291105f72d9e440ca46e96fe9fa085e02c
+---
+
 # Järjestelmän käyttö
 
 ## Tila-LEDit

docs/fi/user-guide/software.md

@@ -1,3 +1,7 @@
+---
+translated_from: a428b6a7e1ca303e0571592a86d0cc6a3db97a83
+---
+
 # Ohjelmisto-opas
 
 ## Käyttöjärjestelmän levykuvat

docs/fi/user-guide/troubleshooting.md

@@ -1,3 +1,7 @@
+---
+translated_from: 35a84e7f96c0891201c8a8248bf146139684b772
+---
+
 # Vianetsintä
 
 Tällä sivulla käydään läpi tavallisia HALPI2:n käytössä vastaan tulevia ongelmia ja niiden ratkaisut.

docs/fi/user-guide/use-cases.md

@@ -1,3 +1,7 @@
+---
+translated_from: 347076aa60c0c593af503f8af30bc480108964b8
+---
+
 # Yleiset käyttötapaukset
 
 - Navigointijärjestelmän pystytys veneeseen