3.14 Localization
SData is designed for use in multi-lingual contexts. A provider can serve localized versions of resources and its consumers have a mechanism to indicate which localized version they would like to obtain from the provider.
Two mechanisms can be combined to communicate the consumer’s language preference to the provider:
- HTTP Accept-Language header.
- language query parameter.
The HTTP Accept-Language header is the default mechanism. SData follows the HTTP standards, but providers are not required to support the full syntax for these header values, including quality factors. They only need to understand a comma separated list of locale codes and give priority to the first elements of the list. For example:
Accept-Language: fr-CA, fr, en
The provider should localize the response in Canadian French if possible, French as a second choice, English as a third choice.
The language MUST be expressed as a 2 letter ISO 639 code (lower case) and the country as 2 letter ISO 3166 code (upper case). The country code is optional.
The provider should be tolerant and SHOULD automatically downcase the language code and upcase the country code. So a code like fr-ca would be interpreted as fr-CA by the provider.
Usually the Accept-Language value is configured in the consumer and the consumer sends the same value for all requests; unless the user changes the configuration setting.
The language query parameter can be used to override this behaviour. When this parameter is present, the Accept-Language header is ignored and the value of the language query parameter is used instead. This feature is useful when a URL needs to refer to a representation in a specific locale, regardless of the consumer settings. It is also useful for debugging.
The language query parameter accepts the same syntax as the Accept-Language header: a comma separated list of locale codes. For example:
http://www.example.com/sdata/myApp/myContract/-/salesOrders?language=fr-CA,fr,en
If the resource is not available in any of the requested locales, the provider MUST NOT return an error. Instead, it SHOULD return the resource in its default locale.
The sme:isLocalized metadata attribute SHOULD be set in the schema on all properties that hold localized text. See Metadata Extensions section for details.
In localized feeds or entries, only the <title> and <content> elements and the payload properties that are explicitly marked with sme:isLocalized="true" in the schema are eligible for localization. The other payload elements SHOULD NOT be localized. Specifically, date/time values, decimal values and listed members (status codes for examples) SHOULD NOT be localized inside the XML payload.
SData providers and consumers MUST use UTF-8 encoding. Legacy encodings, such as ISO-8859-1 and SJIS, MUST NOT be used because they are a source of complexity and UTF-8 is now a well established standard.
Schemas SHOULD be localized, like any other resource returned by an SData service provider. In a schema resource, the only elements that should be localized are the labels of the elements (see Simple Metadata Extensions Summary).
SData providers SHOULD support this localization protocol. If they do not support it, they SHOULD ignore the Accept-Language header and language parameter. They MUST NOT return an error in this case.