Класс Locale

java.lang.Object

java.util.Locale

Все реализуемые интерфейсы:: Serializable, Cloneable

public final class Locale extends Object implements Cloneable, Serializable

Locale представляет определённый географический, политический или культурный регион. API, которому для выполнения задачи требуется Locale, является зависимым от локали и использует Locale для адаптации информации для пользователя. Такие зависимые от локали API главным образом находятся в пакетах java.text и java.util. Например, отображение числа — это зависимая от локали операция: число следует форматировать в соответствии с обычаями и правилами, принятыми в родной стране, регионе или культуре пользователя.

Класс Locale реализует стандарт IETF BCP 47, состоящий из RFC 4647 «Сопоставление языковых тегов» и RFC 5646 «Теги для идентификации языков», а также поддерживает совместимые с BCP 47 расширения LDML (UTS#35, «Язык разметки данных локали Unicode») для обмена данными локалей. Каждому Locale соответствуют данные локали, предоставляемые средой выполнения Java или любыми развёрнутыми реализациями LocaleServiceProvider. Данные локали, предоставляемые средой выполнения Java, могут различаться в разных выпусках.

Состав локали

Locale состоит из перечисленных ниже полей, выделенных полужирным шрифтом; обратите внимание, что Locale не обязательно содержит все эти поля. Например, Locale.ENGLISH состоит только из поля языка. В отличие от него, Locale, например возвращаемая Locale.forLanguageTag("en-Latn-US-POSIX-u-nu-latn"), будет содержать все перечисленные ниже поля. Эта конкретная Locale будет представлять английский язык в США с использованием латинской письменности и числовых обозначений для применения в средах POSIX.

Locale реализует стандарт IETF BCP 47; на любые отклонения следует обращать внимание по комментариям с префиксом «Отклонение от BCP 47:». Стандарт RFC 5646 объединяет подкатегории из различных стандартов ISO (639, 3166, 15924), которые также входят в состав Locale. Кроме того, полный список допустимых кодов для каждого поля можно найти в реестре языковых подкатегорий IANA (например, найдите «Type: region»).

язык: Двух- или трёхбуквенный код языка ISO 639 либо зарегистрированная языковая подкатегория длиной до 8 букв (для будущих расширений). Если для языка существуют двухбуквенный и трёхбуквенный коды, следует использовать двухбуквенный код.; Правила регистра: language не чувствителен к регистру, но Locale всегда преобразует значение к нижнему регистру.; Синтаксис: Корректно сформированные значения language имеют вид [a-zA-Z]{2,8}.; Отклонение от BCP 47: это не полная грамматика языка BCP 47, поскольку из неё исключён extlang (так как предпочтительнее использовать современные трёхбуквенные коды языков).; Примеры: «en» (английский), «ja» (японский), «kok» (конкани)
письменность: Четырёхбуквенный код письменности ISO 15924.; Правила регистра: script не чувствителен к регистру, но Locale всегда преобразует значение к регистру заголовка (первая буква заглавная, остальные — строчные).; Синтаксис: Корректно сформированные значения script имеют вид [a-zA-Z]{4}; Примеры: «Latn» (латиница), «Cyrl» (кириллица)
страна (регион): Двухбуквенный код страны ISO 3166 или трёхзначный цифровой код территории ООН M.49.; Правила регистра: country (region) не чувствителен к регистру, но Locale всегда преобразует значение к верхнему регистру.; Синтаксис: Корректно сформированные значения country (region) имеют вид [a-zA-Z]{2} | [0-9]{3}; Примеры: «US» (Соединённые Штаты), «FR» (Франция), «029» (Карибский регион)
вариант: Любое произвольное значение, используемое для обозначения варианта Locale. Если вариантов несколько, их следует разделять с помощью ('_'|'-'). Более важные варианты должны предшествовать остальным.; Отклонение от BCP 47: подкатегории BCP 47 используются исключительно для указания дополнительных вариантов, определяющих язык или его диалекты, которые не описываются сочетаниями подкатегорий языка, письменности и региона. Однако поле варианта в Locale исторически использовалось для обозначения любых видов вариантов, а не только языковых. Например, некоторые варианты, поддерживаемые в средах выполнения Java SE, указывают на альтернативные культурные особенности, такие как тип календаря или система записи чисел. В BCP 47 такая информация, не идентифицирующая язык, поддерживается подкатегориями расширений или подкатегориями частного использования.; Правила регистра: variant чувствителен к регистру. Отклонение от BCP 47: BCP 47 рассматривает поле варианта как нечувствительное к регистру.; Синтаксис: Корректно сформированные значения variant имеют вид SUBTAG (('_'|'-') SUBTAG)*, где SUBTAG = [0-9][0-9a-zA-Z]{3} | [0-9a-zA-Z]{5,8}.; Отклонение от BCP 47: BCP 47 использует в качестве разделителя только дефис («-»), тогда как Locale допускает более свободный синтаксис.; Примеры: «polyton» (политонический греческий), «POSIX»
расширения: Соответствие между однобуквенными ключами и строковыми значениями, указывающее расширения, не относящиеся к идентификации языка.; Отклонение от BCP 47: extensions в Locale реализуют семантику и синтаксис подкатегорий расширений и подкатегорий частного использования BCP 47. Поле extensions не может содержать пустые значения.; Правила регистра: extensions нечувствительны к регистру, но Locale преобразует все ключи и значения расширений к нижнему регистру.; Синтаксис: Корректно сформированные ключи — это одиночные символы из набора [0-9a-zA-Z]. Корректно сформированные значения имеют вид SUBTAG ('-' SUBTAG)*, где для ключа «x» выполняется SUBTAG = [0-9a-zA-Z]{1,8}, а для остальных ключей — SUBTAG = [0-9a-zA-Z]{2,8} (то есть «x» допускает односимвольные подкатегории).; Пример: key="u"/value="ca-japanese" (японский календарь), key="x"/value="java-1-7"

Отклонение от BCP 47: хотя BCP 47 требует, чтобы значения полей были зарегистрированы в реестре языковых подкатегорий IANA, класс Locale не проверяет это требование. Например, код варианта «foobar» является корректно сформированным, поскольку состоит из 5–8 буквенно-цифровых символов, но не определён в реестре языковых подкатегорий IANA. Класс Locale.Builder проверяет только соответствие отдельного поля синтаксическим требованиям (корректность его формы), но не проверяет само значение. Напротив, Locale::of и его перегруженные варианты не выполняют никаких синтаксических проверок входных данных.

Расширение Unicode U в BCP 47

UTS#35, «Язык разметки данных локали Unicode», определяет необязательные атрибуты и ключевые слова для переопределения или уточнения поведения по умолчанию, связанного с локалью. Ключевое слово представлено парой «ключ — тип». Например, «nu-thai» указывает, что для форматирования чисел (ключ «nu») следует использовать тайские локальные цифры (значение «thai»).

Ключевые слова сопоставляются со значением расширения BCP 47 с помощью ключа расширения «u» (UNICODE_LOCALE_EXTENSION). Приведённый выше пример «nu-thai» преобразуется в расширение «u-nu-thai».

Таким образом, если объект Locale содержит атрибуты и ключевые слова локали Unicode, getExtension(UNICODE_LOCALE_EXTENSION) вернёт строку, представляющую эту информацию, например «nu-thai». Класс Locale также предоставляет методы getUnicodeLocaleAttributes(), getUnicodeLocaleKeys() и getUnicodeLocaleType(String), позволяющие напрямую получать атрибуты локали Unicode и пары «ключ/тип». При представлении в виде строки расширение локали Unicode перечисляет атрибуты в алфавитном порядке, а затем последовательности «ключ/тип», ключи в которых также расположены в алфавитном порядке (порядок подкатегорий, составляющих тип ключа, фиксируется при определении типа).

Корректно сформированный ключ локали имеет вид [0-9a-zA-Z]{2}. Корректно сформированный тип локали имеет вид "" | [0-9a-zA-Z]{3,8} ('-' [0-9a-zA-Z]{3,8})* (он может быть пустым или состоять из последовательности подкатегорий длиной 3–8 буквенно-цифровых символов). Корректно сформированный атрибут локали имеет вид [0-9a-zA-Z]{3,8} (это одна подкатегория в той же форме, что и подкатегория типа локали).

Расширение локали Unicode задаёт необязательное поведение в службах, зависящих от локали. Хотя спецификация LDML определяет различные ключи и значения, конкретные реализации служб, зависящих от локали, в среде выполнения Java могут не поддерживать какие-либо атрибуты локали Unicode или пары «ключ/тип».

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

Локаль по умолчанию используется любыми методами, зависящими от локали, если Locale не указан явно в качестве аргумента, например в NumberFormat.getInstance(). Локаль по умолчанию определяется при запуске среды выполнения Java и устанавливается в три этапа:

Перечисленные ниже системные свойства, связанные с локалью, задаются на основе среды хоста. Некоторые системные свойства (за исключением user.language) могут не иметь значений, полученных из среды хоста.

Показывает ключи свойств и соответствующие значения
Ключ системного свойства, связанного с локалью	Описание
`user.language`	`language` для локали по умолчанию, например «en» (английский)
`user.script`	`script` для локали по умолчанию, например «Latn» (латиница)
`user.country`	`country` для локали по умолчанию, например «US» (Соединённые Штаты)
`user.variant`	`variant` для локали по умолчанию, например «POSIX»
`user.extensions`	`extensions` для локали по умолчанию, например «u-ca-japanese» (японский календарь)

Значения этих системных свойств могут быть переопределены значениями, указанными при запуске. Если переопределяющее значение свойства user.extensions невозможно разобрать, оно игнорируется. Синтаксис и допустимость переопределяющих значений остальных свойств не проверяются; они напрямую используются в локали по умолчанию. (Как правило, значения системных свойств можно задавать с помощью параметра командной строки -D средства запуска. Например, указание -Duser.extensions=foobarbaz приводит к созданию локали по умолчанию без расширений, а указание -Duser.language=foobarbaz — к созданию локали по умолчанию с языком «foobarbaz».)
Экземпляр Locale по умолчанию создаётся на основе значений этих системных свойств.

Изменение значений системных свойств с помощью System.setProperties(Properties)/ System.setProperty(String, String) не влияет на локаль по умолчанию.

После установки локали по умолчанию приложения могут получить её с помощью getDefault() и изменить с помощью setDefault(Locale). Если локаль по умолчанию изменяется с помощью setDefault(Locale), соответствующие системные свойства не меняются. Не рекомендуется считывать эти системные свойства и анализировать или интерпретировать их значения, поскольку они могут устареть.

Категория локали

Для каждой категории Locale.Category существуют более узкоспециализированные локали по умолчанию. Эти локали по умолчанию для конкретной категории можно получить с помощью getDefault(Category) и задать с помощью setDefault(Category, Locale). Локали по умолчанию для конкретной категории создаются на основе соответствующих системных свойств, которые состоят из перечисленных выше базовых системных свойств с суффиксом ".display" или ".format" в зависимости от категории. Например, значение системного свойства user.language.display будет использовано в части language локали по умолчанию для категории Locale.Category.DISPLAY. Если системные свойства для конкретной категории отсутствуют, используются системные свойства без указания категории, например user.language в предыдущем примере.

Получение локали

Получить объект Locale можно несколькими способами. Использовать устаревшие конструкторы Locale не рекомендуется.

Константы Locale: Предоставляется ряд удобных констант, возвращающих объекты Locale для часто используемых локалей. Например, Locale.US — это объект Locale для Соединённых Штатов.
Фабричные методы: Locale::of и его перегруженные варианты получают объект Locale из заданных значений language, country и/или variant. Метод forLanguageTag(String) получает объект Locale для корректно сформированного языкового тега BCP 47.
Построитель: Locale.Builder используется для создания объекта Locale, соответствующего синтаксису BCP 47. Используйте построитель, чтобы обеспечить соблюдение синтаксических ограничений входных данных.

Следующие вызовы создают эквивалентные объекты Locale:

    Locale.US;
    Locale.of("en", "US");
    Locale.forLanguageTag("en-US");
    new Locale.Builder().setLanguage("en").setRegion("US").build();

Примеры использования

После получения объекта Locale можно запросить сведения о нём. Например, используйте getCountry(), чтобы получить код страны (или региона), и getLanguage(), чтобы получить язык. Метод getDisplayCountry() позволяет получить название страны, подходящее для отображения пользователю. Аналогично, используйте getDisplayLanguage(), чтобы получить название языка, подходящее для отображения пользователю. Методы getDisplayXXX сами зависят от локали и имеют два варианта: один с явным параметром локали, другой — без него. Последний использует локаль по умолчанию для категории DISPLAY, поэтому следующие варианты эквивалентны:

    Locale.getDefault().getDisplayCountry();
    Locale.getDefault().getDisplayCountry(Locale.getDefault(Locale.Category.DISPLAY));

Платформа Java предоставляет ряд классов, выполняющих операции, зависящие от локали. Например, класс NumberFormat форматирует числа, денежные суммы и проценты с учётом локали. Такие классы, как NumberFormat, предоставляют несколько фабричных методов для создания объекта этого типа по умолчанию. Обычно у этих методов есть два варианта: один с явным параметром локали, другой — без него. Последний использует локаль по умолчанию для категории FORMAT, поэтому следующие варианты эквивалентны:

    NumberFormat.getCurrencyInstance();
    NumberFormat.getCurrencyInstance(Locale.getDefault(Locale.Category.FORMAT));

В следующем примере показаны операции с валютой и датами, зависящие от локали, для разных локалей:

    var number = 1000;
    NumberFormat.getCurrencyInstance(Locale.US).format(number); // returns "$1,000.00"
    NumberFormat.getCurrencyInstance(Locale.JAPAN).format(number); // returns "Â¥1,000""
    var date = LocalDate.of(2024, 1, 1);
    DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG).localizedBy(Locale.US).format(date); // returns "January 1, 2024"
    DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG).localizedBy(Locale.JAPAN).format(date); // returns "2024å¹´1æ1æ¥"

