Локализация ·
‹ Предыдущий Следующий ›
⏱ 5 минут чтения Обновлено: 2026-10-16

Класс Locale в Java: что такое локаль и как её задать

Строка "ru_RU" выглядит как нормальный код локали, но Locale.forLanguageTag("ru_RU") вернёт пустую локаль: toString() даст "", getDisplayLanguage() — тоже пустую строку. Исключения нет, и приложение молча переключится на базовые ресурсы. Почему так происходит и как создавать локаль правильно, разберём в этом уроке.

Локаль — это набор региональных настроек: язык, страна (регион) и при необходимости письменность и вариант. В Java локаль представляет класс java.util.Locale. Он позволяет учесть особенности региональных представлений алфавита, символов, чисел и дат. При старте JVM берёт локаль из настроек операционной системы, но её можно изменить или передать нужную локаль в конкретный метод.

Сам Locale ничего не форматирует. Это «ярлык» языка и региона, который передают в NumberFormat, DateTimeFormatter, ResourceBundle и другие классы. Зачем всё это нужно приложению, описано в уроке об интернационализации и локализации.

Как создать Locale: 5 способов

В современной Java локаль создают фабричным методом Locale.of("ru", "RU") (Java 19+) или из тега BCP 47 через Locale.forLanguageTag("ru-RU"). Для нескольких стран есть готовые константы, например Locale.US. Конструктор new Locale(...) с Java 19 помечен устаревшим (deprecated).

Способ Пример С какой версии Что будет при некорректном вводе
Константа Locale.FRANCE Java 1.1 Ошибиться нельзя, но констант мало
Locale.of(language, country) Locale.of("ru", "RU") Java 19 Аргументы не проверяются: Locale.of("ru_RU") даст язык "ru_ru" без страны
Locale.forLanguageTag(tag) Locale.forLanguageTag("ru-RU") Java 7 Некорректный подтег и всё после него молча отбрасываются: "ru_RU" → пустая локаль
Locale.Builder new Locale.Builder().setLanguage("ru").setRegion("RU").build() Java 7 Бросает IllformedLocaleException
Конструктор (устарел) new Locale("ru", "RU") Deprecated с Java 19 Не проверяет аргументы, как Locale.of

Все три современных способа дают одну и ту же локаль:

import java.util.Locale;

public class CreateLocale {
    public static void main(String[] args) {
        Locale a = Locale.of("ru", "RU");
        Locale b = Locale.forLanguageTag("ru-RU");
        Locale c = new Locale.Builder().setLanguage("ru").setRegion("RU").build();

        System.out.println(a + " " + b + " " + c);
        System.out.println(a.equals(b) && b.equals(c));
    }
}
// Вывод:
// ru_RU ru_RU ru_RU
// true

Код языка пишется строчными буквами по ISO 639 (ru, en, uk), код страны — заглавными по ISO 3166 (RU, US, UA). Если проект работает на Java 8–18, где Locale.of ещё нет, используйте Locale.forLanguageTag: он есть начиная с Java 7 и в новых версиях не устарел.

Константы Locale.US, Locale.FRANCE и другие

Класс Locale содержит готовые константы для нескольких стран (язык + страна) и языков (только язык). Константы для России и русского языка нет: русскую локаль создают через Locale.of("ru", "RU") или Locale.forLanguageTag("ru-RU").

Константа Значение (toString) Что задаёт
Locale.US en_US Английский язык, США
Locale.UK en_GB Английский язык, Великобритания
Locale.CANADA / Locale.CANADA_FRENCH en_CA / fr_CA Канада: английский / французский
Locale.FRANCE, Locale.GERMANY, Locale.ITALY fr_FR, de_DE, it_IT Франция, Германия, Италия
Locale.JAPAN, Locale.KOREA, Locale.CHINA (= PRC), Locale.TAIWAN ja_JP, ko_KR, zh_CN, zh_TW Япония, Корея, Китай, Тайвань
Locale.ENGLISH, Locale.FRENCH, Locale.GERMAN, Locale.ITALIAN, Locale.JAPANESE, Locale.KOREAN, Locale.CHINESE en, fr, de, it, ja, ko, zh Только язык, страна не задана
Locale.ROOT "" Нейтральная локаль, см. следующий раздел

Разница между Locale.US и Locale.ENGLISH заметна, например, при форматировании валюты: у en_US есть страна, а значит, и валюта (доллар), у en страны нет.

Locale.UK — не Украина

Locale.UK означает United Kingdom, то есть en_GB. Украинский язык имеет код uk, а страна Украина — UA, поэтому украинская локаль создаётся как Locale.of("uk", "UA"). Константы для неё в классе нет.

Locale.ROOT: локаль без языка и страны

