diff --git a/sections/designRules.md b/sections/designRules.md index 3cf9fe3d..190abb98 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -214,6 +214,88 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f +
+

Use standard language codes for localization

+
+
Statement
+
+

A resource containing localized information MUST follow BCP 47 [[RFC4647]] [[RFC5646]]. + All fields in requests and responses containing singular localized information MUST be an object with a field "taal" (Dutch) or "language" (English) with a value conforming [[RFC5646]] and a field "waarde" (Dutch) or "value" (English) with the localized string. +

Use the language subtag registry maintained by IANA for possible language subtags. +

+ +

All fields in requests and responses containing multiple localized options MUST be an array of objects where all objects have a field "taal" (Dutch) or all have a field "language" (English) with a value conforming [[RFC5646]] and all have a field "waarde" (Dutch) or have a field "value" (English) with the localized string. +

+ +

[[?ISO3166-1]] concerns identifiers of countries and MUST NOT be used to denote languages, since countries and languages are not equivalent. +

Following [[RFC4647]] a language code in [[?ISO-639-1]] format matches a language tag in [[RFC5646]] regardless of language subtag. +

+
Rationale
+
+ Standardized language codes removes ambiguity in language handling between systems, potentially present in separate regions with different (spoken) languages. +
+
How to test
+
+
    +
  • Analyse all fields and if the field represents a language and ensure either one of the following options applies: +
      +
    • In case of singular localized information, ensure it is an object. It has two fields "taal" and "waarde" or it has two fields "language" and "value". +
    • In case of multiple localized options, ensure it is an array consisting of objects. Either all objects have two fields "taal" and "waarde" or all objects have two fields "language" and "value". +
    +
  • Confirm each field "taal" or "language" has a value in [[RFC5646]] format. +
+
+
+
+ ## 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.