Сопоставление локалей

Если приложение интернационализировано и предоставляет локализованные ресурсы для нескольких локалей, иногда ему нужно найти одну или несколько локалей (или языковых тегов), соответствующих конкретным предпочтениям пользователя. Обратите внимание, что в следующей документации по сопоставлению локалей термин «языковой тег» используется как синоним слова «локаль».

Для сопоставления предпочтительных локалей пользователя с набором языковых тегов в RFC 4647 «Сопоставление языковых тегов» определены два механизма: фильтрация и поиск. Фильтрация используется для получения всех соответствующих локалей, а поиск — для выбора наиболее подходящей локали. Сопоставление выполняется без учёта регистра. Эти механизмы сопоставления описаны в следующих разделах.

Предпочтения пользователя называются списком приоритетов языков и представляются в виде списка языковых диапазонов. Синтаксически существуют два типа языковых диапазонов: базовые и расширенные. Подробности см. в разделе Locale.LanguageRange.

Фильтрация

Операция фильтрации возвращает все соответствующие языковые теги. В RFC 4647 она определяется следующим образом: «При фильтрации каждый языковой диапазон представляет наименее специфичный языковой тег (то есть языковой тег с наименьшим количеством подкатегорий), который является приемлемым совпадением. Все языковые теги из набора совпадений содержат такое же или большее количество подкатегорий, чем языковой диапазон. Каждая подкатегория языкового диапазона, не являющаяся подстановочным знаком, встречается в каждом из соответствующих языковых тегов».

Существует два типа фильтрации: фильтрация по базовым языковым диапазонам (называемая «базовой фильтрацией») и фильтрация по расширенным языковым диапазонам (называемая «расширенной фильтрацией»). Результаты могут различаться в зависимости от типа языковых диапазонов, включённых в заданный список приоритетов языков. Параметр Locale.FilteringMode задаёт способ выполнения фильтрации.

Поиск

Операция поиска возвращает наиболее подходящие языковые теги. В RFC 4647 она определяется следующим образом: «В отличие от фильтрации, каждый языковой диапазон представляет наиболее специфичный тег, который является приемлемым совпадением. Первый найденный тег, соответствующий приоритетам пользователя, считается наиболее близким совпадением и возвращается в качестве результата».

Например, если список приоритетов языков состоит из двух языковых диапазонов "zh-Hant-TW" и "en-US", расположенных в порядке приоритета, метод поиска последовательно проверяет перечисленные ниже языковые теги, чтобы найти наиболее подходящий тег.

   1. zh-Hant-TW
   2. zh-Hant
   3. zh
   4. en-US
   5. en

Если какой-либо языковой тег полностью соответствует одному из указанных выше языковых диапазонов, возвращается этот языковой тег.

"*" — это специальный языковой диапазон, который при поиске игнорируется.

Если в результате подкатегории '*', включённой в языковой диапазон, подходят несколько языковых тегов, лучшим считается первый совпавший языковой тег, возвращённый при переборе Iterator для Collection языковых тегов.

Сериализация

При сериализации метод writeObject записывает в выходной поток все поля, включая расширения.

При десериализации метод readResolve добавляет расширения, как описано в разделе «Особые случаи», только для двух случаев: th_TH_TH и ja_JP_JP.

Примечание по реализации:

Совместимость

Ниже приведены комментарии для приложений, которым необходимо обеспечить взаимодействие с более ранними выпусками Locale, предоставляемыми эталонной реализацией.

Поведение Locale

Для обеспечения совместимости конструкторы Locale (устаревшие), of(String, String, String) и его перегруженные варианты сохраняют поведение, существовавшее до версии 1.7 среды выполнения Java. Иными словами, для входных параметров не вводится ограничение длины. Аналогичным образом, метод toString() в значительной степени сохраняет прежнее поведение. Приложения, которые ранее разбирали результат toString() на поля языка, страны и варианта, могут продолжать это делать (хотя настоятельно не рекомендуется). Следует учитывать, что поле варианта будет содержать дополнительную информацию, если заданы письменность или расширения.

