Skip to main content

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.

1

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.

Spring Boot configura automàticament un bean MessageSource que llegeix messages.properties des del classpath. Només cal configurar-lo explícitament si es vol personalitzar el nom base, la codificació o el comportament de la memòria cau.
pom.xml
<!-- 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>
2

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ó

messages.properties
# 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

I18nConfig.java
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;
    }
}
Si les traduccions retornen el nom de la clau en comptes del text traduït, la causa més habitual és un nom base incorrecte. El nom predeterminat és 'messages', que correspon a messages.properties al classpath. Si els fitxers tenen un altre nom o són en un subdirectori, estableixi spring.messages.basename explícitament.

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.

LocaleConfig.java
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());
    }
}
3

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

HomeController.java
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.

home.html
<!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>
Les expressions de Thymeleaf com #{greeting('World')} passen arguments a MessageFormat. El text estàtic inclòs dins de les etiquetes HTML serveix com a alternativa quan es visualitza la plantilla sense Spring, una opció útil per als dissenyadors que treballen directament amb les plantilles.

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.

ApiController.java
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!"}
}
Les API REST solen utilitzar AcceptHeaderLocaleResolver, basat en capçaleres, mentre que les aplicacions web utilitzen CookieLocaleResolver, basat en galetes. Si tots dos tipus se serveixen des de la mateixa aplicació, consideri crear un LocaleResolver personalitzat que comprovi primer les galetes i, si no hi ha cap coincidència, recorri a la capçalera Accept-Language.

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.

Bean Validation i18n
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 ein
4

Gestionar 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 Plurals
# 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}
ChoiceFormat no equival a les regles de plural d’ICU. Utilitza intervals numèrics (0#, 1#, 1<) en comptes de categories CLDR (zero, one, two, few, many, other). ChoiceFormat és insuficient per a idiomes amb regles de plural complexes, com l’àrab, el polonès o el rus; utilitzi MessageFormat d’ICU4J.

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.

Terminal
# 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,es
Tradueixi de manera incremental: quan afegeixi claus noves a messages.properties, tradueixi només aquestes claus en comptes de tornar a generar tots els fitxers de configuració regional. Així es conserven les traduccions existents que s’hagin revisat manualment.

Automatitzar la qualitat de les traduccions

Detecti amb i18n-validate les claus que falten i els marcadors de posició malmesos abans del desplegament. Provi la interfície amb pseudotraduccions mitjançant i18n-pseudo abans que arribin les traduccions reals.

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.

pom.xml
<!-- 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

Project Structure
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.gradle

Errors habituals

Els caràcters no ASCII es mostren de manera il·legible

Els fitxers .properties de Java utilitzen per defecte la codificació ISO-8859-1, no UTF-8. Els caràcters com les dièresis (ü) o els caràcters CJK es mostren de manera il·legible. Solució: estableixi spring.messages.encoding=UTF-8 a application.yml o utilitzi seqüències d'escapament Unicode com \u00FC als fitxers .properties. ReloadableResourceBundleMessageSource de Spring Boot utilitza UTF-8 per defecte, però ResourceBundleMessageSource no.

ChoiceFormat falla amb els plurals no anglesos

ChoiceFormat de Java ({0,choice,0#|1#|1<}) només admet intervals numèrics; no pot expressar categories de plural CLDR com 'few' o 'many'. Idiomes com l'àrab (6 formes), el polonès (3 formes) i el rus (3 formes) necessiten ICU4J per formar correctament els plurals. No pressuposi que ChoiceFormat gestiona tots els idiomes.

Els canvis de traducció no es reflecteixen

ResourceBundleMessageSource conserva els paquets a la memòria cau indefinidament per defecte. Durant el desenvolupament, utilitzi ReloadableResourceBundleMessageSource amb cacheSeconds=0 per veure els canvis sense haver de reiniciar. En producció, estableixi una durada raonable per a la memòria cau, per exemple 3600 segons, per equilibrar el rendiment i la velocitat d'actualització.

Retorn inesperat a la configuració regional de la JVM

Per defecte, Spring recorre a la configuració regional predeterminada de la JVM (Locale.getDefault()), no al fitxer messages.properties. Estableixi spring.messages.fallback-to-system-locale=false a application.yml perquè sempre s'utilitzi el paquet predeterminat. En cas contrari, un servidor amb la configuració regional de la JVM establerta en 'fr' mostrarà el contingut en francès en comptes d'anglès quan falti una clau a la configuració regional sol·licitada.

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ó

No cal registrePressupost instantani

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

Terminal
<!-- Maven -->
<dependency>
  <groupId>ai.i18nagent</groupId>
  <artifactId>spring-locale-chain</artifactId>
</dependency>
Configuration
# application.yml
locale-chain:
  fallbacks:
    pt-BR:
      - pt
      - en
    zh-Hant-HK:
      - zh-Hant
      - zh
      - en

Consulti 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 →

Preguntes freqüents