Spec-Zone.ru › OpenJDK 24

Класс 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 (например, поиск по "Тип: регион").

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

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

UTS#35, "Язык разметки данных локали Unicode", определяет необязательные атрибуты и ключевые слова для переопределения или уточнения поведения по умолчанию, связанного с локалью. Ключевое слово представляется парой ключ-тип. Например, "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(String), которые обеспечивают прямой доступ к атрибутам локали Unicode и парам ключ-тип. При представлении в виде строки расширение локали Unicode перечисляет атрибуты в алфавитном порядке, за которым следуют последовательности ключ-тип, ключи в алфавитном порядке (порядок подтегов, составляющих тип ключа, фиксирован при определении типа).

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

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

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

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

  1. Перечисленные ниже системные свойства, связанные с локалью, устанавливаются из среды хоста. Некоторые системные свойства (за исключением user.language) могут не иметь значений из среды хоста.
    Показывает ключи свойств и соответствующие значения
    Ключ системного свойства, связанного с локалью Описание
    user.language language для локальной настройки по умолчанию, например, "en" (английский)
    user.script script для локальной настройки по умолчанию, например, "Latn" (латинский)
    user.country country для локальной настройки по умолчанию, например, "US" (Соединенные Штаты)
    user.variant variant для локальной настройки по умолчанию, например, "POSIX"
    user.extensions extensions для локальной настройки по умолчанию, например, "u-ca-japanese" (японский календарь)
  2. Значения этих системных свойств могут быть переопределены значениями, заданными во время запуска. Если значение свойства user.extensions не может быть обработано, оно игнорируется. Значения других свойств, которые переопределяются, не проверяются на синтаксис или корректность и используются непосредственно в локальной настройке по умолчанию. (Как правило, значения системных свойств могут быть заданы с помощью параметра командной строки -D запускаемого приложения. Например, указание -Duser.extensions=foobarbaz приводит к локальной настройке по умолчанию без расширений, а указание -Duser.language=foobarbaz приводит к локальной настройке по умолчанию, язык которой "foobarbaz".)
  3. Экземпляр локальной настройки по умолчанию 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.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 (устаревшие), of(String, String, String), и их перегрузки сохраняют свое поведение до версии Java Runtime Environment 1.7. То есть, ограничение по длине не накладывается ни на один из входных параметров. Аналогичным образом, то же сохранение предыдущего поведения в значительной степени справедливо для метода toString(). Приложения, которые ранее анализировали вывод метода toString() на поля языка, страны и варианта, могут продолжать это делать (хотя это настоятельно не рекомендуется). Оговорка состоит в том, что поле варианта будет содержать дополнительную информацию, если присутствуют сценарий или расширения.

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

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

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

По соображениям совместимости два несоответствующих языковых стандарта рассматриваются как особые случаи. Это ja_JP_JP и th_TH_TH. Они имеют неправильный формат в BCP 46, так как варианты слишком короткие. Для облегчения миграции на BCP 47 эти случаи обрабатываются особо во время построения. Эти два случая (и только эти) приводят к генерации расширения конструктором, все другие значения ведут себя точно так же, как и до Java 7.

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

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

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

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

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

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

С:
1.1
Внешние спецификации
  • RFC 4647: Сопоставление тегов языка
  • RFC 5646: Теги для идентификации языков
  • Язык разметки данных языковых стандартов Unicode
См. также:
  • Locale.Builder
  • ResourceBundle
  • Format
  • NumberFormat
  • Collator
  • Форматированный вывод

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

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

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

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

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

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

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

