Skip to main content

Spring Boot i18n: посібник із налаштування інтернаціоналізації

Налаштуйте MessageSource, створіть файли властивостей для різних локалей, визначте локалі та відтворюйте багатомовні шаблони Thymeleaf, а потім автоматизуйте переклад за допомогою ШІ.

1

Додати залежності

Spring Boot Starter Web містить готове автоматичне налаштування MessageSource. Додайте Thymeleaf для серверного відтворення шаблонів з i18n, а також стартер валідації для локалізованих повідомлень про помилки.

Spring Boot автоматично налаштовує бін MessageSource, який читає messages.properties із classpath. Явне налаштування потрібне лише для зміни базового імені, кодування або способу кешування.
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 за угодою щодо базового імені: messages.properties (за замовчуванням), messages_de.properties (німецька), messages_ja.properties (японська). Налаштуйте LocaleResolver, щоб визначати локаль для кожного запиту.

Файли перекладу

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;
    }
}
Якщо замість перекладеного тексту повертається назва ключа, найпоширеніша причина — неправильне базове ім’я. Значення за замовчуванням — 'messages', якому відповідає файл messages.properties у classpath. Якщо Ваші файли мають інші назви або містяться в підпапці, явно задайте spring.messages.basename.

Визначення локалі

Налаштуйте спосіб, у який Spring визначає активну локаль для кожного запиту. CookieLocaleResolver зберігає вибір користувача між сеансами. LocaleChangeInterceptor дає користувачам змогу перемикати локаль за допомогою параметра запиту на зразок ?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

Використати переклади в коді

Отримуйте перекладені повідомлення в контролерах через ін’єкцію MessageSource, у шаблонах Thymeleaf — за допомогою синтаксису #{...}, а в REST API — через автоматично визначений параметр Locale.

Контролер із 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)}. Шаблон використовує локаль, визначену Вашим 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. Клієнти перемикають мову, надсилаючи різні заголовки 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 на основі заголовків, а вебзастосунки — 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 — не те саме. ChoiceFormat використовує числові діапазони (0#, 1#, 1<), а не категорії CLDR (zero, one, two, few, many, other). Для мов зі складними правилами множини, як-от арабська, польська чи російська, ChoiceFormat недостатньо — натомість використовуйте MessageFormat з ICU4J.

Автоматизувати переклад

Завершивши налаштування i18n, перекладіть файли .properties за допомогою ШІ. У своїй IDE попросіть ШІ-помічника перекласти вихідний файл або використовуйте i18n Agent CLI у Вашому 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, перекладайте лише їх, а не створюйте всі файли локалей заново. Так Ви збережете переклади в наявних файлах, які вже перевірила людина.

Автоматизувати контроль якості перекладу

Виявляйте відсутні ключі та пошкоджені заповнювачі до випуску за допомогою i18n-validate. Тестуйте інтерфейс із псевдоперекладами за допомогою i18n-pseudo ще до появи справжніх перекладів.

spring-locale-chain: без додаткових налаштувань

spring-locale-chain — стартер Spring Boot з відкритим кодом, який автоматично налаштовує LocaleResolver, LocaleChangeInterceptor і перевірку підтримуваних локалей за допомогою однієї залежності. Визначте підтримувані локалі в 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 відображаються некоректно

Файли Java .properties за замовчуванням мають кодування ISO-8859-1, а не UTF-8. Через це символи на зразок умлаутів (ü) або символів 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 за замовчуванням кешує набори ресурсів безстроково. Під час розробки використовуйте ReloadableResourceBundleMessageSource з cacheSeconds=0, щоб бачити зміни без перезапуску. У виробничому середовищі задайте доцільну тривалість кешування (наприклад, 3600 секунд), щоб збалансувати продуктивність і швидкість оновлення.

Неочікуваний перехід до локалі JVM

За замовчуванням Spring переходить до стандартної локалі JVM (Locale.getDefault()), а не до Вашого файлу messages.properties. Задайте spring.messages.fallback-to-system-locale=false в application.yml, щоб завжди використовувати стандартний набір ресурсів. Інакше сервер із локаллю JVM, установленою як 'fr', показуватиме французький текст замість англійського, коли в запитаній локалі немає ключа.

Спробуйте 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 →

Поширені запитання