Internationalization

In Spring the texts are formatted by java.text.MessageFormat, so the whole format language is available in the bundle. A choice format is the classic way to write a plural, and each language has its own rule text:

Running the same key with 0, 1 and 5 against the MessageSource printed:

Source: Java — MessageFormat

ChoiceFormat is simple and not complete: it cannot express the plural categories of languages such as Polish or Arabic. For those, a library such as ICU4J is the usual answer. That integration is outside what Thymeleaf offers, and the message resolver extension point described at the end of the page is where it would plug in.

The key does not have to be a literal. Inside the braces a variable expression can supply it, and literal substitution builds it from pieces. Both forms are useful to translate values that live in the data, such as the genre of a book:

Source: Using Thymeleaf — Messages

The first line uses the literal-substitution form with |...| and passes the enum straight in, because its toString() is the name. The second evaluates a SpEL string concatenation. Both printed Science fiction in English and Ciencia ficción in Spanish. A message expression can also be an argument, which is how a translated text is passed into a fragment. The panel fragment takes a heading and shows it unchanged, while the message shelf.panel receives the user name:

Source: Using Thymeleaf — Fragments

Rendered with the Spanish locale, the panel heading was Mi estantería and the paragraph Panel: Ana. Fragment parameters are covered in detail on Fragments.

A key that is built from data you control (an enum name, a status code) is fine. A key built from request input is not: anyone who can pick the key can read any entry of the bundle, including entries that were never meant to be shown, and an unexpected key produces the missing-key marker in the page. Map the input to an allow-list of keys first.

The same lookup is available inside a variable expression through #messages, which is useful when a message has to be passed to another utility method or combined in SpEL:

Source: Using Thymeleaf — Expression Utility Objects

The 3.1.5 class has these method families, each taking the key and up to three parameters, or an array of parameters through the WithParams variants:

Source: Javadoc: Messages 3.1.5.RELEASE

The utility objects are introduced on Expression Utility Objects.

th:text escapes its result, parameters included. th:utext does not escape, and a message expression with parameters used in it inserts the parameter values as raw markup. With a user-supplied name, the two attributes rendered:

Source: Using Thymeleaf — Unescaped Text

Use th:text for every message that takes user data. Reserve th:utext for messages whose parameters are trusted or which you have escaped yourself, for example a bundle text that contains a link.

With Spring, the SpringTemplateEngine builds a SpringMessageResolver around the application’s MessageSource bean, so Thymeleaf and the rest of the application (validation messages, MessageSource calls in controllers) share one set of bundles. Spring Boot creates that MessageSource when a bundle named after spring.messages.basename (default messages) exists on the classpath. These are the properties of Boot 4.1.1, read from its configuration metadata:

Source: Spring Boot — Common Application Properties

The lookup for the locale es_ES tries messages_es_ES.properties, then messages_es.properties, then (if enabled) the file of the JVM default locale, and finally messages.properties. The scratch application sets the system-locale fallback off:

Source: Spring Boot — Internationalization

This is not a cosmetic choice. The first run of the scratch application, on a laptop whose JVM locale is Spanish, rendered the Spanish shelf for an English visitor, because there is no messages_en.properties and the default true made the JVM default win over the base file. A plain ResourceBundleMessageSource reproduced it:

A server in a Spanish data centre would show every unsupported visitor Spanish. With the property off, the base file is the real default language.

When no resolver finds a key, Thymeleaf renders a marker made of the key and the locale between double question marks:

Source: Using Thymeleaf — Messages

The marker is deliberately ugly so that a missing translation is seen in a review. It also shows the locale that was used, which is the fastest way to find out that a visitor is being resolved to es_ES when you expected es. With spring.messages.use-code-as-default-message=true the page shows the plain key instead:

Be aware that this setting makes the Spring lookup return the key, so msgOrNull no longer returns null and the Elvis fallback shown earlier is never taken. Keep the property for local development.

