Класс Locale

java.lang.Object

java.util.Locale

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

public final class Locale extends Object implements Cloneable, Serializable

Объект типа Locale представляет собой определённый географический, политический или культурный регион. Операция, для выполнения которой требуется Locale, называется регионально-зависимой и использует Locale для адаптации информации для пользователя. Например, отображение числа — это регионально-зависимая операция; число должно быть отформатировано в соответствии с обычаями и конвенциями страны, региона или культуры пользователя.

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

Объект типа Locale логически состоит из полей, описанных ниже.

язык: Код языка ISO 639 alpha-2 или alpha-3, или зарегистрированные субтеги языка до 8 букв (для будущих улучшений). Если для языка есть и код alpha-2, и код alpha-3, используется код alpha-2. Полный список допустимых кодов языков можно найти в реестре субтегов языка IANA (поиск по "Тип: язык"). Поле языка нечувствительно к регистру, но Locale всегда приводит к нижнему регистру.; Корректные значения языка имеют вид [a-zA-Z]{2,8}. Обратите внимание, что это не полное производство языка BCP47, так как оно исключает extlang. Они не нужны, поскольку современные трехбуквенные коды языков их заменяют.; Пример: "en" (английский), "ja" (японский), "kok" (конкани)
письменность: Код письменности ISO 15924 alpha-4. Полный список допустимых кодов письменности можно найти в реестре субтегов языка IANA (поиск по "Тип: письменность"). Поле письменности нечувствительно к регистру, но Locale всегда приводит к заглавному регистру первой буквы.; Корректные значения письменности имеют вид [a-zA-Z]{4}; Пример: "Latn" (латинская), "Cyrl" (кириллическая)
страна (регион): Код страны ISO 3166 alpha-2 или числовой код области ООН M.49. Полный список допустимых кодов стран и регионов можно найти в реестре субтегов языка IANA (поиск по "Тип: регион"). Поле страны (региона) нечувствительно к регистру, но Locale всегда приводит к верхнему регистру.; Корректные значения страны/региона имеют вид [a-zA-Z]{2} | [0-9]{3}; Пример: "US" (Соединенные Штаты), "FR" (Франция), "029" (Карибский бассейн)
вариант: Любое произвольное значение, используемое для обозначения варианта Locale. Если существует два или более значений варианта, каждое из которых указывает на собственную семантику, эти значения должны быть упорядочены по важности, при этом наиболее важные должны идти первыми, разделенные символом подчеркивания('_'). Поле варианта чувствительно к регистру.

Примечание: IETF BCP 47 устанавливает синтаксические ограничения на подтеги вариантов. Также подтеги BCP 47 строго используются для указания дополнительных вариантов, которые определяют язык или его диалекты, не охватываемые никакими комбинациями подтегов языка, письма и региона. Полный список допустимых кодов вариантов можно найти в реестре подтегов языка IANA (поиск по "Тип: вариант").
Однако поле "variant" в Locale исторически использовалось для любого рода изменений, а не только для языковых вариаций. Например, некоторые поддерживаемые варианты, доступные в средах выполнения Java SE Runtime, указывают альтернативное культурное поведение, такое как тип календаря или система счисления. В BCP 47 такая информация, которая не идентифицирует язык, поддерживается подтегами расширений или подтегами частного использования.; Корректно сформированные значения варианта имеют вид SUBTAG (('_'|'-') SUBTAG)* где SUBTAG = [0-9][0-9a-zA-Z]{3} | [0-9a-zA-Z]{5,8}. (Примечание: BCP 47 использует только дефис ('-') в качестве разделителя, это более гибкий вариант).; Пример: "polyton" (политоническое греческое письмо), "POSIX"
расширения: Карта из ключей, состоящих из одного символа, в строковые значения, указывающие расширения помимо идентификации языка. Расширения в Locale реализуют семантику и синтаксис подтегов расширения BCP 47 и подтегов частного использования. Расширения нечувствительны к регистру, но 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 требует, чтобы значения полей были зарегистрированы в реестре подтегов языка IANA, класс Locale не предоставляет функций валидации. Класс Builder проверяет только, удовлетворяет ли отдельное поле синтаксическим требованиям (корректно сформировано), но не проверяет само значение. Подробности см. в Locale.Builder.