Кроме того, BCP 47 вводит синтаксические ограничения, которых нет у конструкторов Locale. Это означает, что преобразование некоторых локалей в языковые теги BCP 47 и обратно невозможно без потери информации. Поэтому toLanguageTag() не может представить состояние локалей, язык, страна или вариант которых не соответствуют BCP 47.

В связи с этими проблемами приложениям рекомендуется отказаться от создания несоответствующих локалей и вместо этого использовать API forLanguageTag(String) и Locale.Builder. Приложения, которым требуется строковое представление локали целиком, могут всегда использовать для этой цели toLanguageTag().

Особые случаи

По соображениям совместимости две несоответствующие локали обрабатываются как особые случаи: ja_JP_JP и th_TH_TH. Они имеют неправильную форму в BCP 47, поскольку их варианты слишком короткие. Для упрощения перехода на BCP 47 при создании они обрабатываются особым образом. Только эти два случая приводят к тому, что конструктор создаёт расширение; все остальные значения ведут себя точно так же, как до Java 7.

В Java для представления японского языка в Японии вместе с японским императорским календарём использовалось значение ja_JP_JP. Теперь это можно представить с помощью расширения локали Unicode, указав ключ локали Unicode ca (для «календаря») и тип japanese. При вызове конструктора Locale с аргументами «ja», «JP», «JP» расширение «u-ca-japanese» добавляется автоматически.

В Java для представления тайского языка в Таиланде вместе с тайскими цифрами использовалось значение th_TH_TH. Теперь это также можно представить с помощью расширения локали Unicode, указав ключ локали Unicode nu (для «числа») и значение thai. При вызове конструктора Locale с аргументами «th», «TH», «TH» расширение «u-nu-thai» добавляется автоматически.

Устаревшие коды языков

Конструкторы Locale всегда преобразовывали три кода языков в их прежние, устаревшие формы: he преобразуется в iw, yi — в ji, а id — в in. Начиная с Java SE 17 это больше не так. Каждый язык преобразуется в новую форму: iw — в he, ji — в yi, а in — в id.

Для обеспечения обратной совместимости системное свойство java.locale.useOldISOCodes возвращает поведение к состоянию, существовавшему до Java SE 17. Если системному свойству присвоено значение true, эти три текущих кода языков преобразуются в соответствующие устаревшие формы. Свойство считывается только при запуске среды выполнения Java; последующие вызовы System.setProperty() не оказывают никакого эффекта. Начиная с Java SE 25 использование системного свойства java.locale.useOldISOCodes объявлено устаревшим. Это поведение для обратной совместимости будет удалено в одном из будущих выпусков JDK.

API, добавленные в Java SE 7, выполняют преобразование между старыми и новыми кодами языков, сохраняя преобразованные коды внутри Locale (поэтому getLanguage и toString возвращают преобразованный код, который зависит от системного свойства java.locale.useOldISOCodes), но используют новые коды в API языковых тегов BCP 47 (поэтому toLanguageTag возвращает новый код). Благодаря этому эквивалентность локалей сохраняется независимо от того, какой код или API использовался для их создания. Механизм поиска пакетов ресурсов Java по умолчанию также выполняет это преобразование, поэтому ресурсы можно именовать с использованием любого из соглашений; см. ResourceBundle.Control.

Начиная с версии:

1.1

Внешние спецификации

См. также:

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static final class`	`Locale.Builder`	`Builder` используется для создания экземпляров `Locale` на основе значений, заданных методами-сеттерами.
`static enum`	`Locale.Category`	Перечисление категорий локалей.
`static enum`	`Locale.FilteringMode`	Это перечисление содержит константы для выбора режима фильтрации при сопоставлении локалей.
`static enum`	`Locale.IsoCountryCode`	Перечисление для указания типа, определённого в ISO 3166.
`static final class`	`Locale.LanguageRange`	Этот класс представляет диапазон языков, определённый в RFC 4647 «Сопоставление языковых тегов».

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final Locale`	`CANADA`	Полезная константа для страны.
`static final Locale`	`CANADA_FRENCH`	Полезная константа для страны.
`static final Locale`	`CHINA`	Полезная константа для страны.
`static final Locale`	`CHINESE`	Полезная константа для языка.
`static final Locale`	`ENGLISH`	Полезная константа для языка.
`static final Locale`	`FRANCE`	Полезная константа для страны.
`static final Locale`	`FRENCH`	Полезная константа для языка.
`static final Locale`	`GERMAN`	Полезная константа для языка.
`static final Locale`	`GERMANY`	Полезная константа для страны.
`static final Locale`	`ITALIAN`	Полезная константа для языка.
`static final Locale`	`ITALY`	Полезная константа для страны.
`static final Locale`	`JAPAN`	Полезная константа для страны.
`static final Locale`	`JAPANESE`	Полезная константа для языка.
`static final Locale`	`KOREA`	Полезная константа для страны.
`static final Locale`	`KOREAN`	Полезная константа для языка.
`static final Locale`	`PRC`	Полезная константа для страны.
`static final char`	`PRIVATE_USE_EXTENSION`	Ключ расширения для частного использования ('x').
`static final Locale`	`ROOT`	Полезная константа для корневой локали.
`static final Locale`	`SIMPLIFIED_CHINESE`	Полезная константа для языка.
`static final Locale`	`TAIWAN`	Полезная константа для страны.
`static final Locale`	`TRADITIONAL_CHINESE`	Полезная константа для языка.
`static final Locale`	`UK`	Полезная константа для страны.
`static final char`	`UNICODE_LOCALE_EXTENSION`	Ключ расширения локали Unicode ('u').
`static final Locale`	`US`	Полезная константа для страны.

Краткое описание конструкторов

Конструктор	Описание
`Locale(String language)`	Устарел. Конструкторы Locale устарели.
`Locale(String language, String country)`	Устарел. Конструкторы Locale устарели.
`Locale(String language, String country, String variant)`	Устарел. Конструкторы Locale устарели.

Краткое описание методов

