Internationalize your application

Externalizing messages

Wisdom lets you externalize your messages by creating properties files (containing your messages) in the src/main/resources/i18n folder. The name of the file lets you configure the locale/languages of the messages contained in the file. Let’s see some examples:

  • src/main/resources/i18n/app.properties provides messages in the default locale

  • src/main/resources/i18n/app_fr.properties provides messages in French

  • src/main/resources/i18n/app_en_US.properties provides messages in American English

The default locale (empty locale) is used when there is no locale matching the request. Generally we use this locale for English messages (but you can configure it using the application.default.locale property in the application.conf file).

Note
 The file containing the messages are read using UTF-8.

You can retrieve messages using the org.wisdom.api.i18n.InternationalizationService service:

include::{sourcedir}/controllers/i18n/InternationalizedController.java[tags=retrieve-message]

Notice that you need to specify the language explicitly.

Note
 The messages do not have to be packaged within the application’s bundle, but can be provided in separate bundles, even deployed dynamically.

Retrieving messages using the request languages

HTTP Requests can specify the expected languages using the Accept-Language header. Wisdom parses this header and lets you provide the messages in the most suitable language.

To retrieve the messages using the request accepted languages, just use:

include::{sourcedir}/controllers/i18n/InternationalizedController.java[tags=retrieve-message-request]

Wisdom determines what’s the best language to use for the request. For example, for a request specifying an Accept-Language with en-US,en;q=0.8,de;q=0.6,fr;q=0.4, Wisdom tries to provide the message in American English, then English, then German, then French. If none of them are provided, the default locale is used.

Use in templates

Using internationalized messages in a template is pretty simple. It relies on the Thymeleaf syntax:

<p th:utext="#{home.welcome}">Welcome to our grocery store!</p>

A utext instructs Wisdom to use an internationalized message specified using #{key}. For example, the following template uses two internationalized messages:

include::{resourcedir}/templates/snippets/upload/Internationalized.html[]

Notice that the second message is parameterized.

Formatting messages

Messages can be formatted using the java.text.MessageFormat format. For example, if you have defined a message like this:

files.summary=The directory {1} contains {0} file(s).

You can then specify parameters as:

i18n.get(request().languages(), "files.summary", dir.list().length, dir.getName())

Retrieve messages in JavaScript

The internationalization service can be requested using simple HTTP Requests to retrieve the messages. This lets you retrieve the messages from a JavaScript client or anything able to emit a HTTP GET request.

GET http://localhost:9000/i18n/welcome  ===> The message with the welcome key (returned as text)
GET http://localhost:9000/i18n          ===> All messages (returned as JSON)

Wisdom computes the language to use according to the request (so according to the ACCEPT-LANGUAGE header). When retrieving all messages, the Json structure is composed as follows:

{
  "files.summary":"The directory {1} contains {0} file(s)",
  "welcome":"Welcome"
}