Skip to main content

Spring Boot i18n: Εκμάθηση ρύθμισης διεθνοποίησης

Ρυθμίστε το MessageSource, δημιουργήστε αρχεία ιδιοτήτων ανά γλώσσα, καθορίστε την ενεργή γλώσσα και αποδώστε πολύγλωσσα πρότυπα Thymeleaf — και, στη συνέχεια, αυτοματοποιήστε τις μεταφράσεις με AI.

1

Προσθήκη εξαρτήσεων

Το Spring Boot Starter Web περιλαμβάνει εξαρχής την αυτόματη ρύθμιση του MessageSource. Προσθέστε το Thymeleaf για πρότυπα i18n που αποδίδονται στον διακομιστή και το validation starter για τοπικά προσαρμοσμένα μηνύματα σφάλματος.

Το Spring Boot ρυθμίζει αυτόματα ένα bean MessageSource που διαβάζει από το messages.properties στο classpath. Χρειάζεστε ρητή ρύθμιση μόνο αν θέλετε να προσαρμόσετε το basename, την κωδικοποίηση ή τη συμπεριφορά προσωρινής αποθήκευσης.
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

Ρύθμιση MessageSource και LocaleResolver

Το MessageSource του Spring φορτώνει μεταφράσεις από αρχεία .properties χρησιμοποιώντας τη σύμβαση basename: messages.properties (προεπιλογή), messages_de.properties (Γερμανικά), messages_ja.properties (Ιαπωνικά). Ρυθμίστε ένα LocaleResolver για να καθορίσετε ποιο locale θα χρησιμοποιείται ανά αίτημα.

Αρχεία μετάφρασης

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.

Ρύθμιση 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;
    }
}
Αν οι μεταφράσεις επιστρέφουν το όνομα του κλειδιού αντί για το μεταφρασμένο κείμενο, η συνηθέστερη αιτία είναι ένα λανθασμένο basename. Η προεπιλογή είναι 'messages', η οποία αντιστοιχεί στο messages.properties του classpath. Αν τα αρχεία σας έχουν διαφορετικά ονόματα ή βρίσκονται σε υποκατάλογο, ορίστε ρητά το spring.messages.basename.

Επίλυση locale

Ρυθμίστε τον τρόπο με τον οποίο το Spring καθορίζει το ενεργό locale για κάθε αίτημα. Το CookieLocaleResolver διατηρεί την επιλογή του χρήστη μεταξύ συνεδριών. Το LocaleChangeInterceptor επιτρέπει στους χρήστες να αλλάζουν locale μέσω μιας παραμέτρου ερωτήματος, όπως ?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

Χρήση μεταφράσεων στον κώδικα

Αποκτήστε πρόσβαση σε μεταφρασμένα μηνύματα στους controllers μέσω εισαγωγής του MessageSource, στα πρότυπα Thymeleaf με τη σύνταξη #{...} και στα REST API χρησιμοποιώντας την παράμετρο Locale που επιλύεται αυτόματα.

Controller με 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";
    }
}

Πρότυπα Thymeleaf

Η έκφραση #{...} του Thymeleaf επιλύει αυτόματα τα κλειδιά μηνυμάτων από τα αρχεία .properties. Περάστε παραμέτρους με τη σύνταξη #{key(arg0, arg1)}. Το πρότυπο χρησιμοποιεί το locale που επιλύεται από το 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>
Εκφράσεις Thymeleaf όπως #{greeting('World')} περνούν ορίσματα στο MessageFormat. Το στατικό κείμενο μέσα στις ετικέτες HTML λειτουργεί ως εναλλακτικό περιεχόμενο κατά την προβολή του προτύπου χωρίς Spring — χρήσιμο για σχεδιαστές που εργάζονται απευθείας στα πρότυπα.

Τοπική προσαρμογή REST API