Модификатор и тип	Метод	Описание
`static Stream<Locale>`	`availableLocales()`	Возвращает поток доступных локалей.
`static String`	`caseFoldLanguageTag(String languageTag)`	Возвращает языковой тег IETF BCP 47 в нижнем регистре.
`Object`	`clone()`	Переопределяет Cloneable.
`boolean`	`equals(Object obj)`	Возвращает true, если эта локаль равна другому объекту.
`static List<Locale>`	`filter(List<Locale.LanguageRange> priorityList, Collection<Locale> locales)`	Возвращает список подходящих экземпляров `Locale`, используя механизм фильтрации, определённый в RFC 4647.
`static List<Locale>`	`filter(List<Locale.LanguageRange> priorityList, Collection<Locale> locales, Locale.FilteringMode mode)`	Возвращает список подходящих экземпляров `Locale`, используя механизм фильтрации, определённый в RFC 4647.
`static List<String>`	`filterTags(List<Locale.LanguageRange> priorityList, Collection<String> tags)`	Возвращает список подходящих языковых тегов, используя механизм базовой фильтрации, определённый в RFC 4647.
`static List<String>`	`filterTags(List<Locale.LanguageRange> priorityList, Collection<String> tags, Locale.FilteringMode mode)`	Возвращает список подходящих языковых тегов, используя механизм базовой фильтрации, определённый в RFC 4647.
`static Locale`	`forLanguageTag(String languageTag)`	Возвращает локаль для указанной строки языкового тега IETF BCP 47.
`static Locale[]`	`getAvailableLocales()`	Возвращает массив доступных локалей.
`String`	`getCountry()`	Возвращает код страны/региона для этой локали, который должен быть пустой строкой, двухбуквенным кодом ISO 3166 в верхнем регистре или трёхзначным кодом UN M.49.
`static Locale`	`getDefault()`	Возвращает текущее значение `default locale` для этого экземпляра виртуальной машины Java.
`static Locale`	`getDefault(Locale.Category category)`	Возвращает текущее значение `default locale` для указанной категории в этом экземпляре виртуальной машины Java.
`final String`	`getDisplayCountry()`	Возвращает название страны локали, подходящее для отображения пользователю.
`String`	`getDisplayCountry(Locale inLocale)`	Возвращает название страны локали, подходящее для отображения пользователю.
`final String`	`getDisplayLanguage()`	Возвращает название языка локали, подходящее для отображения пользователю.
`String`	`getDisplayLanguage(Locale inLocale)`	Возвращает название языка локали, подходящее для отображения пользователю.
`final String`	`getDisplayName()`	Возвращает название локали, подходящее для отображения пользователю.
`String`	`getDisplayName(Locale inLocale)`	Возвращает название локали, подходящее для отображения пользователю.
`String`	`getDisplayScript()`	Возвращает название письменности локали, подходящее для отображения пользователю.
`String`	`getDisplayScript(Locale inLocale)`	Возвращает название письменности локали, подходящее для отображения пользователю.
`final String`	`getDisplayVariant()`	Возвращает название кода варианта локали, подходящее для отображения пользователю.
`String`	`getDisplayVariant(Locale inLocale)`	Возвращает название кода варианта локали, подходящее для отображения пользователю.
`String`	`getExtension(char key)`	Возвращает значение расширения (или частного использования), связанное с указанным ключом, либо null, если с ключом не связано расширение.
`Set<Character>`	`getExtensionKeys()`	Возвращает набор ключей расширений, связанных с этой локалью, или пустой набор, если у неё нет расширений.
`String`	`getISO3Country()`	Возвращает трёхбуквенное сокращение названия страны этой локали.
`String`	`getISO3Language()`	Возвращает трёхбуквенное сокращение названия языка этой локали.
`static String[]`	`getISOCountries()`	Возвращает список всех двухбуквенных кодов стран, определённых в ISO 3166.
`static Set<String>`	`getISOCountries(Locale.IsoCountryCode type)`	Возвращает неизменяемый `Set` кодов стран ISO 3166 для указанного типа.
`static String[]`	`getISOLanguages()`	Возвращает список всех двухбуквенных кодов языков, определённых в ISO 639.
`String`	`getLanguage()`	Возвращает код языка этой локали.
`String`	`getScript()`	Возвращает письменность этой локали, которая должна быть пустой строкой или четырёхбуквенным кодом письменности ISO 15924.
`Set<String>`	`getUnicodeLocaleAttributes()`	Возвращает набор атрибутов локали Unicode, связанных с этой локалью, или пустой набор, если атрибутов нет.
`Set<String>`	`getUnicodeLocaleKeys()`	Возвращает набор ключей локали Unicode, определённых этой локалью, или пустой набор, если таких ключей нет.
`String`	`getUnicodeLocaleType(String key)`	Возвращает тип локали Unicode, связанный с указанным ключом локали Unicode для этой локали.
`String`	`getVariant()`	Возвращает код варианта этой локали.
`boolean`	`hasExtensions()`	Возвращает `true`, если у этой `Locale` есть какие-либо расширения.
`int`	`hashCode()`	Переопределяет hashCode.
`static Locale`	`lookup(List<Locale.LanguageRange> priorityList, Collection<Locale> locales)`	Возвращает экземпляр `Locale` для наиболее подходящего языкового тега, используя механизм поиска, определённый в RFC 4647.
`static String`	`lookupTag(List<Locale.LanguageRange> priorityList, Collection<String> tags)`	Возвращает наиболее подходящий языковой тег, используя механизм поиска, определённый в RFC 4647.
`static Locale`	`of(String language)`	Создаёт локаль на основе кода языка.
`static Locale`	`of(String language, String country)`	Создаёт локаль на основе языка и страны.
`static Locale`	`of(String language, String country, String variant)`	Создаёт локаль на основе языка, страны и варианта.
`static void`	`setDefault(Locale newLocale)`	Устанавливает `default locale` для этого экземпляра виртуальной машины Java.
`static void`	`setDefault(Locale.Category category, Locale newLocale)`	Устанавливает `default locale` для указанной категории в этом экземпляре виртуальной машины Java.
`Locale`	`stripExtensions()`	Возвращает копию этой `Locale` без расширений.
`String`	`toLanguageTag()`	Возвращает корректно сформированный языковой тег IETF BCP 47, представляющий эту локаль.
`final String`	`toString()`	Возвращает строковое представление этого объекта `Locale`, состоящее из языка, страны, варианта, письменности и расширений в следующем виде: язык + "_" + страна + "_" + (вариант + "_#" \| "#") + письменность + "_" + расширения. Язык всегда записывается в нижнем регистре, страна — в верхнем, письменность — с заглавной буквы, а расширения — в нижнем регистре.

Методы, объявленные в классе Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Подробное описание полей

ENGLISH

public static final Locale ENGLISH

Полезная константа для языка.

FRENCH

public static final Locale FRENCH

Полезная константа для языка.

GERMAN

public static final Locale GERMAN

Полезная константа для языка.

ITALIAN

public static final Locale ITALIAN

Полезная константа для языка.

JAPANESE

public static final Locale JAPANESE

Полезная константа для языка.

KOREAN

public static final Locale KOREAN

Полезная константа для языка.

CHINESE

public static final Locale CHINESE

Полезная константа для языка.

SIMPLIFIED_CHINESE

public static final Locale SIMPLIFIED_CHINESE

Полезная константа для языка.

TRADITIONAL_CHINESE

public static final Locale TRADITIONAL_CHINESE

Полезная константа для языка.

FRANCE

public static final Locale FRANCE

Полезная константа для страны.

GERMANY

public static final Locale GERMANY

Полезная константа для страны.

ITALY

public static final Locale ITALY

Полезная константа для страны.

JAPAN

public static final Locale JAPAN

Полезная константа для страны.

KOREA

public static final Locale KOREA

Полезная константа для страны.

UK

public static final Locale UK

Полезная константа для страны.

US

public static final Locale US

Полезная константа для страны.

CANADA

public static final Locale CANADA

Полезная константа для страны.

CANADA_FRENCH

public static final Locale CANADA_FRENCH

Полезная константа для страны.

ROOT

public static final Locale ROOT

Полезная константа для корневой локали. Корневая локаль — это локаль, язык, страна и вариант которой представлены пустыми строками (""). Она считается базовой локалью для всех локалей и используется как нейтральная по отношению к языку и стране локаль в операциях, зависящих от локали.

Начиная с:: 1.6

CHINA

public static final Locale CHINA

Полезная константа для страны.

PRC

public static final Locale PRC

Полезная константа для страны.

TAIWAN

public static final Locale TAIWAN

Полезная константа для страны.

PRIVATE_USE_EXTENSION

public static final char PRIVATE_USE_EXTENSION

Ключ расширения для частного использования ('x').

Начиная с:

1.7

См. также:

UNICODE_LOCALE_EXTENSION

public static final char UNICODE_LOCALE_EXTENSION

Ключ расширения локали Unicode ('u').

Начиная с:

1.7

См. также:

Подробное описание конструкторов

Locale

@Deprecated(since="19") public Locale(String language, String country, String variant)

Устарело.

Конструкторы Locale устарели. Другие варианты см. в разделе Получение объекта Locale.

Создает локаль из языка, страны и варианта. Этот конструктор приводит значение языка к нижнему регистру, а значение страны — к верхнему.

Примечание по реализации:

Устаревшие коды ISO 639 ("iw", "ji" и "in") преобразуются в актуальные формы. Дополнительные сведения см. в разделе Устаревшие коды языков.
Для обратной совместимости этот конструктор не выполняет синтаксическую проверку входных данных.
Сочетания ("ja", "JP", "JP") и ("th", "TH", "TH") обрабатываются особым образом. Дополнительные сведения см. в разделе Особые случаи.

Параметры:

language — код языка ISO 639 alpha-2 или alpha-3 либо языковой подтег длиной не более 8 символов. Допустимые значения языка описаны в документации класса Locale.

country — код страны ISO 3166 alpha-2 или трехзначный цифровой код области UN M.49. Допустимые значения страны описаны в документации класса Locale.

variant — произвольное значение, обозначающее вариант Locale. Подробные сведения см. в документации класса Locale.

Исключения:

NullPointerException — выбрасывается, если какой-либо аргумент равен null.

Locale

@Deprecated(since="19") public Locale(String language, String country)

Устарело.

Конструкторы Locale устарели. Другие варианты см. в разделе Получение объекта Locale.

Создает локаль из языка и страны. Этот конструктор приводит значение языка к нижнему регистру, а значение страны — к верхнему.

Примечание по реализации:

Устаревшие коды ISO 639 ("iw", "ji" и "in") преобразуются в актуальные формы. Дополнительные сведения см. в разделе Устаревшие коды языков.
Для обратной совместимости этот конструктор не выполняет синтаксическую проверку входных данных.

Параметры:

Исключения:

NullPointerException — выбрасывается, если один из аргументов равен null.

Locale

@Deprecated(since="19") public Locale(String language)

Устарело.

Конструкторы Locale устарели. Другие варианты см. в разделе Получение объекта Locale.

Создает локаль из кода языка. Этот конструктор приводит значение языка к нижнему регистру.

Примечание по реализации:

Устаревшие коды ISO 639 ("iw", "ji" и "in") преобразуются в актуальные формы. Дополнительные сведения см. в разделе Устаревшие коды языков.
Для обратной совместимости этот конструктор не выполняет синтаксическую проверку входных данных.

Параметры:

Исключения:

NullPointerException — выбрасывается, если аргумент равен null.

Начиная с:

1.4

Подробное описание методов

of

public static Locale of(String language, String country, String variant)

Получает локаль из языка, страны и варианта. Этот метод приводит значение языка к нижнему регистру, а значение страны — к верхнему.

Примечание по реализации:

Этот метод не выполняет синтаксическую проверку входных данных. Для полной синтаксической проверки согласно BCP47 используйте Locale.Builder.
Сочетания ("ja", "JP", "JP") и ("th", "TH", "TH") обрабатываются особым образом. Дополнительные сведения см. в разделе Особые случаи.
Устаревшие коды ISO 639 ("iw", "ji" и "in") преобразуются в актуальные формы. Дополнительные сведения см. в разделе Устаревшие коды языков.