Locale.ROOT — это константа нейтральной локали, у которой язык и страна равны пустой строке "". Она является базовой для всех остальных локалей и используется там, где результат не должен зависеть от языка и региона: ключи, идентификаторы, форматы файлов и протоколов.

System.out.println("[" + Locale.ROOT + "]");          // Вывод: []
System.out.println(Locale.ROOT.toLanguageTag());      // Вывод: und
System.out.println("[" + Locale.ROOT.getDisplayName() + "]"); // Вывод: []
System.out.println(Locale.ROOT.equals(Locale.of(""))); // Вывод: true

und — это тег BCP 47 для «неопределённого языка» (undetermined). Где применяется Locale.ROOT:

  • Операции, не зависящие от локали: toUpperCase(Locale.ROOT), String.format(Locale.ROOT, ...). Без явной локали эти методы берут локаль по умолчанию, и результат на сервере может отличаться от результата на машине разработчика. Разбор таких ошибок с примерами — в уроке об интернационализации.
  • Базовые ресурсы: файл text.properties без суффикса соответствует Locale.ROOT. Его ResourceBundle берёт последним, когда для нужной локали ничего не нашлось (подробнее — в уроке о ResourceBundle).

Локаль по умолчанию: getDefault и setDefault

Текущую локаль JVM возвращает Locale.getDefault(), а изменить её можно вызовом Locale.setDefault(Locale) или параметрами запуска -Duser.language и -Duser.country. Локаль по умолчанию определяется один раз при старте JVM по настройкам операционной системы.

Locale current = Locale.getDefault();   // например, ru_RU на русской Windows
Locale.setDefault(Locale.CANADA);       // теперь en_CA для всей JVM

Задать локаль без изменения кода можно при запуске:

java -Duser.language=ru -Duser.country=RU Main

С Java 7 у локали по умолчанию есть две категории (Locale.Category). DISPLAY отвечает за язык, на котором выводятся названия (getDisplayCountry() и т.п.), FORMAT — за формат чисел, дат и валют. Вызов setDefault(Locale) меняет обе категории сразу, а setDefault(Category, Locale) — только одну, и общую getDefault() он не трогает:

import java.util.Locale;

public class DefaultLocaleCategories {
    public static void main(String[] args) {
        Locale start = Locale.getDefault();
        Locale.setDefault(Locale.Category.FORMAT, Locale.GERMANY);
        Locale.setDefault(Locale.Category.DISPLAY, Locale.ENGLISH);

        System.out.println(Locale.getDefault().equals(start)); // общая локаль не изменилась
        System.out.println(String.format("%,.2f", 1234.5));    // формат берётся из FORMAT
        System.out.println(Locale.FRANCE.getDisplayCountry()); // название берётся из DISPLAY
    }
}
// Вывод:
// true
// 1.234,50
// France

Вызов Locale.setDefault(null) бросает NullPointerException.

setDefault действует на всю JVM

Locale.setDefault меняет локаль для текущего экземпляра JVM, а не для потока или пользователя. На сервере, где одновременно обслуживаются пользователи с разными языками, локаль по умолчанию не меняют: локаль запроса передают в форматтеры явно (в Spring её хранит LocaleContextHolder).

Методы класса Locale и пример

Методы Locale делятся на две группы. Коды (getLanguage(), getCountry()) возвращают то, что хранится в объекте. Названия (getDisplayLanguage(), getDisplayCountry()) переводятся на язык локали DISPLAY по умолчанию или на язык локали, переданной аргументом.

Метод Что возвращает Для Locale.of("ru", "RU")
getLanguage() Код языка ISO 639 ru
getCountry() Код страны ISO 3166 или "" RU
getDisplayLanguage(Locale) Название языка на языке аргумента русский (аргумент ru), Russian (аргумент Locale.ENGLISH)
getDisplayCountry(Locale) Название страны на языке аргумента Россия / Russia
getDisplayName(Locale) Язык и страна одной строкой русский (Россия) / Russian (Russia)
toString() Код через подчёркивание ru_RU
toLanguageTag() Тег BCP 47 через дефис ru-RU
getISO3Language() / getISO3Country() Трёхбуквенные коды rus / RUS

Рассмотрим пример использования класса Locale. Локаль по умолчанию заменяется на Locale.CANADA, поэтому названия выводятся по-английски:

import java.util.Locale;

public class LocaleExample1 {
    public static void main(String[] args) {
        Locale fr = Locale.FRANCE;
        Locale us = Locale.US;
        Locale uk = Locale.of("uk", "UA");

        Locale.setDefault(Locale.CANADA);
        Locale current = Locale.getDefault();
        getLocaleInfo(current);

        getLocaleInfo(fr);
        getLocaleInfo(us);
        getLocaleInfo(uk);
    }