Расширение локалей/языков Unicode

UTS#35, "Unicode Locale Data Markup Language", определяет необязательные атрибуты и ключевые слова для переопределения или уточнения поведения по умолчанию, связанного с локалью. Ключевое слово представлено парой "ключ" и "тип". Например, "nu-thai" указывает, что для форматирования чисел следует использовать тайские локальные цифры (значение: "thai") (ключ: "nu").

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

Таким образом, когда объект Locale содержит атрибуты и ключевые слова локали Unicode, getExtension(UNICODE_LOCALE_EXTENSION) вернет строку, представляющую эту информацию, например, "nu-thai". Класс Locale также предоставляет getUnicodeLocaleAttributes(), getUnicodeLocaleKeys() и getUnicodeLocaleType(java.lang.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.

Строитель

Используя Locale.Builder, вы можете создать объект Locale, соответствующий синтаксису BCP 47.

Методы фабрики

Метод forLanguageTag(java.lang.String) получает объект Locale для хорошо сформированного тега языка BCP 47. Метод of(String, String, String) и его перегрузки получают объект Locale из заданных language, country, и/или variant, определенных выше.

Постоянные значения локали

Класс Locale предоставляет ряд удобных констант, которые вы можете использовать для получения объектов Locale для часто используемых локали. Например, Locale.US является объектом Locale для Соединенных Штатов.

Сопоставление языковых локалей

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

Для сопоставления предпочтительных локалей пользователя с набором тегов языка 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 тегов языка, рассматривается как наиболее подходящий.

Использование Locale

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

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

    NumberFormat.getInstance();
    NumberFormat.getCurrencyInstance();
    NumberFormat.getPercentInstance();

Каждый из этих методов имеет две разновидности: одну с явной локалью и одну без неё; последняя использует локаль по умолчанию FORMAT:

    NumberFormat.getInstance(myLocale);
    NumberFormat.getCurrencyInstance(myLocale);
    NumberFormat.getPercentInstance(myLocale);

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

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

Для сохранения совместимости, конструкторы Locale сохраняют свое поведение до версии Java Runtime Environment 1.7. То же самое в значительной степени относится к методу toString. Таким образом, объекты Locale можно продолжать использовать, как и прежде. В частности, клиенты, которые парсят вывод toString в поля языка, страны и варианта, могут продолжать это делать (хотя это настоятельно не рекомендуется), хотя поле варианта будет содержать дополнительную информацию, если присутствуют скрипт или расширения.

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

Из-за этих проблем рекомендуется, чтобы клиенты перешли от создания несоответствующих локалей и использовали API forLanguageTag и 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" добавляется автоматически.

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

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

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

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

Конструктор 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() не окажут никакого эффекта.

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

Трехбуквенные коды языка/страны (региона)

Конструкторы Locale всегда указывали, что язык и страна должны иметь длину в два символа, хотя на практике они принимали любую длину. Сейчас спецификация смягчена, чтобы разрешать коды языка длиной от двух до восьми символов и коды страны (региона) длиной от двух до трех символов, а также, в частности, трехбуквенные коды языка и трехзначные коды региона, как указано в реестре подтэгов языка IANA. Для совместимости реализация по-прежнему не накладывает ограничений на длину.

Since:

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 устарели.

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

Modifier and Type	Method	Description
`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 (2 буквы) в верхнем регистре, либо 3-значным кодом ООН М.49.
`static Locale`	`getDefault()`	Получает текущее значение локаль по умолчанию для этой инстанции Java Virtual Machine.
`static Locale`	`getDefault(Locale.Category category)`	Получает текущее значение локаль по умолчанию для указанной категории для этой инстанции Java Virtual Machine.

`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` список кодов стран ISO3166 для указанного типа.
`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)`	Устанавливает локаль по умолчанию для этого экземпляра Java Virtual Machine.
`static void`	`setDefault(Locale.Category category, Locale newLocale)`	Устанавливает локаль по умолчанию для указанной категории в этом экземпляре Java Virtual Machine.
`Locale`	`stripExtensions()`	Возвращает копию этого `Locale` без расширений.
`String`	`toLanguageTag()`	Возвращает корректный тег языка IETF BCP 47, представляющий эту локаль.
`final String`	`toString()`	Возвращает строковое представление этого объекта `Locale`, состоящее из языка, страны, варианта, скрипта и расширений, как показано ниже: язык + "_" + страна + "_" + (вариант + "_#" \| "#") + скрипт + "_" + расширения. Язык всегда в нижнем регистре, страна — всегда в верхнем регистре, скрипт — всегда в заглавном регистре, а расширения — всегда в нижнем регистре.

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

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

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

АНГЛИЙСКИЙ

public static final Locale ENGLISH

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

ФРАНЦУЗСКИЙ

public static final Locale FRENCH

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

НЕМЕЦКИЙ

public static final Locale GERMAN

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

ИТАЛЬЯНСКИЙ

public static final Locale ITALIAN

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

ЯПОНСКИЙ

public static final Locale JAPANESE

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

КОРЕЙСКИЙ

public static final Locale KOREAN

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

КИТАЙСКИЙ

public static final Locale CHINESE

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

УПРОЩЁННЫЙ КИТАЙСКИЙ

public static final Locale SIMPLIFIED_CHINESE

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

ТРАДИЦИОННЫЙ КИТАЙСКИЙ

public static final Locale TRADITIONAL_CHINESE

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

ФРАНЦИЯ

public static final Locale FRANCE

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

ГЕРМАНИЯ

public static final Locale GERMANY

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

ИТАЛИЯ

public static final Locale ITALY

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

ЯПОНИЯ

public static final Locale JAPAN

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

КОРЕЯ

public static final Locale KOREA

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

ВЕЛИКОБРИТАНИЯ

public static final Locale UK

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

США

public static final Locale US

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

КАНАДА

public static final Locale CANADA

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

КАНАДА (ФРАНЦУЗСКИЙ)

public static final Locale CANADA_FRENCH

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

ROOT

public static final Locale ROOT

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

Since:: 1.6

КИТАЙ

public static final Locale CHINA

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

КНР

public static final Locale PRC

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

ТАЙВАНЬ

public static final Locale TAIWAN

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

PRIVATE_USE_EXTENSION

public static final char PRIVATE_USE_EXTENSION

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

Since:

1.7

См. также:

UNICODE_LOCALE_EXTENSION

public static final char UNICODE_LOCALE_EXTENSION

Ключ для расширения языка Юникод ('u').

Since:

1.7

См. также:

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

Регион

@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 или числовой код зоны ООН M.49. См. описание класса Locale относительно допустимых значений страны.

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

Исключения:

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

Локализация

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

Устаревший.

Конструкторы Locale устарели. См. Получение локали для других вариантов.

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

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

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

Параметры:

language - Код языка ISO 639 alpha-2 или alpha-3, или языковой подтег длиной до 8 символов. См. описание класса Locale о допустимых значениях языка.

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

Исключения:

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

Локализация

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

Устаревший.

Конструкторы Locale устарели. См. Получение локали для других вариантов.

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

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

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

Параметры:

Исключения:

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

С:

1.4

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

of

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

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

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

Этот метод не выполняет никаких синтаксических проверок входных данных. Используйте Locale.Builder для полной синтаксической проверки в соответствии с BCP47.
Два случая ("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)

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

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

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

Параметры:

language - Код языка. См. описание класса Locale значений языка.

country - Код страны. См. описание класса Locale значений страны.

Возвращает:

Объект Locale

Исключения:

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

С:

of

public static Locale of(String language)

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

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

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

Параметры:

language - Код языка. См. описание класса Locale для значений языка.

Возвращает:

Объект Locale

Исключение:

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

С версии:

getDefault

public static Locale getDefault()

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

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

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

getDefault

public static Locale getDefault(Locale.Category category)

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

Параметры:

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

Возвращает:

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

Исключение:

NullPointerException - если категория равна null

С версии:

1.7

См. также:

setDefault

public static void setDefault(Locale newLocale)

Устанавливает локаль по умолчанию для этого экземпляра Java Virtual Machine. Это не влияет на локаль хоста.

Если существует менеджер безопасности, его метод checkPermission вызывается с разрешением PropertyPermission("user.language", "write") перед изменением локали по умолчанию.

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

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

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

Параметры:

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

Исключения:

SecurityException - если менеджер безопасности существует, и его метод checkPermission не разрешает операцию.

NullPointerException - если newLocale равно null

См. также:

Установить значение по умолчанию

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

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

Если есть менеджер безопасности, его метод checkPermission вызывается с разрешением PropertyPermission("user.language", "write"), прежде чем будет изменена локаль по умолчанию.

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

Параметры:

category - указанная категория для установки локали по умолчанию

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

Исключения:

SecurityException - если менеджер безопасности существует и его метод checkPermission не разрешает операцию.

NullPointerException - если категория и/или newLocale равны null

С:

1.7

См. также:

Получить доступные локали

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. Может использоваться для получения локалей. Этот метод эквивалентен getISOCountries(Locale.IsoCountryCode type) с type Locale.IsoCountryCode.PART1_ALPHA2.

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

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

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

getISOCountries

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

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

Параметры:

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

Возвращает:

a Set кодов стран ISO3166 для указанного типа

Бросает:

NullPointerException - если тип равен null

С момента:

См. также:

getISOLanguages

public static String[] getISOLanguages()

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

Примечание:

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

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

getLanguage

public String getLanguage()

Возвращает код языка данного Locale.

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

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

Возвращает:

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

См. также:

getScript

public String getScript()

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

Возвращает:

Код сценария или пустую строку, если он не определён.

С тех пор:

1.7

См. также:

getCountry

public String getCountry()

Возвращает код страны/региона для данного locale, который должен быть либо пустой строкой, либо двухбуквенным кодом ISO 3166 в верхнем регистре, либо трёхзначным кодом ООН М.49.

Возвращает:

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

См. также:

getVariant

public String getVariant()

Возвращает код варианта для данного locale.

Возвращает:

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

См. также:

END_OF_DOCUMENT_MARKER

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()

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

Возвращает:: Набор атрибутов.
С момента:: 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

END_OF_DOCUMENT_MARKER

toString

public final String toString()

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

язык + "_" + страна + "_" + (вариант + "_#" | "#") + скрипт + "_" + расширения

Язык всегда в нижнем регистре, страна — всегда в верхнем регистре, скрипт — всегда в заглавных буквах, а расширения — всегда в нижнем регистре. Расширения и подтеги частного использования будут в каноническом порядке, как объяснено в 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

Overrides:

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) не всегда имеют правильный формат, этот метод просто приведёт устаревший тег к нижнему регистру, чтобы он соответствовал правилам нижнего регистра для конкретного указанного тега в таблице 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(java.lang.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"
```
Когда аргумент languageTag содержит подтег extlang, используется первый такой подтег в качестве языка, а основной подтег языка и другие подтеги extlang игнорируются:
```
    Locale.forLanguageTag("ar-aao").getLanguage(); // returns "aao"
    Locale.forLanguageTag("en-abc-def-us").toString(); // returns "abc_US"
```
Регистр нормализуется, за исключением тегов варианта, которые остаются неизменными. Язык нормализуется до нижнего регистра, сценарий — до верхнего регистра, страна — до верхнего регистра, и расширения — до нижнего регистра.
Если после обработки локаль точно совпадает с либо 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) и подтеги частного использования. Самостоятельные подтеги частного использования представлены пустым языком и расширением 'x-whatever', а устаревшие теги преобразуются в их канонические замены, если они существуют.

Устаревшие теги с каноническими заменами следующие:

Legacy tags with canonical replacements
legacy tag	modern replacement
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

Legacy tags with no modern replacement will be converted as follows:

Legacy tags with no modern replacement
legacy tag	converts to
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

For a list of all legacy tags, see the IANA Language Subtag Registry (search for "Type: grandfathered").

Note: there is no guarantee that toLanguageTag and forLanguageTag will round-trip.

Параметры:

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, возвращается соответствующий трехбуквенный код ISO 3166-1 в верхнем регистре. Если локаль не указывает страну, возвращается пустая строка.

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

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

getDisplayLanguage

public final String getDisplayLanguage()

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

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

getDisplayLanguage

public String getDisplayLanguage(Locale inLocale)

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

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

getDisplayScript

public String getDisplayScript()

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

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

getDisplayScript

public String getDisplayScript(Locale inLocale)

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

Parameters:: inLocale - Язык, для которого необходимо получить имя скрипта.
Returns:: отображаемое имя кода скрипта для текущего языка по умолчанию DISPLAY
Throws:: NullPointerException - если inLocale является null
Since:: 1.7

getDisplayCountry

public final String getDisplayCountry()

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

Returns:: Имя страны, соответствующее языку.

getDisplayCountry

public String getDisplayCountry(Locale inLocale)

