Spring Boot i18n: tutorial de configuració de la internacionalització
Configuri MessageSource, creï fitxers de propietats específics per configuració regional, determini les configuracions regionals i renderitzi plantilles Thymeleaf multilingües; després, automatitzi les traduccions amb IA.
Afegir dependències
Spring Boot Starter Web inclou de sèrie la configuració automàtica de MessageSource. Afegeixi Thymeleaf per a les plantilles d’i18n renderitzades al servidor i el starter de validació per als missatges d’error localitzats.
<!-- pom.xml — Spring Boot Starter Web includes MessageSource auto-config -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Thymeleaf for server-side rendered templates with i18n -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<!-- Validation (for localized error messages) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>Configurar MessageSource i LocaleResolver
MessageSource de Spring carrega les traduccions des de fitxers .properties d'acord amb la convenció del nom base: messages.properties (predeterminat), messages_de.properties (alemany) i messages_ja.properties (japonès). Configuri un LocaleResolver per determinar quina configuració regional s'ha d'utilitzar per a cada sol·licitud.
Fitxers de traducció
# src/main/resources/messages.properties (default / English)
nav.home=Home
nav.about=About
nav.settings=Settings
greeting=Hello, {0}!
cart.itemCount={0,choice,0#No items|1#1 item|1<{0,number} items}
error.notFound=Page not found
error.serverError=Something went wrong. Please try again.Configuració de MessageSource
import org.springframework.context.MessageSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ReloadableResourceBundleMessageSource;
import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean;
@Configuration
public class I18nConfig {
@Bean
public MessageSource messageSource() {
ReloadableResourceBundleMessageSource source =
new ReloadableResourceBundleMessageSource();
source.setBasename("classpath:messages");
source.setDefaultEncoding("UTF-8");
source.setCacheSeconds(3600); // reload interval in dev
return source;
}
// Wire MessageSource into Bean Validation
@Bean
public LocalValidatorFactoryBean validator(MessageSource messageSource) {
LocalValidatorFactoryBean bean = new LocalValidatorFactoryBean();
bean.setValidationMessageSource(messageSource);
return bean;
}
}Determinació de la configuració regional
Configuri com determina Spring la configuració regional activa de cada sol·licitud. CookieLocaleResolver conserva la selecció de l'usuari entre sessions. LocaleChangeInterceptor permet als usuaris canviar de configuració regional mitjançant un paràmetre de consulta com ?lang=de.
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor;
import java.util.Locale;
@Configuration
public class LocaleConfig implements WebMvcConfigurer {
@Bean
public LocaleResolver localeResolver() {
CookieLocaleResolver resolver = new CookieLocaleResolver("lang");
resolver.setDefaultLocale(Locale.ENGLISH);
resolver.setCookieMaxAge(3600 * 24 * 365); // 1 year
return resolver;
}
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
interceptor.setParamName("lang"); // ?lang=de switches locale
return interceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(localeChangeInterceptor());
}
}Utilitzar traduccions al codi
Accedeixi als missatges traduïts als controladors mitjançant la injecció de MessageSource, a les plantilles Thymeleaf amb la sintaxi #{...} i a les API REST amb el paràmetre Locale determinat automàticament.
Controlador amb MessageSource
import org.springframework.context.MessageSource;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import java.util.Locale;
@Controller
public class HomeController {
private final MessageSource messageSource;
public HomeController(MessageSource messageSource) {
this.messageSource = messageSource;
}
@GetMapping("/")
public String home(Model model, Locale locale) {
// Spring injects the resolved Locale automatically
String greeting = messageSource.getMessage(
"greeting",
new Object[]{"World"},
locale
);
model.addAttribute("greeting", greeting);
return "home";
}
}Plantilles Thymeleaf
L'expressió #{...} de Thymeleaf resol automàticament les claus de missatge dels fitxers .properties. Passi els paràmetres amb la sintaxi #{key(arg0, arg1)}. La plantilla utilitza la configuració regional determinada per LocaleResolver.
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title th:text="#{nav.home}">Home</title>
</head>
<body>
<!-- Simple message lookup -->
<h1 th:text="#{greeting('World')}">Hello, World!</h1>
<!-- Navigation with i18n -->
<nav>
<a href="/" th:text="#{nav.home}">Home</a>
<a href="/about" th:text="#{nav.about}">About</a>
<a href="/settings" th:text="#{nav.settings}">Settings</a>
</nav>
<!-- Parameterized messages -->
<p th:text="#{cart.itemCount(3)}">3 items</p>
<!-- Language switcher -->
<div>
<a th:href="@{/(lang=en)}">English</a>
<a th:href="@{/(lang=de)}">Deutsch</a>
<a th:href="@{/(lang=ja)}">日本語</a>
</div>
<!-- Conditional text based on locale -->
<p th:if="${#locale.language == 'ja'}"
th:text="#{greeting('ユーザー')}">
こんにちは、ユーザーさん!
</p>
</body>
</html>Localització d'API REST
Per a les API REST, Spring determina automàticament Locale a partir de la capçalera Accept-Language. Injecti'l com a paràmetre del mètode i passi'l a MessageSource. Els clients canvien d'idioma enviant capçaleres Accept-Language diferents.
import org.springframework.context.MessageSource;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.Locale;
import java.util.Map;
@RestController
@RequestMapping("/api")
public class ApiController {
private final MessageSource messageSource;
public ApiController(MessageSource messageSource) {
this.messageSource = messageSource;
}
@GetMapping("/greeting/{name}")
public ResponseEntity<Map<String, String>> greeting(
@PathVariable String name,
Locale locale) { // Resolved from Accept-Language header
String msg = messageSource.getMessage(
"greeting", new Object[]{name}, locale
);
return ResponseEntity.ok(Map.of("message", msg));
}
// curl -H "Accept-Language: de" localhost:8080/api/greeting/Max
// → {"message": "Hallo, Max!"}
}Missatges de validació de beans
Spring resol automàticament els missatges de les restriccions de validació mitjançant MessageSource. Utilitzi marcadors de posició entre claus, com {validation.name.required}, a les anotacions de restricció i defineixi les traduccions als fitxers .properties.
import jakarta.validation.constraints.*;
public class CreateUserRequest {
@NotBlank(message = "{validation.name.required}")
@Size(min = 2, max = 50, message = "{validation.name.size}")
private String name;
@Email(message = "{validation.email.invalid}")
private String email;
}
// In messages.properties:
// validation.name.required=Name is required
// validation.name.size=Name must be between {min} and {max} characters
// validation.email.invalid=Please enter a valid email address
//
// In messages_de.properties:
// validation.name.required=Name ist erforderlich
// validation.name.size=Name muss zwischen {min} und {max} Zeichen lang sein
// validation.email.invalid=Bitte geben Sie eine gültige E-Mail-Adresse einGestionar plurals i variables
Spring utilitza java.text.MessageFormat per a la interpolació i els plurals. El patró ChoiceFormat gestiona regles de plural bàsiques, però, per disposar de compatibilitat completa amb els plurals d’ICU, com les 6 formes de l’àrab o les 3 del rus, cal afegir la biblioteca ICU4J.
# MessageFormat plural syntax in messages.properties
# Uses java.text.ChoiceFormat — NOT ICU plural rules
cart.itemCount={0,choice,0#No items|1#1 item|1<{0,number} items}
# For more complex plurals, use ICU4J:
# 1. Add dependency: com.ibm.icu:icu4j
# 2. Use ICUMessageSource instead of ResourceBundleMessageSource
#
# Then you can write ICU-style plurals:
# cart.items={count, plural, one {# item} other {# items}}
# Variables with MessageFormat:
welcome.message=Welcome, {0}! You have {1,number} new {1,choice,1#notification|1<notifications}.
order.total=Order total: {0,number,currency}
event.date=Event date: {0,date,long}Automatitzar les traduccions
Un cop completada la configuració d’i18n, tradueixi els fitxers .properties mitjançant IA. Des de l’IDE, demani a l’assistent d’IA que tradueixi el fitxer d’origen o utilitzi la CLI d’i18n Agent a la canalització de CI/CD.
# Translate your .properties files with AI
# In your IDE, ask your AI assistant:
> Translate src/main/resources/messages.properties to German, Japanese, and Spanish
✓ messages_de.properties created (1.2s)
✓ messages_ja.properties created (1.5s)
✓ messages_es.properties created (1.1s)
# Or use the CLI in CI/CD:
npx i18n-agent translate src/main/resources/messages.properties --lang de,ja,esAutomatitzar la qualitat de les traduccions
Configuració automàtica amb spring-locale-chain
spring-locale-chain és un starter de Spring Boot de codi obert que configura automàticament LocaleResolver, LocaleChangeInterceptor i la validació de les configuracions regionals admeses mitjançant una sola dependència. Defineixi les configuracions regionals admeses a application.yml i la biblioteca s'encarregarà de la resta.
<!-- Add spring-locale-chain for zero-config locale resolution -->
<dependency>
<groupId>io.github.i18n-agent</groupId>
<artifactId>spring-locale-chain</artifactId>
<version>1.0.0</version>
</dependency>Estructura de fitxers recomanada
my-spring-app/
├── src/main/
│ ├── java/com/example/
│ │ ├── config/
│ │ │ ├── I18nConfig.java # MessageSource bean
│ │ │ └── LocaleConfig.java # LocaleResolver + interceptor
│ │ ├── controller/
│ │ │ └── HomeController.java # Uses MessageSource
│ │ └── MyApplication.java
│ └── resources/
│ ├── messages.properties # Default (English)
│ ├── messages_de.properties # German
│ ├── messages_ja.properties # Japanese
│ ├── messages_es.properties # Spanish
│ ├── application.yml # Spring config
│ └── templates/
│ └── home.html # Thymeleaf with #{...}
├── pom.xml
└── build.gradleErrors habituals
Els caràcters no ASCII es mostren de manera il·legible
ChoiceFormat falla amb els plurals no anglesos
Els canvis de traducció no es reflecteixen
Retorn inesperat a la configuració regional de la JVM
Provar i18n Agent ara
Arrossegar aquí el fitxer de traducció
JSON, YAML, PO, XML, CSV, Markdown, Properties
o fer clic per explorar
Idiomes de destinació
Configuració regional de reserva amb spring-locale-chain
Quan falta una clau de traducció en una configuració regional com pt-BR, Spring Boot passa directament a la configuració regional predeterminada en comptes de comprovar primer la configuració regional pare (pt).
<!-- Maven -->
<dependency>
<groupId>ai.i18nagent</groupId>
<artifactId>spring-locale-chain</artifactId>
</dependency># application.yml
locale-chain:
fallbacks:
pt-BR:
- pt
- en
zh-Hant-HK:
- zh-Hant
- zh
- enConsulti la nostra guia de configuracions regionals de reserva per veure la llista completa d’entorns de treball admesos i les 75 cadenes integrades. Learn more →