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>
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 data property wraps the actual information in every response returned by the XS2A-API and has no other purpose.
The locale will always be present and describes the language used for the translations (as explained in the last paragraph of the previous section).
The translations object holds the translation keys and their respective translation as keys and values, respectively.
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'