Skip to content

docs(i18n): add eight more languages to the HALMET documentation - #21

Merged
helmihyo merged 6 commits into
mainfrom
feat/i18n-eight-languages
Aug 5, 2026
Merged

docs(i18n): add eight more languages to the HALMET documentation#21
helmihyo merged 6 commits into
mainfrom
feat/i18n-eight-languages

Conversation

@helmihyo

@helmihyo helmihyo commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

Adds French, German, Swedish, Spanish, Italian, Dutch, Norwegian Bokmål and Danish, bringing HALMET level with HALPI2. Nine languages, 72 pages.

The glossaries are HALPI2's

Each was copied from the HALPI2 repository and extended, not written fresh, so the two products do not describe the same part with two different words in the same language. Each adds 67–81 rows of the input-circuit vocabulary HALPI2 never needed — digital and analog inputs, galvanic isolation, constant current source, pull-up and pull-down resistors, solder jumpers — and keeps every inherited typography rule.

Where a HALPI2 decision is deliberately not carried over, the row says so and says why. Finnish power supplyteholähde rather than HALPI2's virtalähde is the one case: on this board virtalähde is a substring of vakiovirtalähde, the constant current source described in the same list, so the reader would meet what looks like one component with a modifier.

Verification

Structure vs. the English source 0 deviations across 72 pages
mkdocs build --strict clean
check_anchors.py 1220 anchors across 82 pages, all resolve
check_typography.py clean in all nine
check_glossary.py clean in all nine
translation_status.py current=8 in all nine
Safety figures cross-checked 12 values × 10 languages, all agree
Passages read against English 1654, across all nine languages

The English source was wrong in five places

Translating means reading every sentence, which surfaced defects that predate this branch. Three hardware figures each appeared as two different numbers on two different pages; Matti settled all three in #20 and they are corrected here in English and in every translation:

  • digital input tolerance is ±32 V, not ±30 V
  • the analog measurement range tops out at 33 V, not 32 V
  • the maximum measurable resistance is 300 Ω, not 320 Ω

Also fixed: a merged sentence in usage/index.md ("Engine panel gauges are often constructed are usually either…"), which all nine translators independently resolved to the same evident meaning, and two typos in hardware/index.md. The two TODO notes stay, on Matti's instruction — they mark missing content and are to be written separately.

What the review found

Nine languages were reviewed in three phases: each glossary's own rules measured against its pages, a hunt for terms that gained a rival, and a sentence-by-sentence read of the two instruction-dense pages, with every finding then given to a skeptic instructed to refute it.

One defect could have misconfigured a board, and it was in Finnish — the translation I wrote myself and nobody else had read. normally open and normally closed were prescribed the wrong way round in a glossary row of mine, so the pull-down and pull-up descriptions each named the opposite kind of switch. The Finnish contradicted itself inside one sentence — an avautuva switch that pulls the input high sulkeutuessaan — and eight sibling languages had it right, Swedish slutande/brytande and German Schließer/Öffner lining up the same way.

Five page titles disagreed with their sidebar label. All five were introduced by aligning the navigation to HALPI2 after the glossaries were written but before the pages were translated. The pages now follow the navigation and the glossaries record the reasoning, so it is not re-litigated.

Six languages left (constant current source) in English inside their own prose; each glossary already prescribed a term.

Nine further reports were checked and refuted, most because they compared against the wrong English phrase: CCS jumper headers and shorting the jumper contacts are different phrases, so Danish using two words is right; ESP32 Introduction is not the ## Introduction heading found elsewhere.

A checker fix that matters beyond this branch

check_glossary.py was reporting a false green. It matched a prescribed term inside any longer word containing it, so Finnish virtalähde counted as used because vakiovirtalähde appears — two unrelated components. It reported every prescribed term in use while one was never used at all.

A false alarm wastes a reviewer's time; a false green means the check was never doing its job. Both repositories have leaned on this script. The fix is verified against all nine HALMET languages and all nine HALPI2 languages, whose verdicts are unchanged. The same fix is owed to hatlabs/halpi2, whose copy still has it.

What this needs from a reader

Nobody who reads these eight languages has read them. The Finnish was read by its author only, which is how its reversed switch terms survived until an independent review looked. Every mechanical check above passes, and 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/<language>-glossary.md as well as in the pages, so the next translator inherits them.

🤖 Generated with Claude Code

helmihyo and others added 6 commits August 5, 2026 13:49
The glossaries are HALPI2's, copied and extended rather than written
fresh, so the two products do not describe the same part with two words
in the same language. Each adds 67-81 rows of input-circuit vocabulary
HALPI2 never needed, and keeps every inherited typography rule.

Five navigation labels came back diverging from HALPI2 for no reason and
were aligned to it. One was also wrong: Italian rendered Errata as
'Errata corrige', which in publishing means a list of corrections to
make, not the known hardware defects the page actually lists.

