Skip to content

5. Internacionalização

Uma aplicação internacionalizada exibe seus textos no idioma do usuário. O estudo de caso está em francês e inglês. O princípio é simples: as views não contêm mais texto, mas sim chaves ([MENU.HOME]), e um dicionário para cada idioma associa um texto a cada chave. O idioma selecionado é armazenado em um cookie.

O [Spring] tem seu próprio sistema de tradução: a interface [MessageSource], cuja implementação padrão lê arquivos como [messages_fr.properties], [messages_en.properties]... Manteremos a interface, já que o [Spring] e o [Thymeleaf] a usam para tradução, mas nós mesmos a implementaremos, usando uma pequena classe que lê dicionários JSON: são os mesmos arquivos das versões [ASP.NET Core MVC] e [NestJS] do estudo de caso, e seu formato pode ser lido e escrito sem nenhuma ferramenta especial. Em contrapartida, deixaremos que o [Spring MVC] cuide da seleção do idioma de cada requisição: esse é o papel de seu resolvedor de idioma ([LocaleResolver]), que encontramos no Exemplo 16.

5.1. Exemplo 22: Uma aplicação bilíngue

22-i18n/
├── src/main/java/example22/
│   ├── config/
│   │   └── WebConfig.java
│   ├── controllers/
│   │   ├── LanguageController.java
│   │   └── PagesController.java
│   ├── translation/
│   │   ├── Formats.java
│   │   └── Translator.java
│   └── Example22Application.java
├── src/main/resources/
│   ├── i18n/
│   │   ├── en.json
│   │   └── fr.json
│   ├── static/css/
│   │   └── styles.css
│   ├── templates/
│   │   ├── fragments/
│   │   │   └── navbar.html
│   │   ├── pages/
│   │   │   ├── home.html
│   │   │   └── products.html
│   │   └── layout.html
│   └── application.properties
└── pom.xml

Os arquivos [pom.xml] (o starter [Thymeleaf]), [application.properties] (porta 5000), [Example22Application.java] (a classe de inicialização) e [styles.css] são os mesmos dos exemplos anteriores.

5.1.1. Os dicionários

O arquivo [src/main/resources/i18n/fr.json]:

{
  "MENU": {
    "HOME": "Accueil",
    "PRODUCTS": "Produits"
  },
  "HOME": {
    "TITLE": "Bienvenue",
    "HELLO": "Bonjour {name} !",
    "DATE": "Nous sommes le {date}."
  },
  "PRODUCTS": {
    "TITLE": "Nos produits",
    "NAME": "Produit",
    "PRICE": "Prix",
    "COUNT": "{n} produit(s) au catalogue."
  }
}

O arquivo [src/main/resources/i18n/en.json]:

{
  "MENU": {
    "HOME": "Home",
    "PRODUCTS": "Products"
  },
  "HOME": {
    "TITLE": "Welcome",
    "HELLO": "Hello {name}!",
    "DATE": "Today is {date}."
  },
  "PRODUCTS": {
    "TITLE": "Our products",
    "NAME": "Product",
    "PRICE": "Price",
    "COUNT": "{n} product(s) in the catalogue."
  }
}
  • Um dicionário é um arquivo JSON, organizado por página ou por tema: a chave [HOME.HELLO] refere-se ao texto [HELLO] da seção [HOME];
  • Linha 8: um texto pode conter parâmetros, delimitados por chaves, que são substituídos durante a tradução. A ordem das palavras varia de um idioma para outro: é por isso que um texto não é criado simplesmente concatenando segmentos traduzidos.

Os dicionários ficam em [src/main/resources]: o [Maven] copia essa pasta para [target/classes], junto com as classes compiladas. Eles fazem parte, portanto, do classpath, o conjunto de pastas e arquivos compactados onde o [Java] procura as classes e os recursos da aplicação: é de lá que o programa os lerá, independentemente da pasta a partir da qual for iniciado.

5.1.2. O serviço de tradução

O arquivo [translation/Translator.java], em duas partes. A primeira parte lê os dicionários e traduz:

package example22.translation;

import java.io.IOException;
import java.io.InputStream;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import org.springframework.context.MessageSource;
import org.springframework.context.MessageSourceResolvable;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;

