Spring Boot i18n: Εκμάθηση ρύθμισης διεθνοποίησης
Ρυθμίστε το MessageSource, δημιουργήστε αρχεία ιδιοτήτων ανά γλώσσα, καθορίστε την ενεργή γλώσσα και αποδώστε πολύγλωσσα πρότυπα Thymeleaf — και, στη συνέχεια, αυτοματοποιήστε τις μεταφράσεις με AI.
Προσθήκη εξαρτήσεων
Το Spring Boot Starter Web περιλαμβάνει εξαρχής την αυτόματη ρύθμιση του MessageSource. Προσθέστε το Thymeleaf για πρότυπα i18n που αποδίδονται στον διακομιστή και το validation starter για τοπικά προσαρμοσμένα μηνύματα σφάλματος.
<!-- 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>Ρύθμιση MessageSource και LocaleResolver
Το MessageSource του Spring φορτώνει μεταφράσεις από αρχεία .properties χρησιμοποιώντας τη σύμβαση basename: messages.properties (προεπιλογή), messages_de.properties (Γερμανικά), messages_ja.properties (Ιαπωνικά). Ρυθμίστε ένα LocaleResolver για να καθορίσετε ποιο locale θα χρησιμοποιείται ανά αίτημα.
Αρχεία μετάφρασης
# 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.Ρύθμιση 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;
}
}Επίλυση locale
Ρυθμίστε τον τρόπο με τον οποίο το Spring καθορίζει το ενεργό locale για κάθε αίτημα. Το CookieLocaleResolver διατηρεί την επιλογή του χρήστη μεταξύ συνεδριών. Το LocaleChangeInterceptor επιτρέπει στους χρήστες να αλλάζουν locale μέσω μιας παραμέτρου ερωτήματος, όπως ?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());
}
}Χρήση μεταφράσεων στον κώδικα
Αποκτήστε πρόσβαση σε μεταφρασμένα μηνύματα στους controllers μέσω εισαγωγής του MessageSource, στα πρότυπα Thymeleaf με τη σύνταξη #{...} και στα REST API χρησιμοποιώντας την παράμετρο Locale που επιλύεται αυτόματα.
Controller με 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";
}
}Πρότυπα Thymeleaf
Η έκφραση #{...} του Thymeleaf επιλύει αυτόματα τα κλειδιά μηνυμάτων από τα αρχεία .properties. Περάστε παραμέτρους με τη σύνταξη #{key(arg0, arg1)}. Το πρότυπο χρησιμοποιεί το locale που επιλύεται από το 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>Τοπική προσαρμογή REST API
Για REST API, το Spring επιλύει αυτόματα το Locale από την κεφαλίδα Accept-Language. Εισαγάγετέ το ως παράμετρο μεθόδου και περάστε το στο MessageSource. Οι clients αλλάζουν γλώσσα στέλνοντας διαφορετικές κεφαλίδες Accept-Language.
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!"}
}Μηνύματα Bean Validation
Το Spring επιλύει αυτόματα τα μηνύματα περιορισμών επικύρωσης από το MessageSource. Χρησιμοποιήστε σύμβολα κράτησης θέσης με άγκιστρα, όπως {validation.name.required}, στις επισημειώσεις περιορισμών σας και ορίστε τις μεταφράσεις στα αρχεία .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 einΔιαχείριση πληθυντικών και μεταβλητών
Το Spring χρησιμοποιεί το java.text.MessageFormat για παρεμβολή και πληθυντικούς. Το μοτίβο ChoiceFormat διαχειρίζεται βασικούς κανόνες πληθυντικού, αλλά για πλήρη υποστήριξη πληθυντικών ICU, όπως οι 6 τύποι των Αραβικών και οι 3 των Ρωσικών, προσθέστε τη βιβλιοθήκη 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}Αυτοματοποίηση μεταφράσεων
Αφού ολοκληρώσετε τη ρύθμιση i18n, μεταφράστε τα αρχεία .properties με AI. Στο IDE σας, ζητήστε από τον βοηθό AI να μεταφράσει το αρχείο προέλευσης ή χρησιμοποιήστε το CLI του i18n Agent στο pipeline 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,esΑυτοματοποιήστε τον έλεγχο ποιότητας των μεταφράσεων
Ρύθμιση χωρίς παραμέτρους με το spring-locale-chain
Το spring-locale-chain είναι ένα starter ανοικτού κώδικα για το Spring Boot, το οποίο ρυθμίζει αυτόματα τα LocaleResolver και LocaleChangeInterceptor και την επικύρωση των υποστηριζόμενων locale με μία μόνο εξάρτηση. Ορίστε τα υποστηριζόμενα locale στο application.yml και η βιβλιοθήκη αναλαμβάνει τα υπόλοιπα.
<!-- 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>Προτεινόμενη δομή αρχείων
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Συνηθισμένες παγίδες
Οι χαρακτήρες εκτός ASCII εμφανίζονται αλλοιωμένοι
Το ChoiceFormat αποτυγχάνει με μη αγγλικούς πληθυντικούς
Οι αλλαγές των μεταφράσεων δεν εμφανίζονται
Απροσδόκητη εναλλακτική επιλογή του locale της JVM
Δοκιμάστε τώρα το i18n Agent
Αφήστε εδώ το αρχείο μετάφρασής σας
JSON, YAML, PO, XML, CSV, Markdown, Properties
ή κάντε κλικ για να επιλέξετε αρχείο
Γλώσσες-στόχοι
Εναλλακτική επιλογή γλώσσας με το spring-locale-chain
Όταν λείπει ένα κλειδί μετάφρασης από μια περιφερειακή γλώσσα όπως το pt-BR, το Spring Boot μεταβαίνει απευθείας στην προεπιλεγμένη γλώσσα αντί να ελέγξει πρώτα τη γονική γλώσσα 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
- enΔείτε τον οδηγό μας για την εναλλακτική επιλογή γλώσσας, όπου θα βρείτε την πλήρη λίστα των υποστηριζόμενων πλαισίων και των 75 ενσωματωμένων αλυσίδων. Learn more →