[Docs] 31% of the public documentation is Dutch, and the reader is not told which parts #587

New issue

Closed

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

brenno commented

2026-07-22 16:16:36 +00:00

Owner

Found in the pre-publication documentation review; measured across all 45 public .md files (26,870 lines).

Measurement: 8,449 of 26,870 lines (31.4%) are Dutch.

File	Lines	Language	Reached via
`CHANGELOG.md`	4,903	Dutch	README table, repo root
`docs/design/OCIWACHT.md`	2,668	Dutch	README table as "Implemented", and bundled in the app
`docs/design/VERIFICATION.md`	279	Dutch	app asset
`docs/design/LEXICON_LICENTIENAVRAAG.md`	167	Dutch	app asset
`assurance/*.md`	432	Dutch	git-tracked
`docs/BUILD.md:116-135`	~20	Dutch inside English	app asset

Two sharp points:

docs/BUILD.md has two Dutch H3 headings in the middle of an English document.
The three Dutch design documents have a reader tile whose title is translated into 32 languages via l10n.d(), while the content is Dutch only. docs/README.md does warn "(in Dutch)" for VERIFICATION.md and LEXICON_LICENTIENAVRAAG.md — but not for OCIWACHT.md, the largest of the three at 2,668 lines and the flagship document of the privacy feature.

Why this must be fixed before publication: a Turkish or Irish user gets a neatly translated tile reading Privacy check (design) and opens 2,668 lines of Dutch. That reads as a broken translation, not as a deliberate choice. An English README that promises 32 languages hands the reader two clicks that land in Dutch, one of them the privacy design — the thing this project most wants scrutinised.

Proposal: do not translate everything. Make English the norm and mark Dutch explicitly. (1) Add · **Language:** Nederlands to the masthead of the four Dutch documents and (in Dutch) beside all three in the docs/README.md table. (2) Translate the ~20 Dutch lines in docs/BUILD.md — one paragraph, and it removes the only genuine mixture. (3) For the changelog, see the separate issue on cutting a 0.1.0 section.

Found in the pre-publication documentation review; measured across all 45 public `.md` files (26,870 lines). **Measurement:** 8,449 of 26,870 lines (31.4%) are Dutch. | File | Lines | Language | Reached via | |---|---|---|---| | `CHANGELOG.md` | 4,903 | Dutch | README table, repo root | | `docs/design/OCIWACHT.md` | 2,668 | Dutch | README table as "Implemented", and bundled in the app | | `docs/design/VERIFICATION.md` | 279 | Dutch | app asset | | `docs/design/LEXICON_LICENTIENAVRAAG.md` | 167 | Dutch | app asset | | `assurance/*.md` | 432 | Dutch | git-tracked | | `docs/BUILD.md:116-135` | ~20 | **Dutch inside English** | app asset | **Two sharp points:** 1. `docs/BUILD.md` has two Dutch H3 headings in the middle of an English document. 2. The three Dutch design documents have a reader tile whose *title* is translated into 32 languages via `l10n.d()`, while the content is Dutch only. `docs/README.md` does warn "(in Dutch)" for `VERIFICATION.md` and `LEXICON_LICENTIENAVRAAG.md` — but **not** for `OCIWACHT.md`, the largest of the three at 2,668 lines and the flagship document of the privacy feature. **Why this must be fixed before publication:** a Turkish or Irish user gets a neatly translated tile reading *Privacy check (design)* and opens 2,668 lines of Dutch. That reads as a broken translation, not as a deliberate choice. An English README that promises 32 languages hands the reader two clicks that land in Dutch, one of them the privacy design — the thing this project most wants scrutinised. **Proposal:** do not translate everything. Make English the norm and mark Dutch explicitly. (1) Add `· **Language:** Nederlands` to the masthead of the four Dutch documents and `(in Dutch)` beside all three in the `docs/README.md` table. (2) Translate the ~20 Dutch lines in `docs/BUILD.md` — one paragraph, and it removes the only genuine mixture. (3) For the changelog, see the separate issue on cutting a 0.1.0 section.

brenno added the

docs

label

2026-07-22 16:16:36 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:10 +00:00

docs: claims en cijfers die niet meer klopten (#602 #599 #614 #640 #634 #587 #623)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00

docs: claims en cijfers die niet meer klopten (#602 #599 #614 #640 #634 #587 #623)

brenno referenced this issue

2026-07-22 17:14:10 +00:00