Language & translations

Introduction

The API client should support multiple languages, however the client may only support one language. For clients that do not support multiple languages, the language used must be the default language configured for the API-user.

Default language property

Each API user has a default language configured which can be altered on the user properties in the UI. The API also provides information about which language is set via the API root.

Request

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
https://api.{HOSTNAME}/api/

Response

{
    ...

    "defaultLanguage": "swe",
    "defaultLanguage_iso": {
        "iso639-1": "sv",
        "iso639-3": "swe"
    }
    ...
}

Fields

[field]: This fields represents the text for the API-users default language. Do not use this field together with [field]_lang/[field]_lang2. If the client support at least 1 language then please use the _lang fields instead. Example of a [field] is title field on Product record.
[field]_lang: This fields contains an object with a translation per language. The language code is used as the key and the translation text is the value. Example of a language code is swe. Do not use this field together with [field] during PUT/POST requests. The field will always be shown in the response if [field] or [field]_lang contains a value. Example of fields are title and title_lang. Read more about language codes as defined in the ISO-639 standard.
[field]_lang2: contains the exact same information as [field]_lang except that the language key contains of a 2-letter code e.g sv.
[field]_fallback: all fields have a fallback text which is used for systems that do not support a language. The field [field] e.g. title will set both the default language for the API-user and the title_fallback. The field title_fallback however will never be set by any content in title_lang. The [field]_fallback can be specifically set in the PUT/POST request. The GET response will contain the [field]_fallback if it contains a value (see section Field rules (input)

Examples

Set field

This call will set the title_fallback and the API-users default language:

Request

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}
    -X PUT \
    -d \
    '{
        "title": "Min produkttitel"
    }'

Response

{
    ...
    "title": "Min produkttitel",
    "title_fallback": "Min produkttitel",
    "title_lang": {
        "swe": "Min produkttitel"
    },
    "title_lang2": {
        "sv": "Min produkttitel"
    },
    ...
}

As we can see from the responses above the title, title_fallback, title_lang and title_lang2 field contains the same information and is tagged with ISO-639-1 and ISO-639-3 representation of Swedish as well. Swedish since that is the current default language of the API user as stated above.

Set [field_lang]

This call will NOT set the title_fallback. The field will be empty unless it had a value before this call.

Request

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}
    -X PUT \
    -d \
    '{
        "title_lang": {
            "swe": "Min produkttitel"
        }
    }'

Response

{
    ...
    "title": "Min produkttitel",
    "title_fallback": null,
    "title_lang": {
        "swe": "Min produkttitel"
    },
    "title_lang2": {
        "sv": "Min produkttitel"
    },
    ...
}

Set field_fallback

Set the title_fallback like this when using _lang: Request

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}
    -X PUT \
    -d \
    '{
        "title_fallback": "Min produkttitel"
        "title_lang": {
            "swe": "Min produkttitel"
        }
    }'

Response

{
    ...
    "title": "Min produkttitel",
    "title_fallback": "Min produkttitel",
    "title_lang": {
        "swe": "Min produkttitel"
    },
    "title_lang2": {
        "sv": "Min produkttitel"
    },
    ...
}

Set multiple languages

You can pass language specific translations by using either *_lang or *_lang2;

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}
    -X PUT \
    -d \
    '{
        "title_lang": {
            "swe": "Min produkttitel",
            "eng": "My product title",
            "deu": "Mein Produkttitel"
        }
    }'

Response

{
    ...
    "title": "Min produkttitel",
    "title_fallback": "Min produkttitel",
    "title_lang": {
        "eng": "My product title",
        "deu": "Mein Produkttitel",
        "swe": "Min produkttitel",
    },
    "title_lang2": {
        "en": "My product title",
        "de": "Mein Produkttitel",
        "sv": "Min produkttitel"
    },
    ...
}

The _lang fields enables compatibility for systems that do not support translations. These clients can ignore these fields.

Removal of translations

Remove a language translation

To remove a translation you need to pass null as value, like so;

Request

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}
    -X PUT \
    -d \
    '{
        "title_lang": {
            "eng": null,
        }
    }'

Response

{
    ...
    "title": "Min produkttitel",
    "title_fallback": "Min produkttitel",
    "title_lang": {
        "deu": "Mein Produkttitel",
        "swe": "Min produkttitel",
    },
    "title_lang2": {
        "de": "Mein Produkttitel",
        "sv": "Min produkttitel"
    },
    ...
}

Remove a default language translation

Clear the fallback to completely remove the default language translation like so;

Request

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}
    -X PUT \
    -d \
    '{
        "title_fallback": null,
        "title_lang": {
            "swe": null,
        }
    }'

Response

{
    ...
    "title": null,
    "title_fallback": null,
    "title_lang": {
        "deu": "Mein Produkttitel",
        "swe": null,
    },
    "title_lang2": {
        "de": "Mein Produkttitel",
        "sv": null
    },
    ...
}

Just ignoring the translation will not remove or change it, allowing you to only send the translations you wish to change, see section Field rules (input).

Next: Tax model