Localization for REST APIs

Question

I am starting this discussion to gather more info on localization practices for APIs. It seems HTTP does NOT provide sufficient guidance and even the state of practice is not su

Answer 1

I would keep all data in a universal locale independent format. For numbers using . as a decimal separator, date and time using ISO 8601 and in UTC, etc.

Provide localized text only if it absolutely necessary. In that case get the locale from accept-language header field, and if you have the localized string pass that. If not fallback to the string you have.

For example, you might a multilingual product database that contains product data in several languages. When you write an API for the database you can select the product data in user's language (if any).

Here is a sample.

Answer 2

Ok guys,

here is a summary of how I answer my question. I hope this helps future API authors.

The fundamental requirements for an UI based on top of API excluding currency presentation seem to be:

1. Select the best language out of the available product translations using RFC 4647 list of language ranges
2. Select the best data format out of the available using RFC 4647 list of language ranges
3. Allow clients to provide distinct preferences for translation and format. There will be cases where people will not find the best translation and yet prefer to see the proper formatting aligned with their culture.
4. Allow clients to specify a timezone using IANA TZDB identifiers
5. Format data elements using Unicode CLDR http://cldr.unicode.org/
6. Use named placeholders in localization bundles e.g. "{drive} is corrupt" is easier to translate properly than "{1} is corrupt"

On the REST HTTP headers I suggest use of 3 headers

1. accept-language - used for selecting translation and following the guidelines of RFC 7231 https://tools.ietf.org/html/rfc7231#section-5.3.5
2. format-locale - used to select data formatting style if different from the translation language preferences. Again list of language range elements. Defaults to accept-language if omitted.
3. timezone - used to select timezone for rendering date and time values. This should be valid timezone ID from the IANA TZDB https://www.iana.org/time-zones

Implementation wise it seems Java 8 and later have full capability to implement a globalized application. Other languages and older Java versions seem to have varying degrees of issues.