Skip to main content

Localization

Localization is a critical feature for apps that serve a global user base, ensuring that responses are tailored to the individual language preferences of each user.

This document outlines how our REST API implements localization by utilizing language headers in HTTP requests.

Overview​

Our REST API supports multiple languages and delivers localized content based on the Accept-Language header provided in the HTTP request. This header allows clients to specify the language and locale preference for the response messages.

If the requested language is supported, the API will respond in that language; otherwise, it defaults to English.

Supported Languages​

The API currently supports the following languages:

  • English (en)
  • German (de)
  • Italian (it)
  • French (fr)
  • Spanish (es)
  • Dutch (nl)
  • Danish (dk)

New translations are constantly being added to our system, thus this list is updated constantly.

Using the Accept-Language Header​

The Accept-Language header is an HTTP header that clients can use to specify their language preferences. The value of this header is one or more language tags, optionally including a locale. The format is generally a two-letter ISO 639-1 language code, optionally followed by a region code (e.g., en-US for American English or fr-CA for Canadian French).

Syntax
Accept-Language: <language>[-<region>][, <language>[-<region>];q=<quality>]
  • language: A two-letter language code as per ISO 639-1.
  • region: An optional region code as per ISO 3166-1 alpha-2 (e.g., US for the United States).
  • quality: An optional quality value between 0 and 1 that specifies the preference's weight. Higher values indicate a higher preference.

Examples​

Single Language​

Accept-Language: es

With Locale​

Accept-Language: en-GB

Multiple Languages, with Preferences​

Accept-Language: fr-CA, fr;q=0.8, en;q=0.5

Handling Localization​

When a request is received, the API evaluates the Accept-Language header to determine the appropriate language for the response:

Parsing the Header​

The API parses the Accept-Language header, if provided, to extract potential languages and their quality values.

Language Matching​

The API matches the parsed languages against the list of supported languages. If multiple languages are requested, they are considered in order of preference, as indicated by their quality values.

Fallback Language​

If none of the requested languages are supported, or if the Accept-Language header is absent, the API defaults to English (en).

Example of Language Header Usage​

Here is an example of how to set the Accept-Language header in an HTTP request using curl:

curl -H "Accept-Language: de" https://api.gokarla.io/v1/shops/my-shop/orders/?order_number=1234

This request tells the API that the preferred language for responses is German. As German is supported, the tracking events from the order will be localized in German.