Deze documentatie wordt actief uitgebreid — kom regelmatig terug.

ADR-00016: Language Support and Documentation Policy

Approval Status

Status flow: Proposed → Accepted → Reviewed → Approved (or Rejected), or Not Required. A superseded ADR keeps its file; only its status changes to Superseded by NNNNN.

Governance body	Status	Last update
CTN Project Team	Proposed	2026-06-18
CTN Technical Advisory Board	Pending	—
CTN Steering Committee	Pending	—
BDI Conformance Team	Pending	—
BDI Framework Team	Pending	—

RdN Question : I would like to understand which tool will be used. I am familiar with POT-files and PO-editors, in which you can have you labels in your UI easily translated by (native) speakers. Nowadays it is often AI powered. E.g. https://poeditor.com/ integrates quite well with Claude.ai. I would prefer an external tool, so that the ASR Admin in future can have a look at the translations and override when needed. For now it will be the Product Owner together with his AI buddy who will be looking into the translations.

We should also consider to add this to the Definition of Done. Changes of UI labels available in all supported languages. And translations approved by Product Owner.

Context and Problem Statement

We need a clear, consistent policy for language usage across documentation, stakeholder communication, user interfaces, and source code. Ambiguity leads to friction in collaboration, inconsistent terminology, and additional rework during reviews and translations. The policy must:

Define the canonical language for permanent technical design documentation.
Define the language for stakeholder-facing artefacts (e.g., product vision, epics, user stories, acceptance criteria).
Ensure all user interfaces are internationalizable with a sensible default locale.
Define language conventions for technical source code to ensure consistency with common tooling and libraries.

Considered Options

Option 1: Single-language Dutch everywhere

Description: All artefacts (docs, stories, UI, code) in Dutch.
Pros: One language for all stakeholders; easier stakeholder reviews.
Cons: Excludes/limits international contributors; conflicts with common programming/library conventions; harder to reuse OSS/i18n resources; increases friction in vendor collaboration.

Option 2: Single-language English everywhere (one locale)

Description: All artefacts (docs, stories, UI, code) in one variant of English.
Pros: Aligns with tooling/OSS; simplifies collaboration across borders; reduces translation overhead.
Cons: Less accessible for Dutch-speaking business stakeholders; risks loss of nuance in policy/legal contexts; may reduce adoption/engagement of non-technical stakeholders.

Option 3: Mixed policy by audience and artefact type (Chosen)

Description: Use different languages per audience/artefact with explicit locale rules.
Pros: Optimizes comprehension per audience; keeps code/tooling aligned with industry norms; supports internationalization for UI.
Cons: Requires discipline and templates; introduces bilingual processes; needs glossary and translation workflows for some artefacts.

Decision Outcome

Chosen option: Option 3 — Mixed policy by audience and artefact type.

Permanent technical design documentation: English.
Stakeholder communication (user stories and higher): Dutch.
All UIs must support i18n, with default locale English (en-GB).
Technical source code: English (en-US).

Rationale

Business alignment: Business-facing planning and validation benefit from Dutch for clarity with local stakeholders.
Technical considerations: Code, APIs, and many dependencies use American English spellings; using en-US in code minimizes friction with linters, libraries, and common vocabulary.
Global collaboration: English technical documentation increases reach, improves onboarding of external contributors, and facilitates vendor collaboration.
UX/Localization: en-GB as the default UI locale aligns with many public-sector/user-facing conventions in the Netherlands while keeping the UI internationalizable.
Risk/Cost: Adds some translation and review overhead, but mitigated by templates, linters, and a shared glossary.

Consequences

Positive:
- Clear guidance per artefact reduces review churn.
- Better interoperability with tooling and OSS ecosystems.
- UI prepared for multi-language audiences from day one.
Negative:
- Bilingual process requires discipline and reviewer awareness.
- Occasional translation needed between Dutch stakeholder artefacts and English technical designs.
Neutral:
- Minor spelling differences (en-GB vs en-US) are constrained by artefact type to avoid confusion.

Implementation Plan

Documentation and templates
- Update ADR, arc42, and design templates to state “Technical documentation language: English”.
- Ensure product/backlog templates state “Stakeholder artefacts language: Dutch”.
UI internationalization
- Require i18n libraries/framework support in all UI modules; set default locale to en-GB.
- Establish message key conventions and folder structure for locale resources.
Source code conventions
- Enforce en-US spelling in identifiers, comments, and API schemas.
- Configure linters/IDE inspections/spell-check dictionaries accordingly.
Glossary and translation workflow
- Maintain a bilingual glossary for domain terms (Dutch ↔ English).
- Define a lightweight process for translating user-facing copy and aligning terms across artefacts.
Governance
- Add checklist items to PR/review templates to verify policy adherence.
- Periodically audit for drift and update the glossary.