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:


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
|
| 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:


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
|
| 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
|
| 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/
|
| <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.