Модификатор и тип Метод Описание
static Stream<Locale> availableLocales()
Возвращает поток доступных языковых локалей.
static String caseFoldLanguageTag(String languageTag)
Возвращает тег языка IETF BCP 47, преобразованный к нижнему регистру.
Object clone()
Переопределяет Cloneable.
boolean equals(Object obj)
Возвращает true, если эта локаль равна другому объекту.
static List<Locale> filter(List<Locale.LanguageRange> priorityList, Collection<Locale> locales)
Возвращает список совпадающих экземпляров Locale, используя механизм фильтрации, определённый в RFC 4647.
static List<Locale> filter(List<Locale.LanguageRange> priorityList, Collection<Locale> locales, Locale.FilteringMode mode)
Возвращает список совпадающих экземпляров Locale, используя механизм фильтрации, определённый в RFC 4647.
static List<String> filterTags(List<Locale.LanguageRange> priorityList, Collection<String> tags)
Возвращает список соответствующих тегов языка, используя базовый механизм фильтрации, определённый в RFC 4647.
static List<String> filterTags(List<Locale.LanguageRange> priorityList, Collection<String> tags, Locale.FilteringMode mode)
Возвращает список соответствующих тегов языка, используя базовый механизм фильтрации, определённый в RFC 4647.
static Locale forLanguageTag(String languageTag)
Возвращает локаль для указанного тега языка IETF BCP 47.
static Locale[] getAvailableLocales()
Возвращает массив доступных локалей.
String getCountry()
Возвращает код страны/региона для этой локали, который должен быть либо пустой строкой, либо кодом ISO 3166 в верхнем регистре (2 буквы), либо кодом UN M.49 (3 цифры).
static Locale getDefault()
Получает текущее значение default locale для данного экземпляра виртуальной машины Java.
static Locale getDefault(Locale.Category category)
Получает текущее значение default locale для указанной категории для данного экземпляра виртуальной машины Java.
final String getDisplayCountry()
Возвращает имя страны локали, подходящее для отображения пользователю.
String getDisplayCountry(Locale inLocale)
Возвращает имя страны локали, подходящее для отображения пользователю.
final String getDisplayLanguage()
Возвращает имя языка локали, подходящее для отображения пользователю.
String getDisplayLanguage(Locale inLocale)
Возвращает имя языка локали, подходящее для отображения пользователю.
final String getDisplayName()
Возвращает имя локали, подходящее для отображения пользователю.
String getDisplayName(Locale inLocale)
Возвращает имя локали, подходящее для отображения пользователю.
String getDisplayScript()
Возвращает имя сценария локали, подходящее для отображения пользователю.
String getDisplayScript(Locale inLocale)
Возвращает имя сценария локали, подходящее для отображения пользователю.
final String getDisplayVariant()
Возвращает имя кода варианта локали, подходящее для отображения пользователю.
String getDisplayVariant(Locale inLocale)
Возвращает имя кода варианта локали, подходящее для отображения пользователю.
String getExtension(char key)
Возвращает значение расширения (или частного использования), связанное с указанным ключом, или null, если с ключом не связано ни одного расширения.
Set<Character> getExtensionKeys()
Возвращает набор ключей расширений, связанных с данной локалью, или пустой набор, если расширений нет.
String getISO3Country()
Возвращает трёхбуквенное сокращение страны этой локали.
String getISO3Language()
Возвращает трёхбуквенное сокращение языка этой локали.
static String[] getISOCountries()
Возвращает список всех двухбуквенных кодов стран, определённых в ISO 3166.
static Set<String> getISOCountries(Locale.IsoCountryCode type)
Возвращает Set кодов стран 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)
Устанавливает 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, состоящее из языка, страны, варианта, сценария и расширений, как показано ниже: язык + «_» + страна + «_» + (вариант + «_#» | «#») + сценарий + «_» + расширения. Язык всегда в нижнем регистре, страна — в верхнем, сценарий — в заглавном, а расширения — в нижнем.

Методы, объявленные в классе 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
Полезная константа для корневого языка. Корневой язык - это язык, страна и вариант которого пустые строки ("") . Он считается базовым языком всех языков и используется в качестве языка/страны-нейтрального языка для операций, чувствительных к языку.
С:
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').
С:
1.7
См. также:
  • getExtension(char)
  • Locale.Builder.setExtension(char, String)
  • Значения постоянных полей

UNICODE_LOCALE_EXTENSION

public static final char UNICODE_LOCALE_EXTENSION
Ключ для расширения локалей Юникода ('u').
С:
1.7
См. также:
  • getExtension(char)
  • Locale.Builder.setExtension(char, String)
  • Значения постоянных полей

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

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 или числовой код области ООН М.49. См. описание класса Locale о допустимых значениях страны.
variant - Любое произвольное значение, используемое для указания вариации Locale. См. описание класса Locale для получения подробностей.
Исключения:
NullPointerException - выбрасывается, если какой-либо аргумент равен null.

Locale

@Deprecated(since="19") public Locale(String language, String country)
Устарело.
Конструкторы Locale устарели. См. Получение Locale для других вариантов.
Создает локаль из языка и страны. Этот конструктор нормализует значение языка к нижнему регистру, а значение страны — к верхнему регистру.
Описание реализации:
  • Устаревшие коды ISO 639 ("iw", "ji" и "in") отображаются в их текущие формы. См. Устаревшие коды языков для получения дополнительной информации.
  • По соображениям обратной совместимости этот конструктор не выполняет никаких синтаксических проверок входных данных.
Параметры:
language - Код языка ISO 639 alpha-2 или alpha-3, или тег языка длиной до 8 символов. См. описание класса Locale о допустимых значениях языка.
country - Код страны ISO 3166 alpha-2 или числовой код области ООН М.49. См. описание класса Locale о допустимых значениях страны.
Исключения:
NullPointerException - выбрасывается, если любой аргумент равен null.

Locale

@Deprecated(since="19") public Locale(String language)
Устарело.
Конструкторы Locale устарели. См. Получение Locale для других вариантов.
Создает локаль из кода языка. Этот конструктор нормализует значение языка к нижнему регистру.
Описание реализации:
  • Устаревшие коды ISO 639 ("iw", "ji" и "in") отображаются в их текущие формы. См. Устаревшие коды языков для получения дополнительной информации.
  • По соображениям обратной совместимости этот конструктор не выполняет никаких синтаксических проверок входных данных.
Параметры:
language - Код языка ISO 639 alpha-2 или alpha-3, или тег языка длиной до 8 символов. См. описание класса Locale о допустимых значениях языка.
Исключения:
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.
С версии:
19

of

public static Locale of(String language, String country)
Получает локаль по языку и стране. Этот метод приводит язык к нижнему регистру, а страну — к верхнему регистру.
Описание реализации:
  • Этот метод не выполняет никаких синтаксических проверок входных данных. Используйте Locale.Builder для полных синтаксических проверок с BCP47.
  • Устаревшие коды ISO 639 ("iw", "ji" и "in") преобразуются в их современные формы. Подробнее см. Устаревшие коды языка.
Параметры:
language - Код языка. См. описание класса Locale значений языка.
country - Код страны. См. описание класса Locale значений страны.
Возвращает:
Объект Locale
Исключения:
NullPointerException - выбрасывается, если любой из аргументов равен null.
С версии:
19

of

public static Locale of(String language)
Получает локаль по коду языка. Этот метод приводит язык к нижнему регистру.
Описание реализации:
  • Этот метод не выполняет никаких синтаксических проверок входных данных. Используйте Locale.Builder для полных синтаксических проверок с BCP47.
  • Устаревшие коды ISO 639 ("iw", "ji" и "in") преобразуются в их современные формы. Подробнее см. Устаревшие коды языка.
Параметры:
language - Код языка. См. описание класса Locale значений языка.
Возвращает:
Объект Locale
Исключения:
NullPointerException - выбрасывается, если аргумент равен null.
С версии:
19

getDefault

public static Locale getDefault()
Возвращает текущее значение default locale для этого экземпляра Java Virtual Machine.

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

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

getDefault

public static Locale getDefault(Locale.Category category)
Возвращает текущее значение default locale для указанной категории для этого экземпляра Java Virtual Machine.

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

Параметры:
category - указанная категория для получения локали по умолчанию
Возвращает:
локаль по умолчанию для указанной категории для этого экземпляра Java Virtual Machine
Исключения:
NullPointerException - если категория равна null
С версии:
1.7
См. также:
  • setDefault(Locale.Category, Locale)

setDefault

public static void setDefault(Locale newLocale)
Устанавливает default locale для этого экземпляра Java Virtual Machine. Это не влияет на локаль хоста.

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

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

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

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

setDefault

public static void setDefault(Locale.Category category, Locale newLocale)
Устанавливает default locale для указанной категории для этого экземпляра Java Virtual Machine. Это не влияет на локаль хоста.

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

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

Параметры:
category - указанная категория для установки локали по умолчанию
newLocale - новая локаль по умолчанию
Исключения:
NullPointerException - если категория и/или новая локаль равны null
С версии:
1.7
См. также:
  • getDefault(Locale.Category)

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

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

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

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

getISOCountries

public static Set<String> getISOCountries(Locale.IsoCountryCode type)
Возвращает Set кодов стран ISO3166 для указанного типа.
Parameters:
type - Locale.IsoCountryCode указанный тип кода ISO.
Returns:
a Set кодов стран ISO3166 для указанного типа
Throws:
NullPointerException - если тип равен null
Since:
9
See Also:
  • Locale.IsoCountryCode

getISOLanguages

public static String[] getISOLanguages()
Возвращает список всех двухбуквенных кодов языков, определённых в ISO 639. Может быть использован для получения Locales.

Примечание:

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

getLanguage

public String getLanguage()
Возвращает код языка этого Locale.
Implementation Note:
Этот метод возвращает новые формы устаревших кодов ISO 639 ("iw", "ji" и "in"). См. Устаревшие коды языков для получения дополнительной информации.
Returns:
Код языка или пустую строку, если он не определён.
See Also:
  • getDisplayLanguage()

getScript

public String getScript()
Возвращает скрипт для этого locale, который должен быть либо пустой строкой, либо четырёхбуквенным кодом скрипта ISO 15924. Первая буква заглавная, остальные — строчные, например, 'Latn', 'Cyrl'.
Returns:
Код скрипта или пустую строку, если он не определён.
Since:
1.7
See Also:
  • getDisplayScript()

getCountry

public String getCountry()
Возвращает код страны/региона для этого locale, который должен быть либо пустой строкой, либо двухбуквенным кодом ISO 3166 в верхнем регистре, либо трёхзначным кодом ООН M.49.
Returns:
Код страны/региона или пустую строку, если он не определён.
See Also:
  • getDisplayCountry()

getVariant

public String getVariant()
Возвращает код варианта для данного locale.
Returns:
Код варианта или пустую строку, если он не определён.
See Also:
  • getDisplayVariant()

hasExtensions

public boolean hasExtensions()
Возвращает true, если у этого Locale есть какие-либо расширения.
Returns:
true, если у этого Locale есть какие-либо расширения
Since:
1.8

stripExtensions

public Locale stripExtensions()
Возвращает копию этого Locale без расширений. Если у этого Locale нет расширений, возвращается этот Locale.
Returns:
копию этого Locale без расширений, или this, если у this нет расширений
Since:
1.8

getExtension

public String getExtension(char key)
Возвращает значение расширения (или частного использования), связанное с указанным ключом, или null, если с ключом не связано никакого расширения. Для корректности ключ должен быть одним из [0-9A-Za-z]. Ключи регистронезависимы, поэтому, например, 'z' и 'Z' представляют одно и то же расширение.
Parameters:
key - ключ расширения
Returns:
Расширение или null, если этот locale не определяет расширение для указанного ключа.
Throws:
IllegalArgumentException - если ключ некорректен
Since:
1.7
See Also:
  • PRIVATE_USE_EXTENSION
  • UNICODE_LOCALE_EXTENSION

getExtensionKeys

public Set<Character> getExtensionKeys()
Возвращает множество ключей расширений, связанных с этим locale, или пустое множество, если у него нет расширений. Возвращаемое множество неизменяемо. Все ключи будут в нижнем регистре.
Returns:
Множество ключей расширений или пустое множество, если у этого locale нет расширений.
Since:
1.7

getUnicodeLocaleAttributes

public Set<String> getUnicodeLocaleAttributes()
Возвращает множество атрибутов unicode locale, связанных с этим locale, или пустое множество, если у него нет атрибутов. Возвращаемое множество неизменяемо.
Returns:
Множество атрибутов.
Since:
1.7

getUnicodeLocaleType

public String getUnicodeLocaleType(String key)
Возвращает тип Unicode locale, связанный с указанным ключом Unicode locale для этого locale. Возвращает пустую строку для ключей, которые определены без типа. Возвращает null, если ключ не определён. Ключи регистронезависимы. Ключ должен содержать две буквенно-цифровых символа ([0-9a-zA-Z]), в противном случае будет выброшено исключение IllegalArgumentException.
Parameters:
key - ключ Unicode locale
Returns:
Тип Unicode locale, связанный с ключом, или null, если locale не определяет ключ.
Throws:
IllegalArgumentException - если ключ некорректен
NullPointerException - если key равно null
Since:
1.7

getUnicodeLocaleKeys

public Set<String> getUnicodeLocaleKeys()
Возвращает множество ключей Unicode locale, определённых этим locale, или пустое множество, если у этого locale нет таких ключей. Возвращаемое множество неизменяемо. Все ключи в нижнем регистре.
Returns:
Множество ключей Unicode locale или пустое множество, если у данного locale нет ключей Unicode locale.
Since:
1.7

toString

public final String toString()
Возвращает строковое представление объекта Locale, состоящее из языка, страны, варианта, скрипта и расширений, как показано ниже:
язык + "_" + страна + "_" + (вариант + "_#" | "#") + скрипт + "_" + расширения
Язык всегда в нижнем регистре, страна — в верхнем, скрипт — в заглавном, а расширения — в нижнем. Расширения и подтеги частного использования будут в каноническом порядке, как объяснено в toLanguageTag().

Когда у locale нет скрипта и расширений, результат совпадает с Java 6 и ранее.

Если отсутствуют как язык, так и страна, этот метод вернёт пустую строку, даже если вариант, скрипт или расширения присутствуют (locale только с вариантом недопустим; вариант должен сопровождаться корректным кодом языка или страны).

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

Это поведение предназначено для отладки и совместимости с предыдущими использованиями 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
Returns:
Строковое представление Locale для отладки.
See Also:
  • getDisplayName()
  • toLanguageTag()

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
См. также:
  • forLanguageTag(String)

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"). Поскольку устаревшие теги (определённые как "grandfathered" в 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
С:
21
Внешние спецификации
  • RFC5646 2.1. Синтаксис
  • RFC5646 2.1.1. Форматирование тегов языка

forLanguageTag

public static Locale forLanguageTag(String languageTag)
Возвращает локаль для указанного тега языка IETF BCP 47.

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

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

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

    loc = Locale.forLanguageTag("de-POSIX-x-URP-lvariant-Abc-Def");
    loc.getVariant(); // returns "POSIX_Abc_Def"
    loc.getExtension('x'); // returns "urp"
  • Когда аргумент 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, и поэтому поддерживает устаревшие (обычные и необычные, называемые «Type: grandfathered» в BCP47) и подтеги для частного использования. Самостоятельные подтеги для частного использования представляются пустым языком и расширением '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
См. также:
  • toLanguageTag()
  • Locale.Builder.setLanguageTag(String)

getISO3Language

public String getISO3Language() throws MissingResourceException
Возвращает трёхбуквенное сокращение языка этой локали. Если язык соответствует двубуквенному коду ISO 639-1, возвращается соответствующий трёхбуквенный код ISO 639-2/T в нижнем регистре. Коды языков ISO 639-2 можно найти онлайн, см. «Codes for the Representation of Names of Languages Part 2: Alpha-3 Code». Если локаль задаёт трёхбуквенный язык, язык возвращается как есть. Если локаль не задаёт язык, возвращается пустая строка.
Возвращает:
трёхбуквенное сокращение языка этой локали
Бросает:
MissingResourceException - Бросает MissingResourceException, если трёхбуквенное сокращение языка недоступно для этой локали.

getISO3Country

public String getISO3Country() throws MissingResourceException
Возвращает трехбуквенное сокращение страны данного языка. Если страна соответствует коду ISO 3166-1 alpha-2, возвращается соответствующий код ISO 3166-1 alpha-3 в верхнем регистре. Если в языке не указана страна, возвращается пустая строка.

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

Возвращает:
трехбуквенное сокращение страны данного языка
Исключения:
MissingResourceException - Бросает MissingResourceException, если трехбуквенное сокращение страны недоступно для данного языка.

getDisplayLanguage

public final String getDisplayLanguage()
Возвращает имя языка данного языка, подходящее для отображения пользователю. Если возможно, возвращаемое имя будет локализовано для языка по умолчанию DISPLAY. Например, если язык — fr_FR, а язык по умолчанию DISPLAY — en_US, getDisplayLanguage() вернет "Французский"; если язык — 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)
Возвращает имя письменности данного языка, подходящее для отображения пользователю. Если возможно, имя будет локализовано для заданного языка. Возвращает пустую строку, если в данном языке не указан код письменности.
Параметры:
inLocale - Язык для получения имени письменности.
Возвращает:
отображаемое имя кода письменности для текущего языка по умолчанию DISPLAY
Исключения:
NullPointerException - если inLocale равен null
С:
1.7