Параметры:

language — код языка. Допустимые значения языка описаны в документации класса Locale.

country — код страны. Допустимые значения страны описаны в документации класса Locale.

variant — произвольное значение, обозначающее вариант Locale. Допустимые значения варианта описаны в документации класса Locale.

Возвращает:

объект Locale

Исключения:

NullPointerException — выбрасывается, если какой-либо аргумент равен null.

Начиная с:

of

public static Locale of(String language, String country)

Получает локаль из языка и страны. Этот метод приводит значение языка к нижнему регистру, а значение страны — к верхнему.

Примечание по реализации:

Этот метод не выполняет синтаксическую проверку входных данных. Для полной синтаксической проверки согласно BCP47 используйте Locale.Builder.
Устаревшие коды ISO 639 ("iw", "ji" и "in") преобразуются в актуальные формы. Дополнительные сведения см. в разделе Устаревшие коды языков.

Параметры:

language — код языка. Допустимые значения языка описаны в документации класса Locale.

country — код страны. Допустимые значения страны описаны в документации класса Locale.

Возвращает:

объект Locale

Исключения:

NullPointerException — выбрасывается, если один из аргументов равен null.

Начиная с:

of

public static Locale of(String language)

Получает локаль из кода языка. Этот метод приводит значение языка к нижнему регистру.

Примечание по реализации:

Этот метод не выполняет синтаксическую проверку входных данных. Для полной синтаксической проверки согласно BCP47 используйте Locale.Builder.
Устаревшие коды ISO 639 ("iw", "ji" и "in") преобразуются в актуальные формы. Дополнительные сведения см. в разделе Устаревшие коды языков.

Параметры:

language — код языка. Допустимые значения языка описаны в документации класса Locale.

Возвращает:

объект Locale

Исключения:

NullPointerException — выбрасывается, если аргумент равен null.

Начиная с:

getDefault

public static Locale getDefault()

Возвращает текущее значение default locale для данного экземпляра виртуальной машины Java.

Виртуальная машина Java задает локаль по умолчанию при запуске на основе среды хоста. Она используется многими методами, зависящими от локали, если локаль явно не указана. Ее можно изменить с помощью метода setDefault(Locale).

Возвращает:: локаль по умолчанию для данного экземпляра виртуальной машины Java

getDefault

public static Locale getDefault(Locale.Category category)

Возвращает текущее значение default locale для указанной категории данного экземпляра виртуальной машины Java.

Параметры:

category — указанная категория, для которой требуется получить локаль по умолчанию

Возвращает:

локаль по умолчанию для указанной категории данного экземпляра виртуальной машины Java

Исключения:

NullPointerException — если category равен null

Начиная с:

1.7

См. также:

setDefault

public static void setDefault(Locale newLocale)

Задает default locale для данного экземпляра виртуальной машины Java. Это не влияет на локаль хоста.

Виртуальная машина Java задает локаль по умолчанию при запуске на основе среды хоста. Она используется многими методами, зависящими от локали, если локаль явно не указана.

Поскольку изменение локали по умолчанию может повлиять на многие функциональные области, этот метод следует использовать только в том случае, если вызывающий код готов повторно инициализировать код, зависящий от локали, который выполняется в той же виртуальной машине Java.

При задании локали по умолчанию с помощью этого метода все локали по умолчанию для каждой категории также устанавливаются в указанную локаль.

Параметры:: newLocale — новая локаль по умолчанию
Исключения:: NullPointerException — если newLocale равен null

setDefault

public static void setDefault(Locale.Category category, Locale newLocale)

Задает default locale для указанной категории данного экземпляра виртуальной машины Java. Это не влияет на локаль хоста.

Параметры:

category — указанная категория, для которой задается локаль по умолчанию

newLocale — новая локаль по умолчанию

Исключения:

NullPointerException — если category и/или newLocale равны null

Начиная с:

1.7

См. также:

getAvailableLocales

public static Locale[] getAvailableLocales()

Возвращает массив доступных локалей. Возвращенный массив представляет собой объединение локалей, поддерживаемых средой выполнения Java и развернутыми реализациями LocaleServiceProvider. Как минимум, возвращенный массив должен содержать экземпляр Locale, равный Locale.ROOT, и экземпляр Locale, равный Locale.US.

Возвращает:: массив доступных локалей

availableLocales

public static Stream<Locale> availableLocales()

Возвращает поток доступных локалей. Возвращенный поток представляет собой объединение локалей, поддерживаемых средой выполнения Java и развернутыми реализациями LocaleServiceProvider. Как минимум, возвращенный поток должен содержать экземпляр Locale, равный Locale.ROOT, и экземпляр Locale, равный Locale.US.

Примечание по реализации:: В отличие от getAvailableLocales(), этот метод не создает защитную копию массива Locale.
Возвращает:: поток доступных локалей
Начиная с:: 21

getISOCountries

public static String[] getISOCountries()

Возвращает список всех двухбуквенных кодов стран, определенных в ISO 3166. Их можно использовать для получения объектов Locale. Этот метод эквивалентен getISOCountries(Locale.IsoCountryCode type) с type Locale.IsoCountryCode.PART1_ALPHA2.

Примечание: Класс Locale также поддерживает другие коды стран (регионов), например трехзначные цифровые коды областей UN M.49. Поэтому возвращаемый этим методом список не содержит ВСЕ допустимые коды, которые можно использовать для получения объектов Locale.

Обратите внимание, что этот метод не возвращает устаревшие двухбуквенные коды стран. Коды ISO3166-3, обозначающие страны, которым соответствовали эти устаревшие коды, можно получить с помощью метода getISOCountries(Locale.IsoCountryCode type) с type Locale.IsoCountryCode.PART3.

Возвращает:: массив двухбуквенных кодов стран ISO 3166.

getISOCountries

public static Set<String> getISOCountries(Locale.IsoCountryCode type)

Возвращает неизменяемый Set кодов стран ISO3166 указанного типа.

Параметры:

type — указанный тип кода ISO Locale.IsoCountryCode.

Возвращает:

неизменяемый Set кодов стран ISO3166 указанного типа

Исключения:

NullPointerException — если type равен null

Начиная с:

См. также:

getISOLanguages

public static String[] getISOLanguages()

Возвращает список всех двухбуквенных кодов языков, определенных в ISO 639. Их можно использовать для получения объектов Locale.

Примечание:

ISO 639 — нестабильный стандарт: коды некоторых языков менялись. Список, возвращаемый этой функцией, содержит как новые, так и старые коды языков, коды которых изменились.
Класс Locale также поддерживает коды языков длиной до 8 символов. Поэтому возвращаемый этим методом список не содержит ВСЕ допустимые коды, которые можно использовать для получения объектов Locale.

Возвращает:: массив двухбуквенных кодов языков ISO 639.

getLanguage

public String getLanguage()

Возвращает код языка этой локали.

Примечание по реализации:

Этот метод возвращает новые формы устаревших кодов ISO 639 ("iw", "ji" и "in"). Дополнительные сведения см. в разделе Устаревшие коды языков.

Возвращает:

код языка или пустую строку, если он не определен.

См. также:

getScript

public String getScript()

Возвращает письменность этой локали, которая должна быть представлена либо пустой строкой, либо четырехбуквенным кодом письменности ISO 15924. Первая буква записывается в верхнем регистре, остальные — в нижнем, например 'Latn', 'Cyrl'.

Возвращает:

код письменности или пустую строку, если он не определен.

Начиная с:

1.7

См. также:

getCountry

public String getCountry()

Возвращает код страны/региона этой локали, который должен быть представлен либо пустой строкой, либо двухбуквенным кодом ISO 3166 в верхнем регистре, либо трехзначным кодом UN M.49.

Возвращает:

код страны/региона или пустую строку, если он не определен.

См. также:

getVariant

public String getVariant()

Возвращает код варианта этой локали.

Возвращает:

код варианта или пустую строку, если он не определен.

См. также:

hasExtensions

public boolean hasExtensions()

Возвращает true, если у этой Locale есть какие-либо расширения.

Возвращает:: true, если у этой Locale есть какие-либо расширения
Начиная с:: 1.8

stripExtensions

public Locale stripExtensions()

Возвращает копию этой Locale без расширений. Если у этой Locale нет расширений, возвращается эта Locale.

Возвращает:: копию этой Locale без расширений или this, если у this нет расширений
Начиная с:: 1.8

getExtension

public String getExtension(char key)

Возвращает значение расширения (или частного использования), связанное с указанным ключом, либо null, если с ключом не связано расширение. Чтобы значение было корректно сформировано, ключ должен входить в [0-9A-Za-z]. Ключи не чувствительны к регистру, поэтому, например, 'z' и 'Z' обозначают одно и то же расширение.

Параметры:

key — ключ расширения

Возвращает:

расширение или null, если для указанного ключа в этой локали не определено расширение.

