feat(poort): een vertaalde gids moet bíj zijn, niet alleen bestaan #1576

Merged

brenno merged 2 commits from feat/poort-vertaalstructuur into main

2026-08-19 10:58:54 +00:00

brenno commented

2026-08-19 10:53:31 +00:00

Owner

Twee commits: de poort, en het wegwerken van wat hij zou hebben vastgelegd.

Waarom

Twee keer in twee dagen kwam er een sectie bij in een Engelse gids zonder Nederlandse tegenhanger — §14.9 van FILE_FORMAT (#1568) en §14.11 die met de tijdlijnfunctie meekwam (#1571, hersteld in #1573). Beide keren stond alles groen. translate-docs-check vroeg namelijk alleen of een variant bestond en geregistreerd was, niet of hij nog klopte. Nederlands is wat de in-app-lezer toont, dus een variant die een sectie achterloopt is een lezer die minder te horen krijgt dan de Engelse.

De poort

Een vijfde regel in docVariantProblems: een verscheepte variant draagt dezelfde structuur als zijn bron. Evenveel koppen per niveau, en elke genummerde sectie onder hetzelfde nummer. Nummers overleven een vertaling waar woorden dat niet doen — dat maakt ze bruikbaar als identiteit van een sectie over talen heen. Een hernoemde kop is dus geen drift, een ontbrekende wel.

Koppen binnen codeblokken tellen niet mee, en dat is geen detail: in FILE_FORMAT is # Rapport meestal de inhoud van een voorbeeld. Mijn eerste twee metingen telden ze wél mee en logen in beide richtingen — eerst zag ik drift die er niet was, daarna geen drift die er wel was. De fence-afhandeling is daarom exact: een langere fence wordt niet gesloten door een kortere erbinnen, en daar staat een test op.

Rood geproefd op de echte repo, niet alleen op synthetische invoer:

sabotage	melding
nummer uit `### 14.11` in `FILE_FORMAT.nl.md` gehaald (koppental gelijk)	`does not carry section number(s) 14.11`
één `##`-sectie uit `KNOWN_LIMITATIONS.nl.md` geknipt	`is missing N heading(s) that … has`

En de tool geeft exitcode 1, niet alleen een boodschap op het scherm — precies waar deze poort in #1341 op viel. Daarna teruggezet uit een kopie, niet met git: er stond ongecommit werk in dezelfde boom.

Geen basislijn

De eerste opzet droeg de bestaande achterstand in een headingDriftBaseline. Toen viel ratchet_trend_tool_test: deze repo eist dat élke basislijn in tool/ geregistreerd staat in check_ratchet_trend.dart, "zodat ze niet onzichtbaar bewegen". Dat maakte de keuze scherp — niet registreren, maar wegwerken. Een lege basislijnmap is het ritueel dat altijd afgaat en niets bewaakt.

Dus zijn de vijf secties vertaald:

USER_GUIDE.nl — Tabellen, sorteren en tijdlijnen, Voetnoten (inclusief de tabel met wat elk oppervlak met een noot kan) en Breedte en zoom tijdens het schrijven.
KNOWN_LIMITATIONS.nl — dat voetnoten in de HTML-export achteraan belanden in plaats van onderaan het vel, en dat de web-export de voettekst, het paginanummer, het watermerk en de TLP-/PrivacyKat-badges weglaat. Die tweede is er een om niet alleen in het Engels te hebben: wie een .html naar een klant stuurt, hoort te weten dat zijn voettekst er niet in zit.
Onderweg kreeg #### 6.3.1 in FILE_FORMAT.nl.md zijn sectienummer terug, dat bij het vertalen was weggevallen.

Structuur nu exact gelijk in alle drie de documenten die achterliepen.

Getoetst

make check volledig groen (inclusief de poort zelf en de 15 nieuwe/aangepaste toetsen in doc_translation_test.dart).
make check-registrations groen.
make check-secrets en make sast gedraaid.
De sabotageproef hierboven, met exitcode.

Wat dit niet is

Geen machinevertaling. De vijf secties zijn met de hand geschreven in het register van de omringende tekst, omdat make translate-docs het hele bestand herschrijft en een externe vertaalmachine vergt die hier niet staat. Dat is dezelfde route als #1543.

Twee commits: de poort, en het wegwerken van wat hij zou hebben vastgelegd. ## Waarom Twee keer in twee dagen kwam er een sectie bij in een Engelse gids zonder Nederlandse tegenhanger — §14.9 van FILE_FORMAT (#1568) en §14.11 die met de tijdlijnfunctie meekwam (#1571, hersteld in #1573). Beide keren stond alles groen. `translate-docs-check` vroeg namelijk alleen *of* een variant bestond en geregistreerd was, niet of hij nog klopte. Nederlands is wat de in-app-lezer toont, dus een variant die een sectie achterloopt is een lezer die minder te horen krijgt dan de Engelse. ## De poort Een vijfde regel in `docVariantProblems`: een verscheepte variant draagt dezelfde structuur als zijn bron. Evenveel koppen per niveau, en elke genummerde sectie onder hetzelfde nummer. Nummers overleven een vertaling waar woorden dat niet doen — dat maakt ze bruikbaar als identiteit van een sectie over talen heen. Een hernoemde kop is dus geen drift, een ontbrekende wel. **Koppen binnen codeblokken tellen niet mee**, en dat is geen detail: in FILE_FORMAT is `# Rapport` meestal de inhoud van een voorbeeld. Mijn eerste twee metingen telden ze wél mee en logen in beide richtingen — eerst zag ik drift die er niet was, daarna geen drift die er wel was. De fence-afhandeling is daarom exact: een langere fence wordt niet gesloten door een kortere erbinnen, en daar staat een test op. **Rood geproefd op de echte repo**, niet alleen op synthetische invoer: | sabotage | melding | |---|---| | nummer uit `### 14.11` in `FILE_FORMAT.nl.md` gehaald (koppental gelijk) | `does not carry section number(s) 14.11` | | één `##`-sectie uit `KNOWN_LIMITATIONS.nl.md` geknipt | `is missing N heading(s) that … has` | En de tool geeft **exitcode 1**, niet alleen een boodschap op het scherm — precies waar deze poort in #1341 op viel. Daarna teruggezet uit een kopie, niet met git: er stond ongecommit werk in dezelfde boom. ## Geen basislijn De eerste opzet droeg de bestaande achterstand in een `headingDriftBaseline`. Toen viel `ratchet_trend_tool_test`: deze repo eist dat élke basislijn in `tool/` geregistreerd staat in `check_ratchet_trend.dart`, "zodat ze niet onzichtbaar bewegen". Dat maakte de keuze scherp — niet registreren, maar wegwerken. Een lege basislijnmap is het ritueel dat altijd afgaat en niets bewaakt. Dus zijn de vijf secties vertaald: - **`USER_GUIDE.nl`** — *Tabellen, sorteren en tijdlijnen*, *Voetnoten* (inclusief de tabel met wat elk oppervlak met een noot kan) en *Breedte en zoom tijdens het schrijven*. - **`KNOWN_LIMITATIONS.nl`** — dat voetnoten in de HTML-export achteraan belanden in plaats van onderaan het vel, en dat de web-export de voettekst, het paginanummer, het watermerk en de TLP-/PrivacyKat-badges weglaat. Die tweede is er een om niet alleen in het Engels te hebben: wie een `.html` naar een klant stuurt, hoort te weten dat zijn voettekst er niet in zit. - Onderweg kreeg `#### 6.3.1` in `FILE_FORMAT.nl.md` zijn sectienummer terug, dat bij het vertalen was weggevallen. Structuur nu exact gelijk in alle drie de documenten die achterliepen. ## Getoetst - `make check` volledig groen (inclusief de poort zelf en de 15 nieuwe/aangepaste toetsen in `doc_translation_test.dart`). - `make check-registrations` groen. - `make check-secrets` en `make sast` gedraaid. - De sabotageproef hierboven, met exitcode. ## Wat dit niet is Geen machinevertaling. De vijf secties zijn met de hand geschreven in het register van de omringende tekst, omdat `make translate-docs` het hele bestand herschrijft en een externe vertaalmachine vergt die hier niet staat. Dat is dezelfde route als #1543.

brenno added 2 commits

2026-08-19 10:53:31 +00:00

feat(poort): translate-docs-check toetst of een vertaling bíj is, niet alleen dat hij bestaat bd9627812c

Twee keer in twee dagen kwam er een sectie bij in de Engelse bron zonder
Nederlandse tegenhanger — §14.9 van FILE_FORMAT (#1568) en §14.11 die met de
tijdlijnfunctie meekwam (#1571, hersteld in #1573). Beide keren stond alles
groen, want de poort vroeg alleen óf de variant bestond. Nederlands is wat de
lezer in de app krijgt, dus een variant die een sectie achterloopt is een lezer
die minder te horen krijgt dan de Engelse.

De vijfde regel in `docVariantProblems` vergelijkt daarom de structuur: evenveel
koppen per niveau als de bron, en elke genummerde sectie onder hetzelfde nummer.
Nummers overleven een vertaling waar woorden dat niet doen, en dat maakt ze
bruikbaar als identiteit van een sectie over talen heen. Een hernoemde kop is
dus geen drift; een ontbrekende wel.

Koppen binnen codeblokken tellen niet mee, en dat is geen detail: in FILE_FORMAT
is `# Rapport` meestal de inhoud van een voorbeeld. Mijn eerste twee metingen
telden ze mee en logen in beide richtingen — eerst drift die er niet was, daarna
geen drift die er wel was. De fence-afhandeling is daarom exact: een langere
fence wordt niet gesloten door een kortere erbinnen, en dat staat in een test.

`headingDriftBaseline` draagt wat vandaag al achterloopt, met naam en aantal:
KNOWN_LIMITATIONS mist twee eerlijkheden (voetnoten in de HTML-export, de
overlays die de web-export weglaat) en USER_GUIDE drie secties over de
documentmodus. Mag krimpen, niet groeien; CHECKS.md zegt erbij dat een getal
ophogen om erlangs te komen geen reparatie is.

Rood geproefd op de echte repo: het nummer uit `### 14.11` in de Nederlandse
FILE_FORMAT halen geeft de nummerklacht, een sectie uit KNOWN_LIMITATIONS.nl
knippen de koppenklacht — en de tool geeft exitcode 1, niet alleen een boodschap
op het scherm. Dat laatste is precies waar deze poort in #1341 op viel.

Onderweg: `#### 6.3.1` in de Nederlandse FILE_FORMAT heeft zijn sectienummer
terug, dat bij het vertalen was weggevallen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs(nl): de vijf achtergebleven secties vertaald, en de basislijn weg

scans / scans (pull_request) Successful in 2m18s

Details

static-gate / static-gate (pull_request) Successful in 4m43s

Details

9c8bb5e870

De poort uit de vorige commit droeg de bestaande achterstand in
`headingDriftBaseline`. Die is nu weggewerkt in plaats van vastgelegd, dus de
basislijn kan verdwijnen — en dat moet ook: `ratchet_trend_tool_test` eist dat
elke basislijn in `tool/` geregistreerd staat zodat ze niet onzichtbaar beweegt,
en een lege basislijnmap is precies het ritueel dat altijd afgaat en niets
bewaakt. Geen basislijn, geen uitzondering: drift die de poort meldt is vanaf nu
drift van vandaag.

`USER_GUIDE.nl` kreeg drie secties uit het hoofdstuk Documenten: *Tabellen,
sorteren en tijdlijnen* (van gisteren, #1571), *Voetnoten* met de tabel van wat
elk oppervlak met een noot kan, en *Breedte en zoom tijdens het schrijven*.

`KNOWN_LIMITATIONS.nl` kreeg de twee beperkingen die alleen de Engelse lezer las:
voetnoten die in de HTML-export achteraan belanden in plaats van onderaan het
vel, en de overlays die de web-export weglaat. Die tweede is er een om niet
alleen in het Engels te hebben — wie een `.html` naar een klant stuurt, hoort te
weten dat zijn voettekst, paginanummer, watermerk en TLP-badges er niet in
zitten.

Structuur nu exact gelijk in alle drie de documenten die achterliepen; `make
check` groen, inclusief de poort zelf.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

brenno merged commit 27efe3832a into main

2026-08-19 10:58:54 +00:00

brenno referenced this pull request from a commit

2026-08-19 10:58:54 +00:00

feat(poort): een vertaalde gids moet bij zijn, niet alleen bestaan (#1576)

brenno referenced this pull request from a commit

2026-08-19 12:59:39 +00:00

docs(bestandsformaat): §8 is eindelijk het overzicht dat het beloofde te zijn

brenno referenced this pull request

2026-08-19 13:00:06 +00:00

docs(bestandsformaat): §8 is eindelijk het overzicht dat het beloofde te zijn #1580

brenno referenced this pull request