Για REST API, το Spring επιλύει αυτόματα το Locale από την κεφαλίδα Accept-Language. Εισαγάγετέ το ως παράμετρο μεθόδου και περάστε το στο MessageSource. Οι clients αλλάζουν γλώσσα στέλνοντας διαφορετικές κεφαλίδες Accept-Language.

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!"}
}
Τα REST API χρησιμοποιούν συνήθως AcceptHeaderLocaleResolver, που βασίζεται σε κεφαλίδες, ενώ οι εφαρμογές Web χρησιμοποιούν CookieLocaleResolver, που βασίζεται σε cookie. Αν παρέχετε και τα δύο από την ίδια εφαρμογή, εξετάστε το ενδεχόμενο ενός προσαρμοσμένου LocaleResolver που ελέγχει πρώτα τα cookie και, στη συνέχεια, χρησιμοποιεί εναλλακτικά την κεφαλίδα Accept-Language.

Μηνύματα Bean Validation

Το Spring επιλύει αυτόματα τα μηνύματα περιορισμών επικύρωσης από το MessageSource. Χρησιμοποιήστε σύμβολα κράτησης θέσης με άγκιστρα, όπως {validation.name.required}, στις επισημειώσεις περιορισμών σας και ορίστε τις μεταφράσεις στα αρχεία .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

Διαχείριση πληθυντικών και μεταβλητών