Исключения:

IllegalArgumentException — если ключ имеет неверный формат

Начиная с:

1.7

См. также:

getExtensionKeys

public Set<Character> getExtensionKeys()

Возвращает набор ключей расширений, связанных с этой локалью, или пустой набор, если расширений нет. Возвращаемый набор неизменяем. Все ключи будут в нижнем регистре.

Возвращает:: набор ключей расширений или пустой набор, если у этой локали нет расширений.
Начиная с:: 1.7

getUnicodeLocaleAttributes

public Set<String> getUnicodeLocaleAttributes()

Возвращает набор атрибутов локали Unicode, связанных с этой локалью, или пустой набор, если атрибутов нет. Возвращаемый набор неизменяем.

Возвращает:: набор атрибутов.
Начиная с:: 1.7

getUnicodeLocaleType

public String getUnicodeLocaleType(String key)

Возвращает тип локали Unicode, связанный с указанным ключом локали Unicode для этой локали. Для ключей, определенных без типа, возвращается пустая строка. Если ключ не определен, возвращается null. Ключи не чувствительны к регистру. Ключ должен состоять из двух буквенно-цифровых символов ([0-9a-zA-Z]); в противном случае выбрасывается IllegalArgumentException.

Параметры:: key — ключ локали Unicode
Возвращает:: тип локали Unicode, связанный с ключом, или null, если ключ не определен для этой локали.
Исключения:: IllegalArgumentException — если ключ имеет неверный формат; NullPointerException — если key равен null
Начиная с:: 1.7

getUnicodeLocaleKeys

public Set<String> getUnicodeLocaleKeys()

Возвращает набор ключей локали Unicode, определенных для этой локали, или пустой набор, если таких ключей нет. Возвращаемый набор неизменяем. Все ключи записаны в нижнем регистре.

Возвращает:: набор ключей локали Unicode или пустой набор, если в этой локали нет ключевых слов локали Unicode.
Начиная с:: 1.7

toString

public final String toString()

Возвращает строковое представление объекта Locale, состоящее из языка, страны, варианта, письменности и расширений, как показано ниже:

language + "_" + country + "_" + (variant + "_#" | "#") + script + "_" + extensions

Язык всегда записывается строчными буквами, страна — прописными, письменность — с заглавной буквы, а расширения — строчными буквами. Расширения и подтеги частного использования располагаются в каноническом порядке, как описано в toLanguageTag().

Если у локали нет ни письменности, ни расширений, результат совпадает с результатом в Java 6 и более ранних версиях.

Если поля языка и страны отсутствуют, эта функция возвращает пустую строку, даже если присутствуют поля варианта, письменности или расширений (локаль, содержащая только вариант, недопустима: вариант должен сопровождаться корректным кодом языка или страны).

Если присутствуют письменность или расширения, а вариант отсутствует, перед символом "#" не добавляется подчёркивание.

Такое поведение предназначено для поддержки отладки и совместимости с предыдущим использованием toString, в котором предполагалось наличие только полей языка, страны и варианта. Чтобы представить Locale в виде строки для обмена данными, используйте toLanguageTag().

Примеры:

en
de_DE
_GB
en_US_WIN
de__POSIX
zh_CN_#Hans
zh_TW_#Hant_x-java
th_TH_TH_#u-nu-thai

Переопределяет:

toString в классе Object

Возвращает:

Строковое представление Locale для отладки.

См. также:

toLanguageTag

public String toLanguageTag()

Возвращает корректно сформированную языковую метку IETF BCP 47, представляющую эту локаль.

Если язык, страна или вариант этой Locale не соответствует синтаксическим требованиям к языковым меткам IETF BCP 47, этот метод обрабатывает эти поля, как описано ниже:

Язык: Если язык не указан или имеет некорректную форму (например, "a" или "e2"), он выводится как "und" (неопределённый).

Страна: Если страна имеет некорректную форму (например, "12" или "USA"), она пропускается.

Вариант: Если вариант имеет корректную форму, каждый его сегмент (разделённый символами '-' или '_') выводится как подтег. В противном случае:

если все сегменты соответствуют [0-9a-zA-Z]{1,8} (например, "WIN" или "Oracle_JDK_Standard_Edition"), первый сегмент с некорректной формой и все последующие будут добавлены к подтегу частного использования. Первым добавленным подтегом будет "lvariant", после него в исходном порядке следуют сегменты, разделённые дефисами. Например, "x-lvariant-WIN", "Oracle-x-lvariant-JDK-Standard-Edition".
если какой-либо сегмент не соответствует [0-9a-zA-Z]{1,8}, вариант усекается, а проблемный сегмент и все последующие пропускаются. Если оставшаяся часть не пуста, она выводится как подтег частного использования, как описано выше (даже если оставшаяся часть имеет корректную форму). Например, "Solaris_isjustthecoolestthing" выводится как "x-lvariant-Solaris", а не как "solaris".

Особые преобразования: Для обеспечения совместимости Java поддерживает некоторые устаревшие представления локалей, включая устаревшие коды языков ISO. Этот метод выполняет следующие преобразования:

Устаревшие коды языков ISO "iw", "ji" и "in" преобразуются соответственно в "he", "yi" и "id".
Локаль с языком "no", страной "NO" и вариантом "NY", обозначающая норвежский нюнорск (Норвегия), преобразуется в языковую метку "nn-NO".

Примечание: Хотя языковая метка, полученная этим методом, имеет корректную форму (соответствует синтаксическим требованиям спецификации IETF BCP 47), она не обязательно является допустимой языковой меткой BCP 47. Например,

  Locale.forLanguageTag("xx-YY").toLanguageTag();

вернёт "xx-YY", но подтег языка "xx" и подтег региона "YY" недопустимы, поскольку они не зарегистрированы в реестре языковых подтегов IANA.

Возвращает:

языковую метку BCP47, представляющую локаль

Начиная с версии:

1.7

См. также:

caseFoldLanguageTag

public static String caseFoldLanguageTag(String languageTag)

Возвращает языковую метку IETF BCP 47 с нормализованным регистром.

Этот метод форматирует языковую метку, приводя её к соглашениям об использовании регистра, соответствующим разделу 2.1.1 «Форматирование языковых меток» RFC5646. Формат определён следующим образом: Все подтеги, включая подтеги расширений и частного использования, записываются строчными буквами, за двумя исключениями: двухбуквенные и четырёхбуквенные подтеги, которые не стоят в начале метки и не следуют за односимвольными подтегами. Такие двухбуквенные подтеги записываются прописными буквами (как в метках "en-CA-x-ca" или "sgn-BE-FR"), а четырёхбуквенные — с заглавной буквы (как в метке "az-Latn-x-latn"). Поскольку устаревшие метки (определённые в RFC5646 как "grandfathered") не всегда имеют корректную форму, этот метод просто нормализует регистр устаревшей метки в соответствии с точными правилами для конкретной метки, указанными в соответствующей таблице Legacy tags.

Особые исключения

Для обеспечения согласованности с variant, в котором регистр имеет значение, этот метод не нормализует регистр подтегов вариантов и подтегов частного использования с префиксом lvariant.

Например:

String tag = "ja-kana-jp-x-lvariant-Oracle-JDK-Standard-Edition";
Locale.caseFoldLanguageTag(tag); // returns "ja-Kana-JP-x-lvariant-Oracle-JDK-Standard-Edition"
String tag2 = "ja-kana-jp-x-Oracle-JDK-Standard-Edition";
Locale.caseFoldLanguageTag(tag2); // returns "ja-Kana-JP-x-oracle-jdk-standard-edition"

Помимо нормализации регистра, этот метод не вносит изменений в саму метку. Регистр символов в языковых метках не несёт смысловой нагрузки; его использование лишь рекомендуется, поскольку оно соответствует различным стандартам ISO, включая ISO639-1, ISO15924 и ISO3166-1.

Поскольку форматирование регистра зависит от расположения определённых подтегов, вызывающий код должен убедиться, что языковая метка имеет корректную форму (соответствует разделу 2.1 «Синтаксис» RFC5646).

Параметры:

languageTag — языковая метка IETF BCP 47.

Возвращает:

языковую метку IETF BCP 47 с нормализованным регистром

Выбрасывает:

IllformedLocaleException — если languageTag имеет некорректную форму

NullPointerException — если languageTag имеет значение null

Начиная с версии:

Внешние спецификации

forLanguageTag

public static Locale forLanguageTag(String languageTag)

Возвращает локаль для указанной строки языковой метки IETF BCP 47.

Если указанная языковая метка содержит подтеги с некорректной формой, этот подтег и все следующие за ним подтеги игнорируются. Сравните с методом Locale.Builder.setLanguageTag(String), который в таком случае выбрасывает исключение.

Выполняются следующие преобразования:

Код языка "und" преобразуется в язык "".
Коды языков "iw", "ji" и "in" преобразуются соответственно в "he", "yi" и "id". (Такая же канонизация выполняется в конструкторах Locale.) Дополнительные сведения см. в разделе Устаревшие коды языков.
Часть подтега частного использования, начинающаяся с "lvariant", если она есть, удаляется и добавляется к полю варианта результирующей локали (без нормализации регистра). Если после этого подтег становится пустым, он отбрасывается:
```
    Locale loc;
    loc = Locale.forLanguageTag("en-US-x-lvariant-POSIX");
    loc.getVariant(); // returns "POSIX"
    loc.getExtension('x'); // returns null

    loc = Locale.forLanguageTag("de-POSIX-x-URP-lvariant-Abc-Def");
    loc.getVariant(); // returns "POSIX_Abc_Def"
    loc.getExtension('x'); // returns "urp"
```
Языковые метки BCP 47 допускают до трёх подтегов extlang. Однако второй и третий подтеги extlang всегда игнорируются. Поэтому первый подтег extlang в languageTag используется как язык, а первичный подтег языка и остальные подтеги extlang игнорируются. Языковые метки, содержащие более трёх подтегов extlang, считаются имеющими некорректную форму начиная с лишнего подтега extlang.
```
    Locale.forLanguageTag("ar-aao").getLanguage(); // returns "aao"
    Locale.forLanguageTag("en-abc-def-us").toString(); // returns "abc_US"
    Locale.forLanguageTag("zh-yue-gan-cmn-czh-CN").toString();
    // returns "yue"; "czh" exceeds the extlang limit, and subsequent
    // subtags are considered ill-formed
```
Регистр нормализуется, за исключением тегов вариантов, которые остаются без изменений. Регистр языка приводится к нижнему, письменности — к заглавному, страны — к верхнему, а расширений — к нижнему.
Если после обработки локаль в точности совпадает с ja_JP_JP или th_TH_TH и не содержит расширений, добавляются соответствующие расширения, как если бы был вызван конструктор:
```
   Locale.forLanguageTag("ja-JP-x-lvariant-JP").toLanguageTag();
   // returns "ja-JP-u-ca-japanese-x-lvariant-JP"
   Locale.forLanguageTag("th-TH-x-lvariant-TH").toLanguageTag();
   // returns "th-TH-u-nu-thai-x-lvariant-TH"
```

Реализуется продукция 'Language-Tag' из BCP47, поэтому поддерживаются как устаревшие (регулярные и нерегулярные, обозначенные в BCP47 как "Type: grandfathered"), так и языковые метки частного использования. Самостоятельные метки частного использования представляются пустым языком и расширением 'x-whatever', а устаревшие метки преобразуются в соответствующие канонические замены, если они существуют.

Устаревшие метки, имеющие канонические замены:

Устаревшие метки, имеющие канонические замены
устаревшая метка	современная замена
art-lojban	jbo
i-ami	ami
i-bnn	bnn
i-hak	hak
i-klingon	tlh
i-lux	lb
i-navajo	nv
i-pwn	pwn
i-tao	tao
i-tay	tay
i-tsu	tsu
no-bok	nb
no-nyn	nn
sgn-BE-FR	sfb
sgn-BE-NL	vgt
sgn-CH-DE	sgg
zh-guoyu	cmn
zh-hakka	hak
zh-min-nan	nan
zh-xiang	hsn

Устаревшие метки, не имеющие современной замены, преобразуются следующим образом:

Устаревшие метки, не имеющие современной замены
устаревшая метка	преобразуется в
cel-gaulish	xtg-x-cel-gaulish
en-GB-oed	en-GB-x-oed
i-default	en-x-i-default
i-enochian	und-x-i-enochian
i-mingo	see-x-i-mingo
zh-min	nan-x-zh-min

Список всех устаревших меток см. в реестре языковых подтегов IANA (выполните поиск по строке "Type: grandfathered").

Примечание: нет гарантии, что toLanguageTag и forLanguageTag будут взаимно обратимыми.

Параметры:

languageTag — языковая метка

Возвращает:

Локаль, которая наилучшим образом представляет языковую метку.

Выбрасывает:

NullPointerException — если languageTag имеет значение null

Начиная с версии:

1.7

См. также:

getISO3Language

public String getISO3Language() throws MissingResourceException

Возвращает трёхбуквенное сокращение языка этой локали. Если язык соответствует двухбуквенному коду ISO 639-1, возвращается соответствующий трёхбуквенный код ISO 639-2/T в нижнем регистре. Коды языков ISO 639-2 можно найти в Интернете; см. "Codes for the Representation of Names of Languages Part 2: Alpha-3 Code". Если в локали указан трёхбуквенный язык, он возвращается без изменений. Если язык в локали не указан, возвращается пустая строка.

Возвращает:: трёхбуквенное сокращение языка этой локали
Выбрасывает:: MissingResourceException — выбрасывает MissingResourceException, если для этой локали недоступно трёхбуквенное сокращение языка.

getISO3Country

public String getISO3Country() throws MissingResourceException

Возвращает трёхбуквенное сокращение страны этой локали. Если страна соответствует двухбуквенному коду ISO 3166-1 alpha-2, возвращается соответствующий трёхбуквенный код ISO 3166-1 alpha-3 в верхнем регистре. Если страна в локали не указана, возвращается пустая строка.

Коды ISO 3166-1 можно найти в Интернете.

Возвращает:: трёхбуквенное сокращение страны этой локали
Выбрасывает:: MissingResourceException — выбрасывает MissingResourceException, если для этой локали недоступно трёхбуквенное сокращение страны.

getDisplayLanguage

public final String getDisplayLanguage()

Возвращает название языка локали, подходящее для отображения пользователю. По возможности возвращаемое название локализуется для локали по умолчанию DISPLAY. Например, если локаль — fr_FR, а локаль по умолчанию DISPLAY — en_US, getDisplayLanguage() вернёт "French"; если локаль — en_US, а локаль по умолчанию DISPLAY — fr_FR, getDisplayLanguage() вернёт "anglais". Если возвращаемое название нельзя локализовать для локали по умолчанию DISPLAY, функция использует английское название, а в крайнем случае — код ISO. Если в локали не указан язык, эта функция возвращает пустую строку.

Возвращает:: Отображаемое название языка.

getDisplayLanguage

public String getDisplayLanguage(Locale inLocale)

Возвращает название языка локали, подходящее для отображения пользователю. По возможности возвращаемое название локализуется в соответствии с inLocale. Например, если локаль — fr_FR, а inLocale — en_US, getDisplayLanguage() вернёт "French"; если локаль — en_US, а inLocale — fr_FR, getDisplayLanguage() вернёт "anglais". Если возвращаемое название нельзя локализовать в соответствии с inLocale, функция использует английское название, а в крайнем случае — код ISO. Если в локали не указан язык, эта функция возвращает пустую строку.

Параметры:: inLocale — локаль, для которой нужно получить отображаемое название языка.
Возвращает:: Отображаемое название языка, соответствующее указанной локали.
Выбрасывает:: NullPointerException — если inLocale имеет значение null

getDisplayScript

public String getDisplayScript()

Возвращает название письменности локали, подходящее для отображения пользователю. По возможности название локализуется для локали по умолчанию DISPLAY. Если в этой локали не указан код письменности, возвращается пустая строка.

Возвращает:: отображаемое название кода письменности для текущей локали по умолчанию DISPLAY
Начиная с версии:: 1.7

getDisplayScript

public String getDisplayScript(Locale inLocale)

Возвращает название письменности локали, подходящее для отображения пользователю. По возможности название локализуется для указанной локали. Если в этой локали не указан код письменности, возвращается пустая строка.

Параметры:: inLocale — локаль, для которой нужно получить отображаемое название письменности.
Возвращает:: отображаемое название кода письменности для текущей локали по умолчанию DISPLAY
Выбрасывает:: NullPointerException — если inLocale имеет значение null
Начиная с версии:: 1.7

getDisplayCountry

public final String getDisplayCountry()

Возвращает название страны локали, подходящее для отображения пользователю. По возможности возвращаемое название локализуется для локали по умолчанию DISPLAY. Например, если локаль — fr_FR, а локаль по умолчанию DISPLAY — en_US, getDisplayCountry() вернёт "France"; если локаль — en_US, а локаль по умолчанию DISPLAY — fr_FR, getDisplayCountry() вернёт "Etats-Unis". Если возвращаемое название нельзя локализовать для локали по умолчанию DISPLAY, функция использует английское название, а в крайнем случае — код ISO. Если в локали не указана страна, эта функция возвращает пустую строку.

Возвращает:: Название страны, соответствующее локали.

getDisplayCountry

public String getDisplayCountry(Locale inLocale)

Возвращает название страны локали, подходящее для отображения пользователю. По возможности возвращаемое название локализуется в соответствии с inLocale. Например, если локаль — fr_FR, а inLocale — en_US, getDisplayCountry() вернёт "France"; если локаль — en_US, а inLocale — fr_FR, getDisplayCountry() вернёт "Etats-Unis". Если возвращаемое название нельзя локализовать в соответствии с inLocale, функция использует английское название, а в крайнем случае — код ISO. Если в локали не указана страна, эта функция возвращает пустую строку.

