[Feature] Every bundled document is English while its reader tile is translated 32 ways #626

New issue

Closed

opened 2026-07-22 16:21:54 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:21:54 +00:00

Owner

Found in the pre-publication localisation review.

Evidence: lib/services/documentation_service.dart:29-41 looks for a .<languageCode>.md sibling beside each document; pubspec.yaml:129-157 bundles 24 documents and zero language variants. The document titles are registered in 30 languages (settings_dialog_docs.dart, enforced by the docs-registration gate). Size: wc -l docs/*.md docs/design/*.md → 19,382 lines, all English.

Why this matters now: a user who sets the app to Polish gets a fully Polish interface, clicks Help → User Guide, and receives 2,992 lines of English. The 32-to-0 asymmetry is sharper than plain "no documentation in your language", because the app raises the expectation itself: a translated title on an untranslated document. The machinery is already there, which makes the gap odder still.

Proposal: the smallest good fix is not translation but disclosure. Have the document reader show one line above any document that exists only in the base version — "This document is available in English only" — which is a single d() string plus 31 translations via make add-l10n. And in README.md:42, say that the interface is in 32 languages and the documentation is in English. Anyone who later wants one language drops docs/USER_GUIDE.de.md beside it and the rest already works.

Found in the pre-publication localisation review. **Evidence:** `lib/services/documentation_service.dart:29-41` looks for a `.<languageCode>.md` sibling beside each document; `pubspec.yaml:129-157` bundles 24 documents and **zero** language variants. The document titles *are* registered in 30 languages (`settings_dialog_docs.dart`, enforced by the docs-registration gate). Size: `wc -l docs/*.md docs/design/*.md` → 19,382 lines, all English. **Why this matters now:** a user who sets the app to Polish gets a fully Polish interface, clicks Help → User Guide, and receives 2,992 lines of English. The 32-to-0 asymmetry is sharper than plain "no documentation in your language", because the app raises the expectation itself: a translated title on an untranslated document. The machinery is already there, which makes the gap odder still. **Proposal:** the smallest good fix is not translation but disclosure. Have the document reader show one line above any document that exists only in the base version — "This document is available in English only" — which is a single `d()` string plus 31 translations via `make add-l10n`. And in `README.md:42`, say that the *interface* is in 32 languages and the *documentation* is in English. Anyone who later wants one language drops `docs/USER_GUIDE.de.md` beside it and the rest already works.

brenno added the

enhancement

label

2026-07-22 16:21:54 +00:00

brenno referenced this issue

2026-07-22 17:13:34 +00:00

docs: haal negen achterhaalde beweringen uit de publieke teksten #655

brenno added the

in-progress

label

2026-07-22 21:21:22 +00:00

brenno referenced this issue

2026-07-22 21:26:51 +00:00

feat(docs): zeg het wanneer een document alleen in het Engels bestaat (#626) #692

brenno referenced this issue from a commit

2026-07-22 21:26:51 +00:00

feat(docs): zeg het wanneer een document alleen in het Engels bestaat (#626)

brenno referenced this issue from a commit

2026-07-22 21:27:10 +00:00

Merge pull request 'feat(docs): zeg het wanneer een document alleen in het Engels bestaat (#626)' (#692) from feat/docs-taalmelding-626 into main

brenno removed the

in-progress

label

2026-07-22 21:27:11 +00:00

brenno commented

2026-07-22 21:27:11 +00:00

Author

Owner

Opgelost in PR #692, op main — langs jouw eigen voorstel: de kleinste goede oplossing is niet vertalen maar het zeggen.

De melding staat boven elk document dat alleen in de basisversie bestaat, in de taal van de gebruiker. Een mededeling en geen waarschuwing: er is niets misgegaan, er is alleen iets er nog niet. DocumentationService.loadDetailed geeft terug óf de basisversie geserveerd is; load blijft voor het zoekpad, dat dit onderscheid niet nodig heeft.

De README zegt het nu ook: de 32 talen zijn de interface, de documentatie is Engels, en docs/USER_GUIDE.de.md ernaast zetten volstaat. Meteen ook de zin over de taaltests bijgewerkt — er zijn er sinds #677 twee.

De test dekt drie gevallen, en de middelste is de belangrijkste: zodra er een vertaling naast ligt moet de melding vanzelf verdwijnen. Blijft hij staan, dan vertelt hij een onwaarheid en is hij erger dan geen melding.

Wat dit niet is: de 19.382 regels vertalen. Dat is een project op zichzelf. Maar zwijgen was het ook niet — de app wekt de verwachting zélf met een vertaalde titel, en die asymmetrie is scherper dan plat "geen documentatie in jouw taal".

Opgelost in PR #692, op main — langs jouw eigen voorstel: de kleinste goede oplossing is niet vertalen maar het zeggen. **De melding** staat boven elk document dat alleen in de basisversie bestaat, in de taal van de gebruiker. Een mededeling en geen waarschuwing: er is niets misgegaan, er is alleen iets er nog niet. `DocumentationService.loadDetailed` geeft terug óf de basisversie geserveerd is; `load` blijft voor het zoekpad, dat dit onderscheid niet nodig heeft. **De README zegt het nu ook**: de 32 talen zijn de interface, de documentatie is Engels, en `docs/USER_GUIDE.de.md` ernaast zetten volstaat. Meteen ook de zin over de taaltests bijgewerkt — er zijn er sinds #677 twee. **De test dekt drie gevallen**, en de middelste is de belangrijkste: zodra er een vertaling naast ligt moet de melding vanzelf verdwijnen. Blijft hij staan, dan vertelt hij een onwaarheid en is hij erger dan geen melding. **Wat dit niet is:** de 19.382 regels vertalen. Dat is een project op zichzelf. Maar zwijgen was het ook niet — de app wekt de verwachting zélf met een vertaalde titel, en die asymmetrie is scherper dan plat "geen documentatie in jouw taal".

brenno closed this issue

2026-07-22 21:27:11 +00:00