Internationalization

Client requests multiple languages

A client need to specify which languages it wants results in, this is done through the RFC2616 Accept-Language header.

Accept-Language: en, de

When an update request is done, graviton will always send a Content-Language header containing the languages of the document.

Please note that you are expected to request multiple languages to implement offline language switching capabilities.

Languages are divided by “domains”. The first part of the url is used to map the domain and is then mapped as the ID for the translation to make it faster for longer translations and saving resources on indexes, sha1( domain + language + translation). All translations within the same domain will be unique even if saving same translation for different domain services.

For example, an api /magazine/ translations will not have the same translations as in /book/ but if a book title is updated having the exact same title as an another book, that second book will now share the same title translation. This is useful as all translations will match, just keep in mind that when designing the api definition if a translation is what you need.

Server returns localized responses

The server responds with content localized into all the possible language-tags requested by the client. It indicates which languages where used in a Content-Language header.

Content-Language: en, de

{
  "title": {
    "en": "Hello World!",
    "de": "Hallo Welt!"
  }
}

Client updating translated data

The client should indicate what languages it’s updating by using Content-Language. It should send translated data in all the specified languages. Leaving out languages will lead to an error.

Default behaviour

The default behavior of graviton is to reply in english. Defined in parameters.

Inner working of translation features.

The underlying data store of the translation features are exposed as service on their own right. A language needs to be defined before any translation can be done. First create the language, then translations.

You may use these services to translate strings directly or to store you own application translations if you wish to do so.

• The /i18n/language/ service contains a listing languages available for services.
• The /i18n/translatable/ service contains a listing of all the available translatable strings.

The translatable structure:

• The id field is a based on the sha1 of domain, locale and original.
• The domain field is based on the service name, it is usually based on the first part of the URL.
• The original field for original text to be translated.
• The translated field for translation.
• The isLocalized field may be used to indicate if a field has been translated yet.

If you want to store your own strings in the translatable endpoint you should choose a domain that does not clash with existing domains.