getDisplayCountry

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

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 - Язык для получения имени варианта.
Возвращает:
Имя варианта, соответствующего заданному языку.
Исключения:
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

clone

public Object clone()
Переопределяет Cloneable.
Переопределяет:
clone в классе Object
Возвращает:
клонированный экземпляр.
См. также:
  • Cloneable

hashCode

public int hashCode()
Переопределяет hashCode. Поскольку локали часто используются в хэш-таблицах, кеширует значение для повышения скорости.
Overrides:
hashCode в классе Object
Возвращает:
значение хэш-кода для данного объекта
См. также:
  • Object.equals(java.lang.Object)
  • System.identityHashCode(java.lang.Object)

equals

public boolean equals(Object obj)
Возвращает true, если эта локаль равна другому объекту. Локаль считается равной другой локали с идентичными языком, письмом, страной, вариантом и расширениями и не равной всем другим объектам.
Overrides:
equals в классе Object
Параметры:
obj - сравниваемый эталонный объект.
Возвращает:
true, если эта локаль равна указанному объекту.
См. также:
  • Object.hashCode()
  • HashMap

filter

public static List<Locale> filter(List<Locale.LanguageRange> priorityList, Collection<Locale> locales, Locale.FilteringMode mode)
Возвращает список соответствующих экземпляров Locale, используя механизм фильтрации, определенный в RFC 4647. Эта операция фильтрации для данного списка locales гарантирует, что возвращаются только уникальные соответствующие локали.
Параметры:
priorityList - Список приоритетов языка пользователя, где каждый тег языка отсортирован в порядке убывания приоритета или веса
locales - экземпляры Locale, используемые для сопоставления
mode - режим фильтрации
Возвращает:
список экземпляров Locale для соответствия тегам языка, отсортированным по убыванию приоритета или веса, или пустой список, если ничего не найдено. Список изменяемый.
Исключения:
NullPointerException - если priorityList или locales имеет null значение
IllegalArgumentException - если один или несколько расширенных языковых диапазонов включены в данный список, когда указан Locale.FilteringMode.REJECT_EXTENDED_RANGES
С:
1.8

