Skip to content

Voeg regel toe voor informatie over talen #333

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TimvdLippe wants to merge 5 commits into
base: develop
Choose a base branch
from
Open

Voeg regel toe voor informatie over talen #333

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6ca1e68
Voeg regel toe voor informatie over talen
TimvdLippe May 13, 2026
389e98c
Fix build
TimvdLippe May 13, 2026
75fca9c
Maak test instructie specifieker
TimvdLippe May 13, 2026
f114af0
Update designRules.md
TimvdLippe May 27, 2026
4bee025
Update designRules.md
TimvdLippe May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions sections/designRules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,88 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f</pr
</dl>
</div>

<div class="rule" id="/core/lang-code" data-type="technical">
<p class="rulelab">Use standard language codes for localization</p>
Comment thread
TimvdLippe marked this conversation as resolved.
Outdated
<dl>
<dt>Statement</dt>
<dd>
<p>A resource containing localized information MUST follow <a href="https://www.rfc-editor.org/info/bcp47">BCP 47</a> [[RFC4647]] [[RFC5646]].
All fields in requests and responses containing singular localized information MUST be an object with a field <code>"taal"</code> (Dutch) or <code>"language"</code> (English) with a value conforming [[RFC5646]] and a field <code>"waarde"</code> (Dutch) or <code>"value"</code> (English) with the localized string.
Comment thread
TimvdLippe marked this conversation as resolved.
Outdated
<p class="note">Use the <a href="https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry">language subtag registry</a> maintained by IANA for possible language subtags.
<aside class="example">
The following example shows a response for a resource with singular localized information in an API with Dutch as its interface language.
Comment thread
TimvdLippe marked this conversation as resolved.
Outdated
<pre><code class="json">{
"status": {
Comment thread
TimvdLippe marked this conversation as resolved.
Outdated
"taal": "nl-NL",
"waarde": "Goedgekeurd"
}
}
</code></pre>
</aside>
<aside class="example">
The following example shows a response for a resource with singular localized information in an API with English as its interface language.
<pre><code class="json">{
"status": {
"language": "nl-NL",
"value": "Goedgekeurd"
}
}
</code></pre>
</aside>
<p>All fields in requests and responses containing multiple localized options MUST be an array of objects where all objects have a field <code>"taal"</code> (Dutch) or all have a field <code>"language"</code> (English) with a value conforming [[RFC5646]] and all have a field <code>"waarde"</code> (Dutch) or have a field <code>"value"</code> (English) with the localized string.
<aside class="example">
The following example shows a response for a resource with multiple localized options in an API with Dutch as its interface language.
<pre><code class="json">{
"status": [
{
"taal": "nl-NL",
"waarde": "Goedgekeurd"
},
{
"taal": "en-GB",
"waarde": "Accepted"
}
]
}
</code></pre>
</aside>
<aside class="example">
The following example shows a response for a resource with multiple localized options in an API with English as its interface language.
<pre><code class="json">{
"status": [
{
"language": "nl-NL",
"value": "Goedgekeurd"
},
{
"language": "en-GB",
"value": "Accepted"
}
]
}
</code></pre>
</aside>
<p class="warning">[[?ISO3166-1]] concerns identifiers of countries and MUST NOT be used to denote languages, since countries and languages are not equivalent.
<p class="note">Following [[RFC4647]] a language code in [[?ISO-639-1]] format matches a language tag in [[RFC5646]] regardless of language subtag.
</dd>
<dt>Rationale</dt>
<dd>
Standardized language codes removes ambiguity in language handling between systems, potentially present in separate regions with different (spoken) languages.
</dd>
<dt>How to test</dt>
<dd>
<ul>
<li>Analyse all fields and if the field represents a language and ensure either one of the following options applies:

@joostfarla joostfarla May 27, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hanteren wij Americaans Engels? In dat geval is het analyze ipv analyse.

@TimvdLippe TimvdLippe May 27, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tot nu toe hebben we overal analyse gebruik in deze teksten. Eigenlijk heb ik geen idee welke we precies kiezen.

Laten we dit in een aparte PR oppakken mochten we dit voor alle regels willen updaten.

@sanderke sanderke Jun 1, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Het document is nu een verzameling van contributies in zowel en-GB als en-US.

@bwbroersma bwbroersma Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Goed om dit expliciet in de HTML output mee te nemen, daarnaast kan je dan ook hunspell o.i.d. draaien op bijv. PR toevoegingen (in EU is Euro English / en-150 de standaard, feitelijk vooral en-GB, dat gebruiken we ook bij internet.nl voor Platform Standaardisatie).
IETF heeft geen voorkeur, buiten per document consistentie, zie RFC 7322 - RFC Style Guide - 3. RFC Style Conventions - § 3.1. Language en W3C lijkt en-US te zijn gezien W3C Manual of Style - § 11.2 Spelling met de toevoeging W3C Manual of Style - § 4.1 Write for a global audience.

@bwbroersma bwbroersma Jun 23, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://en.wikipedia.org/wiki/Oxford_spelling#Language_tag_comparison:

The en-GB tag stands for British English; it is not specified whether -ize or -ise should be used in a given instance. The en-GB-oxendict tag uses -ize and -ization.

<ul>
<li>In case of singular localized information, ensure it is an object. It has two fields <code>"taal"</code> and <code>"waarde"</code> or it has two fields <code>"language"</code> and <code>"value"</code>.
<li>In case of multiple localized options, ensure it is an array consisting of objects. Either all objects have two fields <code>"taal"</code> and <code>"waarde"</code> or all objects have two fields <code>"language"</code> and <code>"value"</code>.
</ul>
<li>Confirm each field <code>"taal"</code> or <code>"language"</code> has a value in [[RFC5646]] format.
</ul>
</dd>
</dl>
</div>

## Date and time

Handling date and time is tricky and can lead to confusion among clients. The date-time rules remove ambiguity and provide clarity in the API contract between servers and clients.
Expand Down
Loading