Taal-selectie/ontdekking
Introductie
De detectie van de taal van een bepaalde resource is belangrijk voor clients met taal-afhankelijke functionaliteiten, zoals bijvoorbeeld het samenvatten en beschrijven van bepaalde resources afhankelijk van de taal van de gebruiker.
Anderzijds gaat de selectie van een taal een stap verder, hierbij kunnen protocollen zoals HTTP language negotiation door clients gebruikt worden om een bepaalde resource in een gegeven taal op te vragen.
Een API MOET minimaal ondersteuning bieden voor één van de volgende taalcodes:
- nl-BE
- nl
Opmerking: We spreken hier over de taal van de data, niet van de controle. Hier zijn bijvoorbeeld de taal van de naam en beschrijving van resources van belang. De taal die (eventueel) gebruikt wordt binnen URLs of andere API-specifieke benamingen is irrelevant, aangezien clients hier geen interpretatie van (zouden) moeten doen.
Nakomingsniveaus
Zie ook: https://github.com/Informatievlaanderen/generieke-hypermedia-api#nakomingsniveaus
HTTP
Voor het toelaten van de detectie van de taal van een resource MOET een Content-Language HTTP header beschikbaar te zijn voor de resource binnen een server response.
Voor het toelaten van de selectie van de taal van een resource MOET een server de Accept-Language in de client request correct behandelen, zodat HTTP language negotiation kan plaats vinden.
Semantisch
Voor het toelaten van de detectie van de taal van een resource MOET tekst geannoteerd te zijn met een taal door middel van RDF language tagged strings.
Voor de selectie van een taal schrijven we op semantisch niveau geen vereisten voor. Hiervoor kan ofwel enkel selectie door middel van HTTP language negotiation gebruikt worden, ofwel kan een eigen hypermedia operatie beschreven worden met een taal-parameter.
Opmerking: De HTTP en Semantische nakomingsniveaus moeten compatibel zijn met elkaar. Dit wilt zeggen dat wanneer een Content-Language header beschikbaar binnen de (RDF) response voor een resource, dat minstens language tagged strings in die taal beschikbaar moeten zijn.
Code voorbeelden
HTTP
Client request:
GET /api/resource/1 HTTP/1.1
Host: example.org
Accept-Language: nl-be,nl-nl;q=0.7
Server response:
HTTP/1.1 200 OK
Content-Language: nl-be
...
Semantisch
RDF response:
rdfs:label "Gent"@nl-be
"Ghent"@en-us.
JSON-LD response
{
"@context": {
"label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@container": "@language" }
},
"@id": "/api/resource/1",
"label": {
"nl-be": "Gent",
"en-us": "Ghent"
}
}
Algoritme voor language negotiation
https://www.ietf.org/rfc/rfc4647.txt