The per-language tables in check_glossary.py and check_typography.py are
restored — they had been trimmed to Finnish while Finnish was the only
translation, and that is no longer true.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
64 pages across French, German, Swedish, Spanish, Italian, Dutch,
Norwegian and Danish, each matching its English source exactly on
headings, lists, tables, figures and code fences.

Four glossary rows were removed rather than translated: they described
HALPI2 pages that have no HALMET counterpart — casting flash on an
enclosure, a Label column that no HALMET table has. Carrying them over
made the glossary checker report a defect on every run, and a checker
that cries wolf stops being read.

The translations copy the English source faithfully, including the places
where it contradicts itself. A translator quietly correcting a hardware
figure is worse than a wrong figure in nine languages.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
usage/index.md merged two phrasings into 'Engine panel gauges are often
constructed are usually either thermostatic or magnetic'. Every one of the
nine translators resolved it to the evident meaning, so the nine
translations already said what the English now says; they are re-stamped
rather than re-translated, and the diff shows why that is honest here.

hardware/index.md had 'measurement.The' and 'noise ina tachometer'.

The contradictory hardware figures and the two TODO notes are left alone
and tracked in #20 — the voltage tolerance and the maximum measurable
resistance each appear as two different numbers on two different pages,
and choosing between them needs someone who knows the board.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The checker matched a prescribed term inside any longer word containing
it, so Finnish 'virtalähde' (power supply) counted as used because
'vakiovirtalähde' (constant current source) appears — two unrelated
components. It reported every prescribed term in use while one was never
used at all. A false green is worse than a false alarm: a checker that
passes when it should not is no checker.

The word boundary is only applied when the term starts with a word
character. A row like '−32 V and +32 V' opens with a minus sign, where \b
asserts the opposite of what is meant and matches nothing — caught by the
fix's own first run.

Two glossary rows follow from what the fix surfaced. Italian keeps a
HALPI2 row about flashing an OS image to an SSD; HALMET has neither, and
its every use of 'flash' is flash memory. Finnish now diverges
deliberately on power supply, with the reason recorded next to it: on this
board 'virtalähde' is a substring of the constant current source described
in the same list.

Verified against all nine HALMET languages and all nine HALPI2 languages,
whose verdicts are unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Matti settled the three contradictions in #20:

- digital inputs tolerate ±32 V, not ±30 V — 'safe and still
  conservative', and the figure hardware/index.md carried was the low one
- the analog measurement range tops out at 33 V, not 32 V
- the maximum measurable resistance is 300 ohms, not 320

Each was stated as two different numbers on two different pages, so one
page was wrong in every case. English is corrected and all nine
translations follow; the pages are re-stamped because they now say what
the corrected source says.

The two TODO notes stay, on Matti's instruction — they mark missing
content and are to be written separately, not deleted.

Also fixes nine findings the Finnish review raised, in the translation I
wrote myself and nobody else had read: ASCII hyphen where the other eight
languages use a minus sign, '+/- 30 V' copied verbatim from English
instead of converted, a compounding hyphen glued to a digit, and a
glossary row of my own that read 'latauslataustila' — download twice.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The one defect that could misconfigure a board was in Finnish, and its
root cause was a glossary row I wrote: normally open and normally closed
were prescribed the wrong way round. A *sulkeutuva* contact is open at
rest and closes when actuated, which is what normally open means, so the
pull-down and pull-up descriptions each named the opposite kind of switch.
The Finnish text contradicted itself in the same sentence — an 'avautuva'
switch that pulls the input high 'sulkeutuessaan' — and eight sibling
languages had it right, Swedish slutande/brytande and German
Schließer/Öffner lining up the same way.

Five page titles disagreed with their sidebar label, all five introduced
when the navigation was aligned to HALPI2 after the glossaries were
written but before the pages were. The pages now follow the navigation and
the glossaries record why, so the choice is not re-litigated: two Hat Labs
products cannot give one page two names.

Six languages left '(constant current source)' in English inside their own
prose. Each glossary already prescribes a term; the acronym CCS stays as
printed on the board, but the expansion is now in the reader's language.

Nine further rival-term reports were checked and refuted. Most compared
against the wrong English: 'CCS jumper headers' and 'shorting the jumper
contacts' are different phrases, so Danish using two words is correct, and
'ESP32 Introduction' is not the '## Introduction' heading elsewhere.

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

da — 8 current
de — 8 current
es — 8 current
fi — 8 current
fr — 8 current
it — 8 current
nb — 8 current
nl — 8 current
sv — 8 current

Every translation of the pages in scope is current.

@helmihyo
helmihyo merged commit 54611c5 into main Aug 5, 2026
1 check passed
@helmihyo
helmihyo deleted the feat/i18n-eight-languages branch August 5, 2026 12:35
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