import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;

// o serviço de tradução: os dicionários JSON, lidos UMA VEZ na inicialização.
// Ele implementa a interface MessageSource do Spring e se chama [messageSource]:
// o Spring então o usa para TODAS as traduções, e o Thymeleaf para as
// expressões #{...} das views.
@Component("messageSource")
public class Translator implements MessageSource {

    public static final List<String> LANGUAGES = List.of("fr", "en");
    public static final String DEFAULT_LANGUAGE = "en";

    // {name}: um parâmetro em um texto
    private static final Pattern PARAMETER = Pattern.compile("\\{(\\w+)\\}");

    // idioma -> (chave completa "HOME.HELLO" -> texto)
    private final Map<String, Map<String, String>> dictionaries = new HashMap<>();

    public Translator() throws IOException {
        ObjectMapper json = new ObjectMapper();
        for (String language : LANGUAGES) {
            // os dicionários estão em src/main/resources/i18n, portanto no classpath
            try (InputStream stream = new ClassPathResource("i18n/" + language + ".json").getInputStream()) {
                Map<String, String> dictionary = new HashMap<>();
                flatten(json.readTree(stream), "", dictionary);
                dictionaries.put(language, dictionary);
            }
        }
    }

    // o idioma suportado mais próximo de [locale]: "fr_FR" -> "fr"; "de" -> "en"
    public static String language(Locale locale) {
        String language = locale == null ? "" : locale.getLanguage();
        return LANGUAGES.contains(language) ? language : DEFAULT_LANGUAGE;
    }

    // translate("HOME.HELLO", ["name", "Marie"], en) -> "Hello Marie!"
    // Os parâmetros são passados como pares (nome, valor).
    public String translate(String key, Object[] parameters, Locale locale) {
        if (key == null || key.isEmpty()) {
            return "";
        }
        // uma chave ausente exibe a própria chave: um esquecimento fica visível na tela
        String text = dictionaries.get(language(locale)).getOrDefault(key, key);
        if (parameters == null || parameters.length == 0) {
            return text;
        }
        Map<String, String> values = new HashMap<>();
        for (int i = 0; i + 1 < parameters.length; i += 2) {
            values.put(String.valueOf(parameters[i]), String.valueOf(parameters[i + 1]));
        }
        // cada {name} é substituído pelo valor do parâmetro de mesmo nome
        Matcher m = PARAMETER.matcher(text);
        return m.replaceAll(r -> Matcher.quoteReplacement(values.getOrDefault(r.group(1), r.group())));
    }

    // { "MENU": { "HOME": "Home" } } -> { "MENU.HOME": "Home" }
    private static void flatten(JsonNode node, String prefix, Map<String, String> result) {
        for (Map.Entry<String, JsonNode> property : node.properties()) {
            String key = prefix.isEmpty() ? property.getKey() : prefix + "." + property.getKey();
            if (property.getValue().isObject()) {
                flatten(property.getValue(), key, result);
            } else {
                result.put(key, property.getValue().asString());
            }
        }
    }

Vamos detalhar este código:

  • linhas 24 e 25: o serviço é um bean (anotado com [@Component]) e, portanto, um singleton: os arquivos são lidos apenas uma vez, na inicialização. Ele implementa a interface [MessageSource] do [Spring] e se chama [messageSource], conforme especificado pela anotação. Esse nome não foi escolhido ao acaso: é com esse nome que o [Spring] procura o serviço de tradução da aplicação. O [Spring Boot], que cria um por padrão (ele leria os arquivos [messages*.properties]), deixa de fazê-lo assim que existe um bean com esse nome;
  • linhas 27 e 28: os idiomas suportados e o idioma padrão. [List.of] cria uma lista somente leitura;
  • linha 31: a expressão regular [\{(\w+)\}] (uma chave de abertura, um ou mais caracteres de palavra, capturados, uma chave de fechamento), que identifica os parâmetros em um texto. Em uma string [Java], a barra invertida é escrita como [\\]. [Pattern.compile] a analisa uma única vez;
  • linha 34: para cada idioma, um dicionário [Java] ([Map]) que associa cada chave completa ([HOME.HELLO]) ao seu texto;
  • linhas 36 a 46: o construtor lê os arquivos JSON. [ClassPathResource] refere-se a um arquivo no classpath (veja acima). A instrução [try (...)] (conhecida como instrução “try-with-resources”) fecha automaticamente o fluxo aberto entre seus parênteses ao final do bloco, mesmo que ocorra um erro. O objeto [ObjectMapper] da biblioteca [Jackson] (a que o [Spring] usa para JSON) analisa o texto e o converte em uma árvore de nós [JsonNode];
  • linhas 49 a 52: o idioma suportado mais próximo de um idioma qualquer. Um objeto [Locale] do tipo [Java] designa um idioma, possivelmente especificado por um país ([fr], [en_US]...); [getLanguage()] fornece seu código de duas letras. Um idioma não suportado ([de]) retorna o idioma padrão;
  • linhas 56 a 72: a tradução. A chave é procurada no dicionário do idioma solicitado; se não for encontrada, a própria chave é exibida ([getOrDefault]): uma omissão fica imediatamente visível na tela;
  • linhas 65 a 68: os parâmetros são armazenados em um array [Object[]], como pares (nome, valor): [["name", "Marie"]]. O laço os organiza em um dicionário [name -> value]. Veremos por que esse formato um tanto incomum foi escolhido;
  • linhas 70 e 71: [replaceAll] substitui cada parâmetro [{name}] encontrado no texto pelo resultado da lambda: o valor do parâmetro de mesmo nome ([r.group(1)] é a parte capturada entre parênteses) ou o próprio parâmetro, deixado como está, se ele não tiver valor ([r.group()] é o texto inteiro encontrado). [Matcher.quoteReplacement] protege os caracteres [$] e [\] que um valor poderia conter e que, de outra forma, têm um significado específico para o [replaceAll];
  • Linhas 75 a 84: o método “achata” o JSON: o objeto ["HOME": { "HELLO": "..." }] produz a chave [HOME.HELLO]. Ele chama a si mesmo (método recursivo) para percorrer objetos aninhados. [properties()] retorna os pares (nome, valor) de um objeto JSON; [asString()] retorna o valor de um texto.

A segunda parte implementa a interface [MessageSource]:

    // ——— a interface MessageSource

    @Override
    public String getMessage(String code, Object[] args, String defaultMessage, Locale locale) {
        return translate(code, args, locale);
    }

    @Override
    public String getMessage(String code, Object[] args, Locale locale) {
        return translate(code, args, locale);
    }

    // uma mensagem descrita por vários códigos possíveis (os erros de validação):
    // o primeiro código presente no dicionário vence
    @Override
    public String getMessage(MessageSourceResolvable message, Locale locale) {
        Map<String, String> dictionary = dictionaries.get(language(locale));
        String[] codes = message.getCodes() == null ? new String[0] : message.getCodes();
        for (String code : codes) {
            if (dictionary.containsKey(code)) {
                return translate(code, message.getArguments(), locale);
            }
        }
        String defaultText = message.getDefaultMessage();
        return defaultText != null ? defaultText : (codes.length > 0 ? codes[0] : "");
    }
}
  • linhas 3 a 11: os dois métodos que traduzem um código (uma chave) e seus argumentos para um determinado idioma; eles chamam [translate]. A anotação [@Override] instrui o compilador a verificar se um método da interface está de fato sendo sobrescrito;
  • linhas 15 a 26: o terceiro método recebe um objeto [MessageSourceResolvable], que descreve uma mensagem por meio de vários códigos possíveis, do mais específico ao mais geral. É assim que o [Spring] descreve os erros de validação (veja o Exemplo 19): uma restrição [@NotBlank] no campo [name] de um objeto [person] produz os códigos [NotBlank.person.name], [NotBlank.name], [NotBlank]... O primeiro código presente no dicionário tem precedência; se nenhum estiver presente, retorna-se a mensagem padrão ou o primeiro código. O estudo de caso usa isso para traduzir suas mensagens de erro.