Without Spring the default message resolver is org.thymeleaf.messageresolver.StandardMessageResolver. It looks for .properties files next to the template, named after it: for the template home it reads home_es_ES.properties, home_es.properties and home.properties. The locale comes from the Context and not from the request, so it must be set:

With home.properties holding English texts and home_es.properties the Spanish welcome, the four runs printed:

Source: Using Thymeleaf — Standard Message Resolver

The tutorial’s own example puts those files in /WEB-INF/templates/, next to the templates. An unsupported language (fr) falls to the base file, and the engine does not consult the JVM default locale. A context built with no locale falls back to the system locale, which the tutorial warns against in real applications. The same template-side files are also found when the Spring engine is used and the key is not in the MessageSource; in the scratch run the Spring-engine rendering of home for Spanish gave the same three lines as above. The details of standalone configuration are on Standalone Engine & Configuration.

Spring Boot registers an AcceptHeaderLocaleResolver unless you define your own bean named localeResolver. Two properties, in spring.web, adjust it: spring.web.locale is the locale to use, and spring.web.locale-resolver takes accept-header (default) or fixed. In the scratch application, with those two set to fixed and es-ES, the request below came back in Spanish even though it asked for English:

Source: Spring Boot — Common Application Properties

With the default accept-header resolver the browser’s language list decides. Sending Accept-Language: es-ES,es;q=0.9,en;q=0.8 rendered the Spanish page and fr-FR,fr;q=0.9 rendered <html lang="fr-FR"> with the English texts, because the bundle has no French. A request with no header resolved to the container’s default request locale (en under MockMvc). Because a header with a country (fr-FR) resolves to fr_FR, the lang attribute and the number formats follow it even when the texts do not.

To let the visitor choose, register a resolver that can store a choice, and an interceptor that reads the choice from a request parameter. The bean method must be called localeResolver:

Source: Spring Framework — Locale Resolution, interceptor

CookieLocaleResolver takes the cookie name in its constructor; the 7.0 class has setters for the maximum age (a Duration), path, domain, Secure, HttpOnly and SameSite. The default locale is the answer for a visitor with no cookie. The interceptor reads the parameter named by setParamName (default locale), turns the value into a Locale and calls setLocale on the resolver, which writes the cookie. With setIgnoreInvalidLocale(true) an invalid value is ignored instead of failing the request. A request with ?lang=es-ES returned the Spanish page and this header:

A following request that sent only the cookie rendered <html lang="es-ES"> and the Spanish page, and ?lang=!! changed nothing. ?lang=ar set the cookie to ar and the texts stayed English, because there is no Arabic bundle, while the page switched to dir="rtl" (see the lang and dir section below).

The same two beans with SessionLocaleResolver (no cookie, the choice lives in the HttpSession) behaved like this over three requests with one session:

Source: Spring Framework — Locale Resolution, session

Two cautions follow from the runs. The interceptor works with a resolver that can store a locale: with the Boot default, the same ?lang=es-ES request ended in an error, which Spring reported as:

Second, the language switch is made with a GET request here, which is how the interceptor works by default (its setHttpMethods method restricts it to chosen HTTP methods). It changes only the visitor’s own language preference and nothing on the server, so it is safe without a CSRF token, but it must never carry a side effect. Every state change in the application stays a POST with CSRF protection on.

A switcher is a fragment with one link per language, included in the layout so every page offers it. The link points at the current page with the parameter that the interceptor reads:

Source: Using Thymeleaf — Link URLs

An empty base with a parameter list renders a page-relative URL made only of the query string, so the link stays on the current path. It also replaces the whole query string, which loses other parameters such as a page number; carry them explicitly where that matters. Each link names its own language in that language (lang="es" on Español) so a screen reader pronounces it correctly, and hreflang states the language of the target for search engines and assistive technology. Link expressions are explained on Link URLs and the layout that would include the switcher is on Layouts & the Layout Dialect.