    private static void getLocaleInfo(Locale locale) {
        System.out.println("Код региона: " + locale.getCountry());
        System.out.println("Название региона: " + locale.getDisplayCountry());
        System.out.println("Код языка региона: " + locale.getLanguage());
        System.out.println("Название языка региона: "
                + locale.getDisplayLanguage());
        System.out.println();
    }
}

Вывод (Java 11+):

Код региона: CA
Название региона: Canada
Код языка региона: en
Название языка региона: English

Код региона: FR
Название региона: France
Код языка региона: fr
Название языка региона: French

Код региона: US
Название региона: United States
Код языка региона: en
Название языка региона: English

Код региона: UA
Название региона: Ukraine
Код языка региона: uk
Название языка региона: Ukrainian

Чтобы получить названия на русском независимо от локали по умолчанию, передайте локаль аргументом:

Locale ru = Locale.of("ru", "RU");

System.out.println(ru.getDisplayName(ru));               // Вывод: русский (Россия)
System.out.println(Locale.FRANCE.getDisplayCountry(ru)); // Вывод: Франция
System.out.println(Locale.FRANCE.getDisplayLanguage(ru)); // Вывод: французский
System.out.println(ru.toLanguageTag());                  // Вывод: ru-RU
System.out.println(ru.getISO3Country());                 // Вывод: RUS

На чём чаще всего ошибаются с Locale

Большинство ошибок с Locale не приводит к исключению: неправильная локаль создаётся молча, и проблема всплывает позже, когда текст или формат оказываются не теми. Главное правило — toString() выдаёт ru_RU с подчёркиванием, а forLanguageTag ждёт ru-RU с дефисом.

Ошибка 1: подчёркивание в forLanguageTag. Это пример из начала урока.

Locale bad = Locale.forLanguageTag("ru_RU");
System.out.println("[" + bad + "]");                   // Вывод: []
System.out.println(bad.equals(Locale.ROOT));           // Вывод: true

// Исправление: заменить подчёркивание на дефис
Locale good = Locale.forLanguageTag("ru_RU".replace('_', '-'));
System.out.println(good);                              // Вывод: ru_RU

Ошибка 2: Locale.of не проверяет аргументы. Строка целиком становится кодом языка:

Locale wrong = Locale.of("ru_RU");
System.out.println(wrong.getLanguage());     // Вывод: ru_ru
System.out.println("[" + wrong.getCountry() + "]"); // Вывод: []

Если код локали приходит извне (из настроек, базы данных, HTTP-запроса), используйте Locale.Builder: он проверяет значения и бросает IllformedLocaleException, например на new Locale.Builder().setLanguage("ru_RU").

Ошибка 3: setDefault как способ «перевести» один экран. Вызов Locale.setDefault внутри обработчика запроса меняет локаль всем потокам JVM. Передавайте локаль явно: NumberFormat.getInstance(locale), ResourceBundle.getBundle("text", locale).

Часто задаваемые вопросы

Что выбрать для машинного формата: Locale.ROOT или Locale.US?

Оба дают точку в качестве десятичного разделителя, поэтому в старом коде часто встречается Locale.US. Но Locale.US — это настройки реальных пользователей американского английского, а Locale.ROOT специально предназначен для операций, не зависящих от языка. Для ключей, логов, CSV и протоколов выбирайте Locale.ROOT: так и читателю кода понятно, что результат не для показа человеку.

Почему в Locale нет константы для России?

Константы появились ещё в Java 1.1 только для небольшого набора стран и языков, и с тех пор список не расширяли. Для остальных локалей используют Locale.of("ru", "RU") или Locale.forLanguageTag("ru-RU"). Если русская локаль нужна во многих местах, объявите свою константу: static final Locale RU = Locale.of("ru", "RU");. Полный список встроенных констант — в разделе «Константы Locale.US, Locale.FRANCE и другие».

Как узнать, какие локали поддерживает JVM?

Locale.getAvailableLocales() возвращает массив всех установленных локалей, а с Java 21 есть Locale.availableLocales(), который возвращает Stream<Locale>. У форматтеров свой список, например NumberFormat.getAvailableLocales(). Локаль, которой нет в списке, создать всё равно можно: форматтеры возьмут данные более общей локали.

Как получить Locale из строки вида "ru_RU"?

Замените подчёркивание на дефис и передайте строку в Locale.forLanguageTag(s.replace('_', '-')). Обратное преобразование — locale.toLanguageTag(). Почему без замены получается пустая локаль, показано в разделе «На чём чаще всего ошибаются с Locale».

Практика по теме

Закрепите урок на задачах — у каждой есть уровень и оценка времени.

Все задачи модуля →

Видео объяснение

Предпочитаете видеоформат? Посмотрите этот урок с примерами и объяснениями.

Комментарии

Зарегистрируйтесь или войдите, чтобы иметь возможность оставить комментарий.