No [Spring], o formato usual dos parâmetros de mensagem é posicional: [Hello {0}!], em que o primeiro argumento substitui [{0}]. Preferimos parâmetros nomeados, que são mais legíveis em um dicionário ([Hello {name}!]) e idênticos aos das outras versões do estudo de caso. No entanto, a interface [MessageSource] só transmite um array de argumentos; daí a convenção de pares (nome, valor).

5.1.3. Traduzindo nas views

Em uma view [Thymeleaf], a expressão [#{KEY}], simplesmente apresentada pelo array do Exemplo 14, é a tradução da chave [KEY] para o idioma da requisição: o [Thymeleaf] chama o bean [messageSource], isto é, nosso [Translator]. Os argumentos são passados entre parênteses: [#{HOME.HELLO('name', ${name})}] chama [getMessage("HOME.HELLO", ["name", "Marie"], language)]. Nenhuma classe precisa ser escrita do lado da view; essa é a vantagem de ter implementado a interface do [Spring].

Restam as datas e os valores, que não são traduzidos, mas formatados de acordo com o idioma. O arquivo [translation/Formats.java]:

package example22.translation;

import java.math.BigDecimal;
import java.text.NumberFormat;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.Currency;

import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.stereotype.Component;

// datas e valores, formatados no idioma da requisição (veja o exemplo 16)
@Component("formats")
public class Formats {

    // uma data por extenso
    public String longDate(LocalDate date) {
        return date.format(DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(LocaleContextHolder.getLocale()));
    }

    // um valor em euros
    public String money(BigDecimal amount) {
        NumberFormat format = NumberFormat.getCurrencyInstance(LocaleContextHolder.getLocale());
        format.setCurrency(Currency.getInstance("EUR"));
        return format.format(amount);
    }
}

Esta é, mais ou menos, a classe do Exemplo 16:

  • linha 14: um bean chamado [formats], ao qual as views se referem como [${@formats.longDate(...)}];
  • linhas 19 e 24: [LocaleContextHolder.getLocale()] especifica o idioma da requisição atual. Veremos quem o define;
  • linha 19: uma data em formato longo ([FormatStyle.FULL]), nesse idioma;
  • linhas 24 a 26: um valor, no formato monetário desse idioma, em euros, independentemente do idioma.

5.1.4. Seleção do idioma

O arquivo [config/WebConfig.java]:

package example22.config;

import java.time.Duration;
import java.util.Locale;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

// a configuração do Spring MVC, complementada
@Configuration
public class WebConfig implements WebMvcConfigurer {

    // Bootstrap, compartilhado pelos exemplos: a pasta examples/common/bootstrap
    // é servida na URL /bootstrap/...
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/bootstrap/**")
                // "file:": uma pasta do disco, relativa à pasta atual. Duas
                // tentativas: iniciado a partir da pasta do exemplo, ou a partir de [examples]
                .addResourceLocations("file:../common/bootstrap/", "file:common/bootstrap/");
    }

    // o idioma de cada requisição: o do cookie [language], inglês caso contrário.
    // O bean deve se chamar [localeResolver]: é com este nome que o Spring o procura.
    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver("language");
        resolver.setDefaultLocale(Locale.ENGLISH);
        resolver.setCookieMaxAge(Duration.ofDays(365));
        resolver.setCookieHttpOnly(true);
        resolver.setCookieSameSite("Lax");
        return resolver;
    }
}

Vamos detalhar este código:

  • Linhas 19 a 25: os arquivos do [Bootstrap], como nos exemplos anteriores;
  • Linhas 29 a 37: o bean [localeResolver] (que é o nome [Spring MVC] usa para procurá-lo) define o idioma de cada requisição. No início de cada requisição, o [Spring MVC] pede a ele o idioma e o armazena em [LocaleContextHolder] durante a requisição: os métodos de [Formats], as expressões [#{...}] do [Thymeleaf] e a variável [#locale] nas views o obtêm de lá;
  • linha 31: um [CookieLocaleResolver], fornecido pelo [Spring], lê o idioma de um cookie, aqui chamado [language]. O cookie contém o código do idioma ([en]);
  • linha 32: sem cookie, o idioma é o inglês. Observe que o idioma do navegador (cabeçalho [Accept-Language]) é então ignorado: o usuário escolhe o idioma pelos botões FR / EN;
  • Linhas 33 a 35: as características do cookie que o [CookieLocaleResolver] gravará quando o idioma for alterado: duração de um ano; [HttpOnly] (o [JavaScript] da página não pode lê-lo); [SameSite=Lax] (ele não é enviado em requisições POST vindas de outros sites).

O arquivo [controllers/LanguageController.java]:

package example22.controllers;

import java.net.URI;
import java.util.Locale;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.LocaleResolver;

import example22.translation.Translator;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Controller
public class LanguageController {

    private final LocaleResolver localeResolver;

    public LanguageController(LocaleResolver localeResolver) {
        this.localeResolver = localeResolver;
    }

    // GET /language/fr: armazena a escolha em um cookie e depois volta à página anterior
    @GetMapping("/language/{language}")
    public String change(@PathVariable String language, HttpServletRequest request, HttpServletResponse response) {
        if (!Translator.LANGUAGES.contains(language)) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND);
        }
        // o LocaleResolver escreve seu cookie por conta própria (nome, valor, duração...)
        localeResolver.setLocale(request, response, Locale.forLanguageTag(language));
        return "redirect:" + originPage(request);
    }

    // a página de onde viemos (cabeçalho Referer), da qual mantemos apenas o caminho:
    // redirecionar para um endereço completo tirado da requisição permitiria
    // enviar o usuário a outro site (vulnerabilidade de "open redirect")
    private static String originPage(HttpServletRequest request) {
        String referer = request.getHeader("Referer");
        try {
            URI url = URI.create(referer);
            String path = url.getRawPath();
            // "//site.com/..." seria entendido pelo navegador como um endereço
            // em OUTRO site: rejeitado também
            if (path == null || !path.startsWith("/") || path.startsWith("//")) {
                return "/";
            }
            return url.getRawQuery() == null ? path : path + "?" + url.getRawQuery();
        } catch (RuntimeException e) {
            // sem cabeçalho Referer (NullPointerException), ou um endereço inválido
            return "/";
        }
    }
}

Vamos detalhar este código:

  • linhas 20 a 24: o controller recebe o [LocaleResolver] por injeção de dependência;
  • linhas 27 a 35: [GET /language/fr] armazena a seleção em um cookie e depois redireciona para a página de onde o usuário veio. Um idioma desconhecido dispara um erro 404 ([ResponseStatusException], veja o Exemplo 21);
  • linha 33: nós mesmos não criamos o cookie; em vez disso, pedimos ao [LocaleResolver] que altere o idioma, e ele grava o cookie com o nome e as características especificados em [WebConfig]. [Locale.forLanguageTag("en")] cria o objeto [Locale] para o inglês;
  • linha 34: [redirect:] solicita um redirecionamento (veja o exemplo 04);
  • linhas 40 a 55: a página original é indicada pelo cabeçalho [Referer], que o navegador adiciona quando um link é clicado. Mantemos apenas o caminho e os parâmetros ([getRawPath], [getRawQuery]: como aparecem no endereço, sem decodificação). Redirecionar para uma URL completa vinda da requisição permitiria que um site malicioso criasse um link que, depois de passar pelo nosso site, enviasse o usuário ao site malicioso (uma vulnerabilidade conhecida como [open redirect]);
  • linhas 45 a 49: um caminho que começa com duas barras também é rejeitado: o navegador interpretaria [//pirate.example/trap] como o endereço [http://pirate.example/trap], em outro site;
  • linhas 51 a 54: sem o cabeçalho [Referer], [URI.create(null)] dispara uma [NullPointerException]; um endereço inválido, uma [IllegalArgumentException]. Ambas derivam de [RuntimeException]: isso leva você de volta à página inicial.

5.1.5. As views

O arquivo [templates/layout.html]:

<!doctype html>
<!--/* #locale: o idioma da requisição; seu código de duas letras: #locale.language */-->
<html xmlns:th="http://www.thymeleaf.org" th:lang="${#locale.language}" th:fragment="page(title, content)">
<head>
  <meta charset="utf-8">
  <!--/* o título é uma CHAVE, fornecida pela página, traduzida pelo layout */-->
  <title th:text="#{${title}}">Title</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <nav th:replace="~{fragments/navbar :: navbar}"></nav>
    <main th:replace="${content}"></main>
  </div>
</body>
</html>
  • Linha 3: o template (veja o Exemplo 15) é um fragmento com dois parâmetros: o título da página e seu conteúdo. O atributo [lang] da página reflete o idioma selecionado (útil para leitores de tela e corretores ortográficos): [#locale] é o idioma da requisição, e [#locale.language] é seu código de duas letras;
  • linha 7: o título da página é uma chave, fornecida pela página e traduzida pelo template: em [#{${title}}], a própria chave é o resultado de uma expressão;
  • linha 13: a barra de navegação, um fragmento de outro arquivo.

O arquivo [templates/fragments/navbar.html]:

<nav class="navbar navbar-expand bg-light rounded mb-3 px-3" th:fragment="navbar">
  <div class="navbar-nav me-auto">
    <!--/* #{KEY}: a tradução de uma chave, no idioma da requisição */-->
    <a class="nav-link" href="/" th:text="#{MENU.HOME}">Home</a>
    <a class="nav-link" href="/products" th:text="#{MENU.PRODUCTS}">Products</a>
  </div>
  <!--/* o idioma atual é destacado */-->
  <div class="btn-group btn-group-sm" th:with="language=${#locale.language}">
    <a class="btn" th:classappend="${language == 'fr'} ? 'btn-primary' : 'btn-outline-primary'" href="/language/fr">FR</a>
    <a class="btn" th:classappend="${language == 'en'} ? 'btn-primary' : 'btn-outline-primary'" href="/language/en">EN</a>
  </div>
</nav>
  • Linhas 4 e 5: dois textos traduzidos. O texto escrito dentro da tag ([Home]) só é exibido se o arquivo for aberto diretamente em um navegador; o [Thymeleaf] o substitui pela tradução;
  • linha 8: [th:with] define uma variável local, [language], que pode ser usada dentro da tag e de suas tags filhas;
  • Linhas 9–10: dois links (mudar o idioma não modifica nenhum dado da aplicação: um GET é suficiente), com o idioma atual destacado: [th:classappend] adiciona uma classe CSS às já existentes na tag.

O arquivo [templates/pages/home.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('HOME.TITLE', ~{::main})}">
<body>
<main>
  <h1 th:text="#{HOME.TITLE}">Welcome</h1>
  <!--/* um parâmetro: o par (nome do parâmetro, valor) */-->
  <p th:text="#{HOME.HELLO('name', ${name})}">Hello Marie!</p>
  <!--/* a data, formatada primeiro, depois passada como o parâmetro [date] */-->
  <p th:text="#{HOME.DATE('date', ${@formats.longDate(today)})}">Today is...</p>
</main>
</body>
</html>
  • linha 2: a página chama o template, usando a chave para seu título e conteúdo (a tag [main]);
  • linha 7: um parâmetro, passado como um par (nome, valor);
  • linha 9: a data é primeiro formatada pelo bean [formats] e depois passada como o parâmetro [date] para a mensagem.

O arquivo [templates/pages/products.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page('PRODUCTS.TITLE', ~{::main})}">
<body>
<main>
  <h1 th:text="#{PRODUCTS.TITLE}">Our products</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th th:text="#{PRODUCTS.NAME}">Product</th><th class="text-end" th:text="#{PRODUCTS.PRICE}">Price</th></tr></thead>
    <tbody>
      <tr th:each="product : ${products}">
        <td th:text="${product.name}">Keyboard</td>
        <td class="text-end" th:text="${@formats.money(product.price)}">€25.00</td>
      </tr>
    </tbody>
  </table>
  <p th:text="#{PRODUCTS.COUNT('n', ${#lists.size(products)})}">3 product(s) in the catalogue.</p>
</main>
</body>
</html>
  • linha 11: o valor, formatado de acordo com o idioma;
  • linha 15: um parâmetro numérico: [#lists.size] indica o tamanho da lista; [Translator] converte o valor em string ([String.valueOf]).

O arquivo [controllers/PagesController.java]:

package example22.controllers;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

// as ações não sabem nada sobre o idioma: elas fornecem dados,
// as views os traduzem e os formatam
@Controller
public class PagesController {

    public record Product(String name, BigDecimal price) {
    }

    @GetMapping("/")
    public String home(Model model) {
        model.addAttribute("name", "Marie");
        model.addAttribute("today", LocalDate.of(2026, 9, 23));
        return "pages/home";
    }

    @GetMapping("/products")
    public String products(Model model) {
        model.addAttribute("products", List.of(
                new Product("Keyboard", new BigDecimal("25")),
                new Product("Mouse", new BigDecimal("12.5")),
                new Product("Screen", new BigDecimal("1149"))));
        return "pages/products";
    }
}

As actions são independentes do idioma: fornecem os dados, enquanto as views os traduzem e formatam. O preço é um [BigDecimal], e o tipo [Java] para números decimais exatos é adequado para valores monetários (linha 16). A data da página inicial é uma data fixa, 23 de setembro de 2026 (linha 22), e não a data atual: assim, os resultados abaixo não dependem do dia em que o exemplo é executado.

5.1.6. Execução

Em inglês (ainda sem cookie), nas URLs http://localhost:5000/ e http://localhost:5000/products:

Image

Image

Um clique em um botão de idioma (aqui EN), simulado com [curl] (a opção [-H] adiciona o cabeçalho [Referer] que o navegador teria enviado):

curl -i -H "Referer: http://localhost:5000/products" http://localhost:5000/language/en
1
2
3
4
HTTP/1.1 302
Set-Cookie: language=en; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:23 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/products
Content-Length: 0

[CookieLocaleResolver] define o cookie [language], com o valor [en], com as características solicitadas ([Max-Age] e [Expires] especificam ambos o tempo de vida, para navegadores mais antigos e mais recentes, respectivamente). O redirecionamento volta para a página de origem ([Tomcat]; o servidor expandiu o caminho [/products] para um endereço completo). Um clique em FR funciona da mesma forma (cookie [language=fr]): as páginas agora estão em francês:

Image

Image

As datas e os valores acompanharam: “mercredi 23 septembre 2026”, “1 149,00 €”.

Um site malicioso que tentasse explorar nosso redirecionamento veria apenas uma página do nosso próprio site:

curl -i -H "Referer: https://pirate.example/trap?x=1" http://localhost:5000/language/fr
curl -i -H "Referer: https://pirate.example//pirate.example/trap" http://localhost:5000/language/fr
1
2
3
4
5
6
7
8
9
HTTP/1.1 302
Set-Cookie: language=fr; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:24 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/trap?x=1
Content-Length: 0

HTTP/1.1 302
Set-Cookie: language=fr; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:49:24 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/
Content-Length: 0

Um idioma não suportado:

curl -i http://localhost:5000/language/de
1
2
3
4
HTTP/1.1 404
Content-Type: application/json

{"timestamp":"2026-09-25T16:49:23.993Z","status":404,"error":"Not Found","message":"404 NOT_FOUND","path":"/language/de"}

A resposta de erro padrão do [Spring Boot]: JSON para o [curl], uma página HTML para um navegador. O Capítulo 7 mostra como substituí-la por nossa própria página.

Por fim, lembre-se de que um cookie é controlado pelo cliente. Um cookie [language=de] criado manualmente é aceito pelo [CookieLocaleResolver]: o texto permanece em inglês (o idioma padrão de [Translator]), mas a data é formatada em alemão:

curl -b "language=de" http://localhost:5000/
1
2
3
<html lang="de">
  <p>Hello Marie!</p>
  <p>Today is Mittwoch, 23. September 2026.</p>

(apenas três linhas da página são mostradas). Isso não tem grande importância: o usuário só está enganando a si mesmo.

O estudo de caso segue exatamente esse princípio, com dicionários mais completos ([i18n/fr.json] e [i18n/en.json]): o mesmo bean [messageSource], o mesmo [CookieLocaleResolver], o mesmo controller [/language/{language}]. A única diferença é que as mensagens de erro geradas pelas camadas de negócio e web também são chaves, traduzidas no último momento pela view.