Параметры:: inLocale — локаль, для которой нужно получить отображаемое название страны.
Возвращает:: Название страны, соответствующее указанной локали.
Выбрасывает:: NullPointerException — если inLocale имеет значение null

getDisplayVariant

public final String getDisplayVariant()

Возвращает название кода варианта локали, подходящее для отображения пользователю. По возможности название локализуется для локали по умолчанию DISPLAY. Если в локали не указан код варианта, эта функция возвращает пустую строку.

Возвращает:: Отображаемое название кода варианта, соответствующее локали.

getDisplayVariant

public String getDisplayVariant(Locale inLocale)

Возвращает название кода варианта локали, подходящее для отображения пользователю. По возможности название локализуется для inLocale. Если в локали не указан код варианта, эта функция возвращает пустую строку.

Параметры:: inLocale — локаль, для которой нужно получить отображаемый код варианта.
Возвращает:: Отображаемое название кода варианта, соответствующее указанной локали.
Выбрасывает:: NullPointerException — если inLocale имеет значение null

getDisplayName

public final String getDisplayName()

Возвращает название локали, подходящее для отображения пользователю. Оно составляется из значений, возвращаемых getDisplayLanguage(), getDisplayScript(), getDisplayCountry(), getDisplayVariant(), и необязательных расширений Unicode. Непустые значения используются по порядку; второе и последующие названия заключаются в скобки. Например:

language (script, country, variant(, extension)*)
language (country(, extension)*)
language (variant(, extension)*)
script (country(, extension)*)
country (extension)*

в зависимости от того, какие поля указаны в локали. Разделитель полей в приведённых выше скобках, обозначенный запятой, может локализоваться в зависимости от локали. Если поля языка, письменности, страны и варианта пусты, эта функция возвращает пустую строку.

Возвращает:: Название локали, подходящее для отображения.

getDisplayName

public String getDisplayName(Locale inLocale)

language (script, country, variant(, extension)*)
language (country(, extension)*)
language (variant(, extension)*)
script (country(, extension)*)
country (extension)*

Параметры:: inLocale — локаль, для которой нужно получить отображаемое название.
Возвращает:: Название локали, подходящее для отображения.
Выбрасывает:: NullPointerException — если inLocale имеет значение null

clone

public Object clone()

Переопределяет Cloneable.

Переопределяет:

clone в классе Object

Возвращает:

копию этого экземпляра.

См. также:

hashCode

public int hashCode()

Переопределяет hashCode. Поскольку Locale часто используются в хеш-таблицах, значение кэшируется для повышения скорости.

Переопределяет:

hashCode в классе Object

Возвращает:

хеш-код этого объекта

См. также:

equals

public boolean equals(Object obj)

Возвращает true, если эта Locale равна другому объекту. Locale считается равной другой Locale с идентичными языком, письменностью, страной, вариантом и расширениями и неравной всем остальным объектам.

Переопределяет:

equals в классе Object

Параметры:

obj — объект, с которым выполняется сравнение.

Возвращает:

true, если эта Locale равна указанному объекту.

См. также:

filter

public static List<Locale> filter(List<Locale.LanguageRange> priorityList, Collection<Locale> locales, Locale.FilteringMode mode)

Возвращает список совпадающих экземпляров Locale с использованием механизма фильтрации, определённого в RFC 4647. Эта операция фильтрации для указанного locales гарантирует, что возвращаются только уникальные совпадающие локали.

Параметры:: priorityList — список языковых приоритетов пользователя, в котором каждая языковая метка отсортирована по убыванию приоритета или веса; locales — экземпляры Locale, используемые для сопоставления; mode — режим фильтрации
Возвращает:: список экземпляров Locale для совпадающих языковых меток, отсортированных по убыванию приоритета или веса, либо пустой список, если совпадений нет. Список можно изменять.
Выбрасывает:: NullPointerException — если priorityList или locales имеет значение null; IllegalArgumentException — если указанный список содержит один или несколько расширенных языковых диапазонов, когда задано Locale.FilteringMode.REJECT_EXTENDED_RANGES
Начиная с версии:: 1.8

filter

public static List<Locale> filter(List<Locale.LanguageRange> priorityList, Collection<Locale> locales)

Возвращает список совпадающих экземпляров Locale с использованием механизма фильтрации, определённого в RFC 4647. Эквивалентен методу filter(List, Collection, FilteringMode), если для mode задано значение Locale.FilteringMode.AUTOSELECT_FILTERING. Эта операция фильтрации для указанного locales гарантирует, что возвращаются только уникальные совпадающие локали.

Параметры:: priorityList — список языковых приоритетов пользователя, в котором каждая языковая метка отсортирована по убыванию приоритета или веса; locales — экземпляры Locale, используемые для сопоставления
Возвращает:: список экземпляров Locale для совпадающих языковых меток, отсортированных по убыванию приоритета или веса, либо пустой список, если совпадений нет. Список можно изменять.
Выбрасывает:: NullPointerException — если priorityList или locales имеет значение null
Начиная с версии:: 1.8

filterTags

public static List<String> filterTags(List<Locale.LanguageRange> priorityList, Collection<String> tags, Locale.FilteringMode mode)

Возвращает список совпадающих языковых меток с использованием механизма базовой фильтрации, определённого в RFC 4647. Эта операция фильтрации для указанного tags гарантирует, что возвращаются только уникальные совпадающие метки с сохранением регистра. Если совпавшие метки отличаются регистром, возвращается первая совпавшая метка с сохранением регистра. Например, из совпавших меток "de-ch" и "de-CH" возвращается "de-ch", если для сопоставления в указанном tags первой проверяется "de-ch". Обратите внимание: если указанный tags является неупорядоченным Collection, возвращаемая совпавшая метка из дубликатов может измениться в зависимости от реализации Collection.

Параметры:: priorityList — список языковых приоритетов пользователя, в котором каждая языковая метка отсортирована по убыванию приоритета или веса; tags — языковые метки; mode — режим фильтрации
Возвращает:: список совпадающих языковых меток, отсортированных по убыванию приоритета или веса, либо пустой список, если совпадений нет. Список можно изменять.
Выбрасывает:: NullPointerException — если priorityList или tags имеет значение null; IllegalArgumentException — если указанный список содержит один или несколько расширенных языковых диапазонов, когда задано Locale.FilteringMode.REJECT_EXTENDED_RANGES
Начиная с версии:: 1.8

filterTags

public static List<String> filterTags(List<Locale.LanguageRange> priorityList, Collection<String> tags)

Возвращает список подходящих языковых тегов с использованием базового механизма фильтрации, определённого в RFC 4647. Это эквивалентно filterTags(List, Collection, FilteringMode), если mode — Locale.FilteringMode.AUTOSELECT_FILTERING. Эта операция фильтрации для указанного tags гарантирует, что возвращаются только уникальные подходящие теги с сохранением регистра. Если среди подходящих тегов есть дубликаты, различающиеся регистром, возвращается первый совпавший тег с сохранением регистра. Например, из дублирующихся подходящих тегов «de-ch» и «de-CH» будет возвращён «de-ch», если при проверке на совпадение в указанном tags первым встретился «de-ch». Обратите внимание: если указанный tags является неупорядоченным Collection, возвращаемый подходящий тег из числа дубликатов может измениться в зависимости от реализации Collection.

Параметры:: priorityList — список языковых предпочтений пользователя, в котором языковые теги отсортированы в порядке убывания приоритета или веса; tags — языковые теги
Возвращает:: список подходящих языковых тегов, отсортированных в порядке убывания приоритета или веса, или пустой список, если совпадений нет. Список допускает изменение.
Исключения:: NullPointerException — если priorityList или tags равен null
Начиная с версии:: 1.8

lookup

public static Locale lookup(List<Locale.LanguageRange> priorityList, Collection<Locale> locales)

Возвращает экземпляр Locale для наиболее подходящего языкового тега с использованием механизма поиска, определённого в RFC 4647.

Параметры:: priorityList — список языковых предпочтений пользователя, в котором языковые теги отсортированы в порядке убывания приоритета или веса; locales — экземпляры Locale, используемые для сопоставления
Возвращает:: наиболее подходящий экземпляр Locale, выбранный на основе приоритета или веса, либо null, если совпадений нет.
Исключения:: NullPointerException — если priorityList или locales равен null
Начиная с версии:: 1.8

lookupTag

public static String lookupTag(List<Locale.LanguageRange> priorityList, Collection<String> tags)

Возвращает наиболее подходящий языковой тег с использованием механизма поиска, определённого в RFC 4647. Эта операция поиска для указанного tags гарантирует, что возвращается первый совпавший тег с сохранением регистра.

Параметры:: priorityList — список языковых предпочтений пользователя, в котором языковые теги отсортированы в порядке убывания приоритета или веса; tags — языковые теги, используемые для сопоставления
Возвращает:: наиболее подходящий языковой тег, выбранный на основе приоритета или веса, либо null, если совпадений нет.
Исключения:: NullPointerException — если priorityList или tags равен null
Начиная с версии:: 1.8

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Locale.html