Класс 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».
Практика по теме
Закрепите урок на задачах — у каждой есть уровень и оценка времени.
Все задачи модуля →Видео объяснение
Предпочитаете видеоформат? Посмотрите этот урок с примерами и объяснениями.
Комментарии