Возвращает имя страны для локали, подходящее для отображения пользователю. Если возможно, возвращаемое имя будет локализовано в соответствии с inLocale. Например, если локаль — fr_FR, а inLocale — en_US, getDisplayCountry() вернёт «Франция»; если локаль — en_US, а inLocale — fr_FR, getDisplayCountry() вернёт «Соединённые Штаты». Если имя не может быть локализовано в соответствии с 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, собранные в одну строку. Непустые значения используются в порядке следования, а последующие имена помещаются в скобки. Например:

язык (письменность, страна, вариант(, расширение)*)
язык (страна(, расширение)*)
язык (вариант(, расширение)*)
письменность (страна(, расширение)*)
страна (расширение)*

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

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

getDisplayName

public String getDisplayName(Locale inLocale)

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

язык (письменность, страна, вариант(, расширение)*)
язык (страна(, расширение)*)
язык (вариант(, расширение)*)
письменность (страна(, расширение)*)
страна (расширение)*

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

клон

public Object clone()

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

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

clone в классе Object

Возвращает:

клонированный экземпляр.

См. также:

hashCode

public int hashCode()

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

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

hashCode в классе Object

Возвращает:

значение хэш-кода для этого объекта.

См. также:

equals

public boolean equals(Object obj)

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

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

