Translations

Most of the translating happens internally in the XS2A API, but as the client has a need for showing input validation messages to the consumer (e.g. 'The PIN can only consist of numbers'), the client still has to be able to translate on its own.

Therefore the XS2A API exposes a dedicated endpoint from which the client can get the current translations for a language. We recommend to fetch the translations once at the start of the client session and then use it to translate messages shown to the consumer.

The Request

The Riverbank translation endpoint is reachable at the URL retrieved in the decoded client_token-JWT in the translations_url-field.

GET <decoded(client_token).translations_url>?locale=en-US HTTP/1.1
Host: <Host>
Origin: <origin>
curl -X "GET" "<decoded(client_token).translations_url>?locale=en-US"

The URL is flow specific and should therefore not be reused between different flows.

The response contains an Expires header which client implementations should follow.

Which language to use for the translations is optionally specified in the locale query parameter. If not provided, the language specified when the session was created will be used. If a language has not been set or one has been set but no translations were found, then "en-US" will be used as a fallback.

The Response

The endpoint provides a JSON object that is structured as follows:

{
    data: {
        locale: string,
        translations: {
            <translationkey>: string
        }
    }
}

The locale will always be present and describes the language used for the translations (as explained in the last paragraph of the previous section).

Each translation value will be a text in the ICU MessageFormat. This is especially useful for server-side errors received through Server-side Validation.

Translation-Keys

The API will provide following translation-keys:

Note: If this documentation refers to an element or a form, a XS2A Form API Element or Form is meant.

key description
xs2a.validation_error.min_length default message to show when the min_length validation rule was broken
xs2a.validation_error.max_length default message to show when the max_length validation rule was broken
xs2a.validation_error.required default message to show when the required validation rule was broken
xs2a.validation_error.required.input (optional) message to show when the required validation rule was broken in an input-element
xs2a.validation_error.required.toggle (optional) message to show when the required validation rule was broken in a toggle-element
xs2a.validation_error.required.padlock (optional) message to show when the required validation rule was broken in a padlock-element
xs2a.validation_error.required.switchable (optional) message to show when the required validation rule was broken in a switchable-element
xs2a.validation_error.min_value default message to show when the min_value validation rule was broken
xs2a.validation_error.min_value.input (optional) message to show when the min_value validation rule was broken in an input-element
xs2a.validation_error.min_value.padlock (optional) message to show when the min_value validation rule was broken in a padlock-element
xs2a.validation_error.max_value default message to show when the max_value validation rule was broken
xs2a.validation_error.numeric default message to show when the numeric validation rule was broken
xs2a.validation_error.letters_uppercase default message to show when the letters.uppercase validation rule was broken
xs2a.validation_error.letters_lowercase default message to show when the letters.lowercase validation rule was broken
xs2a.validation_error.symbols default message to show when the symbols validation rule was broken
xs2a.validation_error.char_whitelist default message to show when the char_whitelist validation rule was broken
xs2a.validation_error.char_blacklist default message to show when the char_blacklist validation rule was broken
xs2a.validation_error.pattern default message to show when the pattern validation rule was broken
xs2a.validation_error.allow_selected_min default message to show when the allow_selected_min validation rule was broken
xs2a.validation_error.allow_selected.max default message to show when the allow_selected.max validation rule was broken
xs2a.validation_error.option_disabled default message to show when the option_disabled validation rule was broken

Substitution Variables

The ICU MessageFormat defines a method to insert variables into a message. For this to work the name of the variable and the replacement must be defined.

The following table shows the key (or at least the last part of the key) and the field to which it points.

key field
min_length <element>.validator.min_length
max_length <element>.validator.max_length
required <element>.validator.required
min_value <element>.validator.min_value
max_value <element>.validator.max_value
numeric <element>.validator.numeric
letters_uppercase <element>.validator.letters.uppercase
letters_lowercase <element>.validator.letters.lowercase
symbols <element>.validator.symbols
char_whitelist <element>.validator.char_whitelist
char_blacklist <element>.validator.char_blacklist
pattern_format <element>.validator.pattern_format
allow_selected_min <element#choice>.allow_selected.min
allow_selected_max <element#choice>.allow_selected.max

Example

  format('The PIN field {required, select, true{must not be empty} false{is not required}}.', { required: true }`)
  >> 'The PIN field must not be empty'

results matching ""

    No results matching ""