Skip to content

docs(i18n): add Finnish translation - #18

Merged
helmihyo merged 2 commits into
mainfrom
feat/i18n-finnish
Aug 5, 2026
Merged

docs(i18n): add Finnish translation#18
helmihyo merged 2 commits into
mainfrom
feat/i18n-finnish

Conversation

@helmihyo

@helmihyo helmihyo commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

Adds Finnish as a second language, and the machinery that keeps a translation honest once the English moves on.

Why

HALMET's readers are largely the same people as HALPI2's, and that documentation now ships in ten languages. Finnish first, on the same footing.

Structure

English moves under docs/en/ and Finnish lives at the mirrored path under docs/fi/, served by mkdocs-static-i18n in folder mode. That is the structure HALPI2 settled on after starting with suffix mode: suffix interleaves markdown with assets in shared directories, which stops scaling as soon as there is more than one translation. Only markdown lives under docs/fi/; images stay with the English source and are shared.

The glossary is HALPI2's, deliberately

solutions/translation/finnish-glossary.md began as a copy of HALPI2's. Keeping it means two Hat Labs products do not describe the same part with two different Finnish words — carrier boardemolevy is Matti's call there and stands here too. A HALMET section adds the ~70 terms this product needs and HALPI2 never did: digitaalitulo, vakiovirtalähde, juotossilta, ylös-/alasvetovastus, alipäästösuodin, galvaaninen erotus, porrasterä.

The file records that a shared row must change in both repositories or in neither.

One decision worth a second opinion: the shared glossary renders both connector and header as liitin. HALMET puts the two side by side more often than HALPI2 does — 1-Wire header connector, analog input connectors — and the glossary now says to let the qualifier carry the distinction rather than invent a second word. If that reads wrong to a Finnish reader, the glossary is where to change it.

Verification

Structure vs. the English source 0 deviations across 8 pages
Numeric values 0 differences, compared as multisets in both directions
mkdocs build --strict clean
check_anchors.py 244 anchors across 18 pages, all resolve
check_typography.py clean
check_glossary.py 45 prescribed terms, every one in use
translation_status.py fi: current=8

The numeric check matters most here: these pages carry input voltage limits, fuse ratings, threshold voltages and cutoff frequencies. A drifted digit is a hardware problem, not a typo.

Two things fixed along the way

edit_uri was broken before this branch. It pointed at edit/main/halmet-docs/docs/, a path this repository does not contain, so every "edit this page" pencil led nowhere. Verified against the GitHub API rather than assumed: halmet-docs/docs/index.md returns 404, docs/index.md returns 200. Now edit/main/docs/, which the i18n plugin completes with the language folder — English pencils point at docs/en/, Finnish ones at docs/fi/.

check_typography.py had a blind spot. It read a table's alignment row — | ---: | — as a space before a colon. HALPI2 has no right-aligned columns, so this never surfaced there. Fixed here; the same fix is owed to HALPI2, whose copy still has it.

print-site is removed

mkdocs-print-site-plugin has no i18n support: it builds one print page for the default language, so every Finnish page would have linked to an English PDF under an English tooltip. Removing it also removes the printer button from the English site — a visible change, tracked in the accompanying issue rather than left to be noticed.

What this needs from a reader

The Finnish is unreviewed by anyone other than its author. The mechanical checks above cover structure, anchors, numbers, typography and terminology; none of them can tell whether a sentence about pull-up resistors says the right thing about pull-up resistors.

Corrections belong in solutions/translation/finnish-glossary.md as well as in the pages, so the next translator inherits them.

🤖 Generated with Claude Code

helmihyo and others added 2 commits August 5, 2026 11:09
English moves under docs/en/ and mkdocs-static-i18n serves Finnish from
docs/fi/ in folder mode, the structure HALPI2 settled on: suffix mode
interleaves markdown with assets once there is more than one language.

print-site is removed. It has no i18n support, so it would either bundle
every language into one PDF or point Finnish pages at an English one. That
also removes the print button from the English site — a visible change.

edit_uri pointed at halmet-docs/docs/, a path this repository does not
have, so every 'edit this page' pencil led nowhere. Verified against the
GitHub API before changing it.

The glossary is HALPI2's, kept deliberately so the two products do not
describe the same part with two Finnish words, plus a HALMET section for
the input-circuit vocabulary HALPI2 never needed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
All eight pages, plus the anchor pass: the GPIO Reference heading becomes
GPIO-taulukko, so the one cross-page fragment pointing at it needed
mapping. Anchors break only once the target page is translated, which is
why it was invisible before this commit.

The typography checker read a table's alignment row — | ---: | — as a
space before a colon. HALPI2 has no right-aligned columns, so the blind
spot never showed there; the same fix is owed to that repository.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown

Translation status

fi — 8 current

Every translation of the pages in scope is current.

@helmihyo

helmihyo commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator Author

print-site removal is tracked in #19.

@helmihyo
helmihyo merged commit c2cead0 into main Aug 5, 2026
1 check passed
@helmihyo
helmihyo deleted the feat/i18n-finnish branch August 5, 2026 08:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant