Класс 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 alpha-2/alpha-3 или зарегистрированный языковой подстановочный код длиной до 8 букв (для будущих расширений). Если для языка существуют коды alpha-2 и alpha-3, необходимо использовать код alpha-2.; Правила регистра: language не чувствителен к регистру, но Locale всегда приводит символы к нижнему регистру.; Синтаксис: Правильно сформированные значения language имеют вид [a-zA-Z]{2,8}.; Отклонение от BCP 47: Locale не сохраняет подстановочный код extlang. Это объясняется тем, что предпочтение отдаётся трёхбуквенным языковым кодам, а не подстановочным кодам extlang. Если Locale создаётся из языкового тега, содержащего подстановочный код extlang, первый подстановочный код extlang интерпретируется как поле язык. Основной языковой подстановочный код и любые последующие подстановочные коды extlang игнорируются.; Пример: «en» (английский), «ja» (японский), «kok» (конкани)
письменность: Код письменности ISO 15924 alpha-4.; Правила регистра: script не чувствителен к регистру, но Locale всегда приводит символы к регистру заголовка (первая буква заглавная, остальные строчные).; Синтаксис: Правильно сформированные значения script имеют вид [a-zA-Z]{4}; Пример: «Latn» (латиница), «Cyrl» (кириллица)
страна (регион): Код страны ISO 3166 alpha-2 или числовой код территории ООН 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 использует в качестве разделителя только дефис («-»), и API, предоставляемые Locale и принимающие языковые теги BCP 47, ожидают именно такой формат. Однако для обратной совместимости Locale.Builder.setVariant(String) также принимает знак подчёркивания («_»). of(String, String, String) принимает только знак подчёркивания («_»).; Пример: «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 не проверяет, зарегистрированы ли подстановочные коды в Реестре подстановочных кодов. Locale.Builder проверяет только соответствие отдельного поля синтаксическим требованиям (правильность его формирования). При передаче повторяющихся вариантов Builder принимает их и включает в результат. При передаче повторяющихся одиночных кодов расширений


Builder

принимает их, но игнорирует повторяющийся ключ и связанное с ним значение. И наоборот, Locale::of и его перегруженные версии вообще не проверяют, правильно ли сформированы входные данные.

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

UTS#35, «Язык разметки данных локали Unicode», определяет расширение U Unicode BCP 47 — расширение на основе RFC 6067, описывающее необязательные атрибуты и ключевые слова для переопределения или уточнения поведения по умолчанию, связанного с локалью. Ключевое слово представляется парой из ключа и типа. Например, «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} (это один подстановочный код той же формы, что и подстановочный код типа локали). Повторяющиеся атрибуты и ключи локали не несут дополнительного смысла. Методы в Locale и Locale.Builder, принимающие расширения, допускают повторяющиеся атрибуты и ключи локали, а также связанные с ними типы, но игнорируют их.

Расширение локали 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) и его перегруженные версии сохраняют поведение, существовавшее до версии среды выполнения Java 1.7. То есть длина входных параметров не ограничивается. В целом такое же сохранение прежнего поведения относится и к методу 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 с одним из трёх устаревших языковых кодов — iw, ji или in — язык будет преобразован в современный эквивалент: соответственно he, yi или id.

Механизм поиска ресурсов по умолчанию также выполняет это преобразование, поэтому ресурсы можно именовать с использованием любого из вариантов; см. 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, если этот объект Locale равен другому объекту.
`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.
`String`	`getDisplayCountry()`	Возвращает название страны локали `this`, подходящее для отображения пользователю.
`String`	`getDisplayCountry(Locale inLocale)`	Возвращает название страны локали `this`, подходящее для отображения пользователю.
`String`	`getDisplayLanguage()`	Возвращает название языка локали `this`, подходящее для отображения пользователю.
`String`	`getDisplayLanguage(Locale inLocale)`	Возвращает название языка локали `this`, подходящее для отображения пользователю.
`String`	`getDisplayName()`	Возвращает название локали `this`, подходящее для отображения пользователю.
`String`	`getDisplayName(Locale inLocale)`	Возвращает название локали `this`, подходящее для отображения пользователю.
`String`	`getDisplayScript()`	Возвращает название письменности локали `this`, подходящее для отображения пользователю.
`String`	`getDisplayScript(Locale inLocale)`	Возвращает название письменности локали `this`, подходящее для отображения пользователю.
`String`	`getDisplayVariant()`	Возвращает код варианта локали `this` в виде названия, подходящего для отображения пользователю.
`String`	`getDisplayVariant(Locale inLocale)`	Возвращает код варианта локали `this` в виде названия, подходящего для отображения пользователю.
`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`, состоящее из языка, страны, варианта, письменности и расширений в следующем формате: language + "_" + country + "_" + (variant + "_#" \| "#") + script + "_" + extensions. Язык всегда записывается в нижнем регистре, страна — в верхнем, письменность — с заглавной буквы, а расширения — в нижнем регистре.

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

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

Модификатор и тип	Метод	Описание
`protected void`	`finalize()`	Устарел и подлежит удалению: этот элемент API может быть удален в будущей версии. Финализация устарела и может быть удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного промежутка реального времени.

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

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 из 3 цифр. Сведения о допустимых значениях страны см. в описании класса 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 — если категория равна null

Начиная с:

1.7

См. также:

setDefault

public static void setDefault(Locale newLocale)

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

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

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

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

setDefault

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

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

Параметры:

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

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

Исключения:

NullPointerException — если категория и/или 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 кодов стран ISO 3166 указанного типа.

Параметры:

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

Возвращает:

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

Исключения:

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

Начиная с:

См. также:

getISOLanguages

public static String[] getISOLanguages()

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

Примечание:

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

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

getLanguage

public String getLanguage()

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

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

Этот метод возвращает новые формы устаревших кодов 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, состоящее из языка, страны, варианта, письменности и расширений, как показано ниже:

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

Язык всегда записывается строчными буквами, страна — заглавными, письменность — с заглавной первой буквы, а расширения — строчными. Расширения и подтеги частного использования располагаются в каноническом порядке, как описано в 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 «Форматирование языковых меток» RFC 5646. Формат определяется следующим образом: Все подтеги, включая подтеги расширений и частного использования, записываются строчными буквами, за двумя исключениями: двухбуквенные и четырёхбуквенные подтеги, которые не находятся в начале метки и не следуют за односимвольными подтегами. Такие двухбуквенные подтеги записываются заглавными буквами (как в метках "en-CA-x-ca" или "sgn-BE-FR"), а четырёхбуквенные — с заглавной первой буквы (как в метке "az-Latn-x-latn"). Поскольку устаревшие метки (определённые в RFC 5646 как "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 «Синтаксис» RFC 5646).

Параметры:

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), который в этом случае выбрасывает исключение.

Повторяющиеся варианты принимаются и включаются построителем. Однако повторяющиеся ключи расширений-одиночек и связанные с ними типы принимаются, но игнорируются. Такое же поведение применяется к повторяющимся ключам локали и атрибутам в расширении U. Обратите внимание: последующие подтеги после повторного значения не игнорируются.

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

Код языка "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 можно найти в Интернете; см. «Коды для представления названий языков. Часть 2: код Alpha-3». Если в локали указан трёхбуквенный язык, он возвращается без изменений. Если язык в локали не указан, возвращается пустая строка.

Возвращает:: трёхбуквенное сокращение языка этой локали
Выбрасывает:: 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 String getDisplayLanguage()

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

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

getDisplayLanguage

public String getDisplayLanguage(Locale inLocale)

Возвращает название языка локали this, подходящее для отображения пользователю. Если возможно, возвращаемое название будет локализовано в соответствии с 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()

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

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

getDisplayScript

public String getDisplayScript(Locale inLocale)

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

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

getDisplayCountry

public String getDisplayCountry()

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

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

getDisplayCountry

public String getDisplayCountry(Locale inLocale)

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

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

getDisplayVariant

public String getDisplayVariant()

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

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

getDisplayVariant

public String getDisplayVariant(Locale inLocale)

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

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

getDisplayName

public String getDisplayName()

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

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

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

Возвращает:: Отображаемое название, подходящее для локали DISPLAY по умолчанию.

getDisplayName

public String getDisplayName(Locale inLocale)

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

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

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

clone

public Object clone()

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

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

clone в классе Object

Возвращает:

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

См. также:

hashCode

public int hashCode()

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

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

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. Может быть выброшено NullPointerException, если какие-либо элементы в любом из Collection равны 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. Может быть выброшено NullPointerException, если какие-либо элементы в любом из Collection равны 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. NullPointerException может быть выброшено, если какие-либо элементы в любом из Collection имеют значение 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. NullPointerException может быть выброшено, если какие-либо элементы в любом из Collection имеют значение 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. NullPointerException может быть выброшено, если какие-либо элементы в любом из Collection имеют значение 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. NullPointerException может быть выброшено, если какие-либо элементы в любом из Collection имеют значение 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.