filter

public static List<Locale> filter(List<Locale.LanguageRange> priorityList, Collection<Locale> locales)
Возвращает список соответствующих экземпляров Locale, используя механизм фильтрации, определенный в RFC 4647. Это эквивалентно filter(List, Collection, FilteringMode), когда mode равен Locale.FilteringMode.AUTOSELECT_FILTERING. Эта операция фильтрации для данного списка locales гарантирует, что возвращаются только уникальные соответствующие локали.
Параметры:
priorityList - Список приоритетов языка пользователя, где каждый тег языка отсортирован в порядке убывания приоритета или веса
locales - экземпляры Locale, используемые для сопоставления
Возвращает:
список экземпляров Locale для соответствия тегам языка, отсортированным по убыванию приоритета или веса, или пустой список, если ничего не найдено. Список изменяемый.
Исключения:
NullPointerException - если priorityList или locales имеет null значение
С:
1.8

filterTags

public static List<String> filterTags(List<Locale.LanguageRange> priorityList, Collection<String> tags, Locale.FilteringMode mode)
Возвращает список соответствующих тегов языка, используя базовый механизм фильтрации, определенный в RFC 4647. Эта операция фильтрации для данного списка tags гарантирует, что возвращаются только уникальные соответствующие теги с сохранением регистра. В случае дублирующихся соответствующих тегов с разным регистром возвращается первый соответствующий тег с сохранением регистра. Например, "de-ch" возвращается из дублирующихся соответствующих тегов "de-ch" и "de-CH", если "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.
Параметры:
priorityList - Список приоритетов языка пользователя, где каждый тег языка отсортирован в порядке убывания приоритета или веса
tags - теги языка
Возвращает:
список соответствующих тегов языка, отсортированных по убыванию приоритета или веса, или пустой список, если ничего не найдено. Список изменяемый.
Исключения:
NullPointerException - если priorityList или tags имеет null значение
С:
1.8