equals в классе Object

Параметры:

obj - объект-ссылка для сравнения.

Возвращает:

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

См. также:

фильтр

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

фильтр

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", если "de-ch" проверяется первым на соответствие в заданном tags. Обратите внимание, что если заданный 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", если "de-ch" проверяется на соответствие в заданных tags. Обратите внимание, что если заданные tags являются неупорядоченным Collection, возвращаемый соответствующий тег из дублирующих тегов может меняться в зависимости от реализации Collection.

Parameters:: priorityList - список приоритетов языка пользователя, в котором каждый языковой тег отсортирован в порядке убывания приоритета или веса; tags - языковые теги
Returns:: список соответствующих языковых тегов, отсортированных в порядке убывания приоритета или веса, или пустой список, если ничего не соответствует. Список можно изменить.
Throws:: NullPointerException - если priorityList или tags null
Since:: 1.8

lookup

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

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

Parameters:: priorityList - список приоритетов языка пользователя, в котором каждый языковой тег отсортирован в порядке убывания приоритета или веса; locales - экземпляры Locale для сопоставления
Returns:: экземпляр лучшего соответствующего Locale , выбранный на основе приоритета или веса, или null , если ничего не соответствует.
Throws:: NullPointerException - если priorityList или locales null
Since:: 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, 2023, 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/21/docs/api/java.base/java/util/Locale.html