Localization

The fulfillmenttools platform supports localization, enabling you to manage data in multiple languages. This document outlines how to change user and platform locales, request specific languages for your requests, and handle localized information in entities.

Supported Localization Features

User-specific locales: Determined by user settings in the authentication token.
Request-specific languages: Can be specified using a locale query parameter.
Localized entity fields: Store and retrieve localized field values.

Supported Languages

A list of currently supported languages can be found via the API. All supported languages are also available in the Backoffice and other fulfillmenttools applications.

Get the list of supported locales

GEThttps://%%HOST%%//api/configurations/supportedlocales

Authorization

Response

The supported locales can be found in the body.

Body

itemsSupportedLocale (enum)

ISO 3166 conform country code and ISO 639-1 conform language code (de_DE, en_US, ch_FR, etc.)

de_DEen_USpl_PLru_RUnl_NLfr_FRit_ITnb_NO

Request

const response = await fetch('https://%%HOST%%//api/configurations/supportedlocales', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  "de_DE"
]

Requesting Specific Languages

To request data in a specific language, add the locale query parameter followed by the language code, conforming to the ISO 639-1 standard.

Example request for a specific language

GET /api/endpoint?locale=de_DE

Fallback Language Mechanism

If a requested language is unavailable, the platform uses the following fallback order:

Language specified in user settings.
Default platform language.
English (en_US).
First available language for the entity.
Non-localized field value of the entity.

Handling Localized Information in Entities

Each localizable entity schema contains fields and their corresponding localized versions, which are stored as objects with locale codes as keys.

Example of localized entity fields

{
  "title": "My Product",
  "titleLocalized": {
    "de_DE": "Mein Produkt",
    "fr_FR": "Mon produit",
    "nl_NL": "Mijn product"
  }
}

GET requests return localized values based on the user's locale.
POST, PUT, and PATCH requests must provide all localized values for the desired locales. Partial updates of localized values are not supported.

Using Entities Without Localization

The platform will prioritize returning localized values based on the user's locale. If a non-localized field is patched when a localizedObject is already present, the original field will always be overridden with the localized values in responses.

If localization is not required, omit the <fieldName>Localized object and provide the non-localized field directly.

Example of non-localized usage

{
  "title": "My Product"
}

Changing the User Locale

To change the user locale, send a PATCH request to the user endpoint, including the new locale in the request body. After the change, you must request a new authentication token to reflect the locale update.

Patch an existing user with the given ID

PATCHhttps://%%HOST%%//api/users/{userId}

Authorization

Path parameters

userId*string

ID of the user you want to patch

Body

ModifyUser object

actions*array of ModifyUserAction (all of)

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

Response

The user is successfully modified.

Body

createdstring (date-time)

The date this entity was created at the platform. This value is generated by the service.

lastModifiedstring (date-time)

The date this entity was modified last. This value is generated by the service.

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

customClaimsCustomClaims (object)

Include all different claims could be assigned to a user

firstname*string

id*string

lastname*string

locale*SupportedLocale (enum)

ISO 3166 conform country code and ISO 639-1 conform language code (de_DE, en_US, ch_FR, etc.)

de_DEen_USpl_PLru_RUnl_NLfr_FRit_ITnb_NO

username*string

authenticationProvider*AuthenticationProvider (object)

assignedFacilitiesarray of UserAssignedFacility (object)

Request

const response = await fetch('https://%%HOST%%//api/users/{userId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "version": 42,
      "actions": [
        {
          "action": "ModifyUser"
        }
      ]
    }),
});
const data = await response.json();

Response

{
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42,
  "customClaims": {
    "roles": [
      {
        "facilities": [
          "0T1vKaEar0nuG58CxzA5"
        ],
        "name": "FULFILLER"
      }
    ]
  },
  "firstname": "Alex",
  "id": "LGMl2DuvPnfPoSHhYFOm",
  "lastname": "Schneider",
  "locale": "de_DE",
  "username": "aschneider",
  "authenticationProvider": {
    "type": "EMAIL_PASSWORD",
    "id": "LGMl2DuvPnfPoSHhYFOm"
  },
  "assignedFacilities": [
    {
      "facilityRef": "0T1vKaEar0nuG58CxzA5",
      "assignedZones": [
        {
          "zoneRef": "LGMl2DuvPnfPoSHhYFOm"
        }
      ],
      "id": "LGMl2DuvPnfPoSHhYFOm"
    }
  ]
}

Changing the Default Platform Locale

The default platform locale sets the standard language for the frontend applications. Change it by sending a PUT request to the relevant configuration endpoint.

Change the tenant wide default locale configuration

PUThttps://%%HOST%%//api/configurations/locale

Authorization

Body

Desired default locale configuration to put

createdstring (date-time)

The date this entity was created at the platform. This value is generated by the service.

lastModifiedstring (date-time)

The date this entity was modified last. This value is generated by the service.

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

Response

The locale Configuration was successfully set.

Body

createdstring (date-time)

The date this entity was created at the platform. This value is generated by the service.

lastModifiedstring (date-time)

The date this entity was modified last. This value is generated by the service.

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

Request

const response = await fetch('https://%%HOST%%//api/configurations/locale', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "locale": "de_DE"
    }),
});
const data = await response.json();

Response

{
  "locale": "de_DE",
  "countryLanguageMapping": {
    "DE": "de_DE",
    "US": "en_US",
    "RU": "ru_RU"
  },
  "id": "text"
}

PreviousPagination Interface NextCustom Attributes

Last updated 12 days ago

const response = await fetch('https://%%HOST%%//api/users/{userId}', { method: 'PATCH', headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "version": 42, "actions": [ { "action": "ModifyUser" } ] }), }); const data = await response.json();

{ "created": "2020-02-03T08:45:51.525Z", "lastModified": "2020-02-03T09:45:51.525Z", "version": 42, "customClaims": { "roles": [ { "facilities": [ "0T1vKaEar0nuG58CxzA5" ], "name": "FULFILLER" } ] }, "firstname": "Alex", "id": "LGMl2DuvPnfPoSHhYFOm", "lastname": "Schneider", "locale": "de_DE", "username": "aschneider", "authenticationProvider": { "type": "EMAIL_PASSWORD", "id": "LGMl2DuvPnfPoSHhYFOm" }, "assignedFacilities": [ { "facilityRef": "0T1vKaEar0nuG58CxzA5", "assignedZones": [ { "zoneRef": "LGMl2DuvPnfPoSHhYFOm" } ], "id": "LGMl2DuvPnfPoSHhYFOm" } ] }