lookup

public static Locale lookup(List<Locale.LanguageRange> priorityList, Collection<Locale> locales)
Возвращает экземпляр Locale для лучшего соответствующего тега языка, используя механизм поиска, определенный в RFC 4647.
Параметры:
priorityList - Список приоритетов языка пользователя, где каждый тег языка отсортирован в порядке убывания приоритета или веса
locales - экземпляры Locale, используемые для сопоставления
Возвращает:
экземпляр лучшего соответствующего Locale, выбранный на основе приоритета или веса, или null, если ничего не найдено.
Исключения:
NullPointerException - если priorityList или locales имеет null значение
С:
1.8

lookupTag

public static String lookupTag(List<Locale.LanguageRange> priorityList, Collection<String> tags)
Возвращает лучший соответствующий тег языка, используя механизм поиска, определенный в RFC 4647. Эта операция поиска для данного списка tags гарантирует, что возвращается первый соответствующий тег с сохранением регистра.
Параметры:
priorityList - Список приоритетов языка пользователя, где каждый тег языка отсортирован в порядке убывания приоритета или веса
tags - теги языка, используемые для сопоставления
Возвращает:
лучший соответствующий тег языка, выбранный на основе приоритета или веса, или null, если ничего не найдено.
Исключения:
NullPointerException - если priorityList или tags имеет null значение
С:
1.8

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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API