Το Spring χρησιμοποιεί το java.text.MessageFormat για παρεμβολή και πληθυντικούς. Το μοτίβο ChoiceFormat διαχειρίζεται βασικούς κανόνες πληθυντικού, αλλά για πλήρη υποστήριξη πληθυντικών ICU, όπως οι 6 τύποι των Αραβικών και οι 3 των Ρωσικών, προσθέστε τη βιβλιοθήκη 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 δεν είναι το ίδιο με τους κανόνες πληθυντικού ICU. Χρησιμοποιεί αριθμητικά εύρη (0#, 1#, 1<) αντί για κατηγορίες CLDR (zero, one, two, few, many, other). Για γλώσσες με σύνθετους κανόνες πληθυντικού, όπως τα Αραβικά, τα Πολωνικά ή τα Ρωσικά, το ChoiceFormat δεν επαρκεί — χρησιμοποιήστε το MessageFormat του ICU4J.

Αυτοματοποίηση μεταφράσεων

Αφού ολοκληρώσετε τη ρύθμιση i18n, μεταφράστε τα αρχεία .properties με AI. Στο IDE σας, ζητήστε από τον βοηθό AI να μεταφράσει το αρχείο προέλευσης ή χρησιμοποιήστε το CLI του i18n Agent στο pipeline 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
Μεταφράζετε σταδιακά — όταν προσθέτετε νέα κλειδιά στο messages.properties, μεταφράζετε μόνο τα νέα κλειδιά αντί να δημιουργείτε ξανά όλα τα αρχεία locale. Έτσι διατηρούνται οι υπάρχουσες μεταφράσεις που έχουν ελεγχθεί από ανθρώπους.

Αυτοματοποιήστε τον έλεγχο ποιότητας των μεταφράσεων

Εντοπίστε κλειδιά που λείπουν και λανθασμένα placeholders πριν φτάσουν στην παραγωγή με το i18n-validate. Δοκιμάστε τη διεπαφή χρήστη με ψευδομεταφράσεις μέσω του i18n-pseudo, πριν φτάσουν οι πραγματικές μεταφράσεις.

Ρύθμιση χωρίς παραμέτρους με το spring-locale-chain

Το spring-locale-chain είναι ένα starter ανοικτού κώδικα για το Spring Boot, το οποίο ρυθμίζει αυτόματα τα LocaleResolver και LocaleChangeInterceptor και την επικύρωση των υποστηριζόμενων locale με μία μόνο εξάρτηση. Ορίστε τα υποστηριζόμενα locale στο application.yml και η βιβλιοθήκη αναλαμβάνει τα υπόλοιπα.

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>

Προτεινόμενη δομή αρχείων

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

Συνηθισμένες παγίδες

Οι χαρακτήρες εκτός ASCII εμφανίζονται αλλοιωμένοι

Τα αρχεία .properties της Java χρησιμοποιούν από προεπιλογή κωδικοποίηση ISO-8859-1 και όχι UTF-8. Χαρακτήρες όπως τα umlaut (ü) ή οι χαρακτήρες CJK εμφανίζονται αλλοιωμένοι. Διόρθωση: ορίστε spring.messages.encoding=UTF-8 στο application.yml ή χρησιμοποιήστε διαφυγές Unicode, όπως \u00FC, στα αρχεία .properties. Το ReloadableResourceBundleMessageSource του Spring Boot χρησιμοποιεί από προεπιλογή UTF-8, αλλά το ResourceBundleMessageSource όχι.

Το ChoiceFormat αποτυγχάνει με μη αγγλικούς πληθυντικούς

Το ChoiceFormat της Java ({0,choice,0#|1#|1<}) υποστηρίζει μόνο αριθμητικά εύρη — δεν μπορεί να εκφράσει κατηγορίες πληθυντικού CLDR, όπως 'few' ή 'many'. Γλώσσες όπως τα Αραβικά (6 τύποι), τα Πολωνικά (3 τύποι) και τα Ρωσικά (3 τύποι) χρειάζονται το ICU4J για σωστό σχηματισμό πληθυντικού. Μην υποθέτετε ότι το ChoiceFormat διαχειρίζεται όλες τις γλώσσες.

Οι αλλαγές των μεταφράσεων δεν εμφανίζονται

Το ResourceBundleMessageSource αποθηκεύει από προεπιλογή τα bundle επ' αόριστον. Κατά την ανάπτυξη, χρησιμοποιήστε το ReloadableResourceBundleMessageSource με cacheSeconds=0 για να βλέπετε τις αλλαγές χωρίς επανεκκίνηση. Στην παραγωγή, ορίστε μια εύλογη διάρκεια προσωρινής αποθήκευσης, π.χ. 3600 δευτερόλεπτα, ώστε να εξισορροπείτε την απόδοση και την ταχύτητα ενημέρωσης.

Απροσδόκητη εναλλακτική επιλογή του locale της JVM

Από προεπιλογή, το Spring χρησιμοποιεί εναλλακτικά το προεπιλεγμένο locale της JVM (Locale.getDefault()) και όχι το αρχείο messages.properties. Ορίστε spring.messages.fallback-to-system-locale=false στο application.yml, ώστε να χρησιμοποιείται πάντα το προεπιλεγμένο bundle. Διαφορετικά, ένας διακομιστής του οποίου το locale JVM έχει οριστεί σε 'fr' θα εμφανίζει Γαλλικά αντί για Αγγλικά, όταν λείπει ένα κλειδί από το ζητούμενο locale.

Δοκιμάστε τώρα το i18n Agent

Αφήστε εδώ το αρχείο μετάφρασής σας

JSON, YAML, PO, XML, CSV, Markdown, Properties

ή κάντε κλικ για να επιλέξετε αρχείο

Γλώσσες-στόχοι

Δεν απαιτείται εγγραφήΆμεση εκτίμηση

Εναλλακτική επιλογή γλώσσας με το spring-locale-chain

Όταν λείπει ένα κλειδί μετάφρασης από μια περιφερειακή γλώσσα όπως το pt-BR, το Spring Boot μεταβαίνει απευθείας στην προεπιλεγμένη γλώσσα αντί να ελέγξει πρώτα τη γονική γλώσσα 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

Δείτε τον οδηγό μας για την εναλλακτική επιλογή γλώσσας, όπου θα βρείτε την πλήρη λίστα των υποστηριζόμενων πλαισίων και των 75 ενσωματωμένων αλυσίδων. Learn more →

Συχνές ερωτήσεις