Localizing Error Messages

We use the req.error() method from the message API both in the implementation class for the AdminService from our scenario and in the implementation class for our CatalogService. We use this method to output error messages if validations fail. So far, we have hard-coded the reported messages as text literals.

In this lesson, we will learn how to internationalize messages. Instead of embedding them hard-coded, they are maintained in separate files - so-called text bundles - as key-value pairs. The keys are then used by the application code to access the corresponding texts. This means that the values for the keys are the actual language-specific texts. In order to support different languages, different files are maintained that provide translated texts for the same keys (see following figure). 

The detailed procedure is as follows: Create a file with the name messages.properties in a folder called _i18n, i18n or assets/i18n. The folder for the messages.properties file must either be located directly below the project directory or in a directory that contains files that are used to define service models (such as the srv directory in our project).

The required texts are maintained as key-value pairs in the messages.properties file. Usually, the texts are maintained there in English. Placeholders can be used, which are noted in the form "{n}". n runs through the natural numbers starting with 0.

To support additional languages, additional files are created in the same folder as the messages.properties file according to the following naming convention: messages<_languageCode><_countryCode>.properties. The country code is optional. Examples of such file names are messages_de.properties, messages_fr_CA.properties or messages_es_MX.properties.

The additional files use the same keys as the messages.properties file. However, the values for the keys are translated according to the language code and, if applicable, the country code from the file name.

In the example shown, two .properties files have been created: messages.properties with English texts and messages_de.properties with the corresponding German translations.

Assume that a text is queried via a key when processing a request, whereby German was determined for the language. If a text is maintained for the key in the messages_de.properties file, this text is used by the application. However, if there is no messages_de.properties file or the key used is not maintained in the existing messages_de.properties file, CAP falls back to the messages.properties file and attempts to determine a value for the key via this file. If this is possible, the corresponding text is used by the application. If messages.properties does not contain a matching entry either, the application uses the key name as text.

The texts maintained in the text bundles can be accessed via the message API, for example via the methods req.error() or req.warn(). To do this, the corresponding key is simply passed to these methods instead of the actual message (see following figure).

Optionally, an array with placeholder values can be passed to the methods from the message API as last parameter. The first value from the array is then used for the placeholder {0}, the second value from the array for the placeholder {1} and so on.

You can use the URL parameter sap-locale to test different languages. In the following example, German texts are requested:

1234567
POST <service_url>/submitOrder?sap-locale=de
Content-Type: application/json

{
  "book": "0ec991dc-95c5-4d8f-91e6-f81a92744781",
  "quantity": 0
}

Alternatively, you can also use requests with an appropriate Accept-Language header:

12345678
POST <service_url>/submitOrder
Accept-Language: de
Content-Type: application/json

{
  "book": "0ec991dc-95c5-4d8f-91e6-f81a92744781",
  "quantity": 0
}

The URL parameter sap-locale has the highest preference. It overrides the Accept-Language header if this should also be set.

Watch the video to see how to use localized error messages.