Localization for the Wallet Admin API

Similar to the localization offered by the Authorization Server API, the Wallet Server API supports localization by allowing administrators to configure specific strings for certain elements in multiple languages. Depending on the end-user's language selection and browser configuration, FPX can return values in the specified language (if so configured).

This chapter will illustrate the different commands that need to be executed to set up additional languages for the Wallet API.

note

For the purposes of this guide, the creation of a new Organization will be used as an example to illustrate language configuration commands. See the tables included at the bottom of each page in the preceding "Configuring a Wallet" section of this guide for more information on which fields can be localized and for which entities.

To define multiple languages when creating a new element (Organization, OAuth Client, OAuth Provider etc.) within the Wallet Server, you can follow one of the following methods:

• Adding translations for one language at a time
• Adding translations for multiple languages at once

The first method uses the 'Accept-Language' header to define the language whereas the second method uses the JSON-API patch extension as defined in the 'Content-Type' header.

Adding translations one language at a time

Using the 'Accept-Language' header

When creating entries in the database using the Wallet Admin API, you may include an Accept-Language header with the request, where the value is the language code.

You can find a full list of language codes in the IANA Language Subtag Registry (search for "Type: language"). These codes (and the value used in the Accept-Language header) are case insensitive.

Be aware that although the Wallet Admin API will not restrict which language codes you may use and configure translations for, there is a setting at the Wallet Server that does. Therefore it is important to ensure that the language translations you add and the languages that the Wallet is configured to accept are in alignment. At the Wallet Server, this configuration is defined by the i18n.allLanguages property in its application config.

Creating a new Organization with localized values in one language

Sample Request

curl -X POST '{{WS_ADMIN_URI}}/organization/1' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --header 'Accept-Language: en' \
  --data-raw '{
  "data": {
    "type": "organization",
    "id": 1,
    "attributes": {
      "name": "IDENTOS",
      "mainOperator": false
    }
  }
}'

In this example, the name attribute is localizable. Because we have supplied an Accept-Language header, this value will be automatically entered into the database as a localized value in English.

Updating an existing Organization with localized values in a new language

Sample Request

curl -X PATCH '{{WS_ADMIN_URI}}/organization/1' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --header 'Accept-Language: fr' \
  --data-raw '{
  "data": {
    "type": "organization",
    "id": 1,
    "attributes": {
      "name": "SOTNEDI",
      "mainOperator": false
    }
  }
}'

In this example, we change the value of the Accept-Language header and perform an update operation using the PATCH method as we would normally. The new value will automatically be entered into the database as a localized value in French.

Getting information about an existing Organization in a specific language

Sample Request

curl -X GET '{{WS_ADMIN_URI}}/organization' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --header 'Accept-Language: fr'

Here we use a simple GET request. The language that is returned for any localizable values is determined by the Accept-Language header.

Assuming the French translation was inserted according to the previous steps, the response to this request would look like:

{
  "data": 
  {
    "type": "organization",
    "id": "1",
    "attributes": {
      "mainOperator": false,
      "name": "SOTNEDI"
    },
    "relationships": {
      "authorizationServers": {
        "data": []
      },
      "clients": {
        "data": []
      },
      "dataSources": {
        "data": []
      }
    }
  }
}

Adding translations for multiple languages at once

A common use case is one where you may have many translations to enter at once for a given entity. To do this, the Wallet Admin API provides an alternative method to the above.

This method makes use of the JSON-API patch extension. The Content-Type header in the request must specify this extension by appending "ext=jsonpatch" to the base value, as follows:

Content-Type: application/vnd.api+json; ext=jsonpatch

important

Do not include an Accept-Language header in your request when using this method.

Similar to all other requests made using the JSON-API patch extension, this request is made to the /json-api endpoint directly, not to the endpoint for the entity itself (i.e. not to /organization in this case).

Two examples are provided:

• Creating a new entity with new translations in multiple languages, and
• Updating an existing entity with new translations in multiple languages.

Create a new entity with new translations in multiple languages

This is a sample request that demonstrates creating a new Organization with multiple translations for its localizable field.

Note that there are IDs supplied in the requests made to the /language-translation endpoint. These are required, but are simply placeholders. You can use the same ID for every language translation entry you create, and they will be replaced when the request is processed.

curl -X PATCH '{{WS_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --data-raw '[
  {
    "op": "add",
    "path": "/organization",
    "value": {
      "type": "organization",
      "id": 1,
      "attributes": {
        "name": "organization-name-translation-key-12345678",
        "mainOperator": false
      }
    }
  },
  {
    "op": "add",
    "path": "/language-translation",
    "value": {
      "type": "language-translation",
      "id": 42,
      "attributes": {
        "locale": "en",
        "messageKey": "organization-name-translation-key-12345678",
        "messageContent": "IDENTOS"
      }
    }
  },
  {
    "op": "add",
    "path": "/language-translation",
    "value": {
      "type": "language-translation",
      "id": 42,
      "attributes": {
        "locale": "fr",
        "messageKey": "organization-name-translation-key-12345678",
        "messageContent": "SOTNEDI"
      }
    }
  }
]'

Update an existing entity with new translations in multiple languages

This is a sample request that demonstrates updating an existing Organization with multiple new translations for its localizable field.

This example should only be used if you have previously made a request to create an Organization that included the Accept-Language header, as shown in the "Creating a new Organization with localized values in one language" section above, or otherwise have an entity where one or more translations have been defined, and now want to add multiple new translations at once.

For this method, there is an additional step to perform.

When the original request was made, the Wallet Admin API automatically created a translation key for the localizable fields. You must therefore retrieve the existing translation key(s) for the localizable field(s) of that existing entity. This is done by simply making a GET request without an Accept-Language header, as shown here:

curl -X GET '{{WS_ADMIN_URI}}/organization' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' 

Response:

{
  "data": {
    "type": "organization",
    "id": "1",
    "attributes": {
      "mainOperator": false,
      "name": "Organization-name-453d4e9b-f493-4543-8552-2e102633b3cd"
    },
    "relationships": {
      "authorizationServers": {
        "data": []
      },
      "clients": {
        "data": []
      },
      "dataSources": {
        "data": []
      }
    }
  }
}

You must then use this key to make the next request where you will add multiple new translations in other languages:

curl -X PATCH '{{WS_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --data-raw '[
  {
    "op": "add",
    "path": "/language-translation",
    "value": {
      "type": "language-translation",
      "id": 42,
      "attributes": {
        "locale": "fr",
        "messageKey": "Organization-name-453d4e9b-f493-4543-8552-2e102633b3cd",
        "messageContent": "IDENTOS in French"
      }
    }
  },
  {
    "op": "add",
    "path": "/language-translation",
    "value": {
      "type": "language-translation",
      "id": 42,
      "attributes": {
        "locale": "es",
        "messageKey": "Organization-name-453d4e9b-f493-4543-8552-2e102633b3cd",
        "messageContent": "IDENTOS in Spanish"
      }
    }
  }
]'