Интернационализация (i18n) и локализация (l10n) в Java

Программа, написанная на компьютере с английскими настройками, отправляется к пользователю в России, и String.format("%.2f", 1234.5) вдруг возвращает "1234,50" вместо "1234.50". Следующий вызов Double.parseDouble на этой строке падает с NumberFormatException. Чтобы таких сюрпризов не было, приложение нужно заранее подготовить к разным языкам и регионам. Этим и занимаются интернационализация и локализация.

Интернационализация (i18n) — это проектирование приложения так, чтобы для добавления нового языка не нужно было перекомпилировать и пересобирать всё приложение. Для этого тексты интерфейса хранят отдельно от кода, в файлах свойств, которые приложение загружает во время работы. Форматы чисел, дат и валют берут из текущей локали, а не прописывают в коде.

Локализация (l10n) — это адаптация приложения к конкретному языку и региону: перевод текстов интерфейса и документации, а также настройка форматов даты и времени, валют, чисел и других региональных особенностей.

Презентация с видео на Patreon →

Что такое i18n и l10n: расшифровка

i18n — это сокращение английского слова internationalization (интернационализация): первая буква i, последняя n и 18 букв между ними. l10n так же сокращает слово localization (локализация): l, 10 букв, n. Такие сокращения называют нумеронимами. Программисты придумали их, чтобы не писать длинные слова целиком.

В Java обе задачи решает один и тот же набор классов, а связывает их локаль — объект java.util.Locale, то есть пара «язык + регион», например ru-RU или en-US.

i18n и l10n: в чём разница

Интернационализация (i18n) делается один раз, при разработке: программист готовит код так, чтобы его можно было перевести. Локализация (l10n) делается для каждого языка отдельно: переводчик или разработчик добавляет переводы и региональные настройки, не трогая код. Без i18n локализация превращается в переписывание программы.

Что меняется от локали к локали

От локали зависит не только язык интерфейса. Меняются разделители в числах, порядок частей даты, названия месяцев, символ и место валюты, первый день недели и порядок сортировки строк. Ниже показано, как одни и те же данные выглядят в трёх локалях при стандартных форматтерах Java 11+.

Инструменты Java для i18n

В стандартной библиотеке Java для интернационализации есть всё необходимое, сторонние библиотеки не нужны. Основу составляют Locale (какой язык и регион) и ResourceBundle (где лежат переводы). Остальные классы форматируют числа, даты и сообщения по правилам выбранной локали.

Фреймворки строятся на тех же идеях. Например, MessageSource в Spring Boot читает те же messages_xx.properties и выбирает язык по заголовку Accept-Language запроса.

Как сделать приложение интернационализированным: 4 шага

Интернационализация Java-приложения сводится к четырём шагам. Все строки интерфейса выносятся из кода в properties-файлы. Локаль пользователя задаётся явно. Переводы загружаются через ResourceBundle. Числа и даты выводятся только через форматтеры с этой локалью.

1. Вынести тексты. Вместо System.out.println("Добро пожаловать!") — ключ message.welcome в файлах messages.properties, messages_ru_RU.properties и т.д. Формат файлов и правила их именования описаны в уроке о ResourceBundle.
2. Определить локаль. Взять её из настроек пользователя, заголовка HTTP-запроса или Locale.getDefault(). Способы создать локаль описаны в уроке о Locale.
3. Загрузить переводы. ResourceBundle.getBundle("messages", locale) сам найдёт подходящий файл. Если файла для этой локали нет, он возьмёт более общий.
4. Форматировать с локалью. Числа, валюты и даты выводить через NumberFormat, DateTimeFormatter, MessageFormat с той же локалью, а не склеивать строки вручную.

Пример локализации даты (java localization example): одна и та же LocalDate выводится в трёх локалях, при этом код не меняется.

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.Locale;

public class LocalizedDateExample {
    public static void main(String[] args) {
        LocalDate date = LocalDate.of(2026, 3, 8);
        Locale[] locales = {Locale.US, Locale.GERMANY, Locale.forLanguageTag("ru-RU")};

        for (Locale locale : locales) {
            DateTimeFormatter formatter = DateTimeFormatter
                    .ofLocalizedDate(FormatStyle.LONG)
                    .withLocale(locale);
            System.out.println(locale.toLanguageTag() + ": " + date.format(formatter));
        }
    }
}
// Вывод (Java 11+):
// en-US: March 8, 2026
// de-DE: 8. März 2026
// ru-RU: 8 марта 2026 г.

Чтобы добавить, например, французский, достаточно поставить в массив Locale.FRANCE. Ни строки формата, ни названия месяцев в коде не появляются: их берёт JDK. Это и есть результат интернационализации.

Где локаль по умолчанию ломает код

Если локаль не указана явно, многие методы Java берут Locale.getDefault(), то есть настройки операционной системы или JVM. Поэтому один и тот же код по-разному работает на машине разработчика и на сервере. Внутренние данные (ключи, идентификаторы, форматы файлов) нужно обрабатывать с Locale.ROOT, а локаль пользователя применять только к тексту, который он увидит.

Ошибка 1: число, которое не читается обратно. Это пример из начала урока.

Locale.setDefault(Locale.forLanguageTag("ru-RU"));

String s = String.format("%.2f", 1234.5);
System.out.println(s);                       // Вывод: 1234,50
double d = Double.parseDouble(s);            // NumberFormatException: For input string: "1234,50"

// Исправление: для машинного формата явно указать Locale.ROOT
String fixed = String.format(Locale.ROOT, "%.2f", 1234.5);
System.out.println(fixed);                   // Вывод: 1234.50
System.out.println(Double.parseDouble(fixed)); // Вывод: 1234.5

Ошибка 2: что выведет этот код?

Locale tr = Locale.forLanguageTag("tr-TR");

System.out.println("title".toUpperCase(tr));          // Вывод: TİTLE
System.out.println("TITLE".toLowerCase(tr));          // Вывод: tıtle
System.out.println("title".toUpperCase(Locale.ROOT)); // Вывод: TITLE

В турецком языке у буквы i заглавная пара с точкой (İ), а у I строчная пара без точки (ı). Если приложение запущено с турецкой локалью по умолчанию, то "title".toUpperCase() без аргументов вернёт "TİTLE". Тогда сравнение equals("TITLE"), поиск по ключу в Map или разбор команды тихо перестанут работать. Для ключей, имён enum и протоколов используйте toUpperCase(Locale.ROOT) или equalsIgnoreCase.