Класс Locale

public final class Locale extends Object implements Cloneable, Serializable

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

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

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

язык

Код языка ISO 639 alpha-2 или alpha-3, или зарегистрированные подтеги языка до 8 букв (для будущих улучшений). Когда язык имеет как код alpha-2, так и код alpha-3, необходимо использовать код alpha-2. Полный список допустимых кодов языка можно найти в реестре подтегов языка IANA (поиск по «Тип: язык»). Поле языка нечувствительно к регистру, но Locale всегда приводит к нижнему регистру.

Корректно сформированные значения языка имеют вид [a-zA-Z]{2,8}. Обратите внимание, что это не полное представление языка BCP47, поскольку оно исключает extlang. Они не нужны, так как современные трехбуквенные коды языка их заменяют.

Пример: «en» (английский), «ja» (японский), «kok» (конкани)

алфавит

Код алфавита ISO 15924 alpha-4. Полный список допустимых кодов алфавита можно найти в реестре подтегов языка IANA (поиск по «Тип: алфавит»). Поле алфавита нечувствительно к регистру, но Locale всегда приводит к заглавному регистру (первая буква — заглавная, остальные — строчные).

Корректно сформированные значения алфавита имеют вид [a-zA-Z]{4}

Пример: «Latn» (латинский), «Cyrl» (кириллический)

страна (регион)

Код страны ISO 3166 alpha-2 или числовой код области ООН M.49. Полный список допустимых кодов страны и региона можно найти в реестре подтегов языка IANA (поиск по «Тип: регион»). Поле страны (региона) нечувствительно к регистру, но Locale всегда приводит к верхнему регистру.

Корректно сформированные значения страны/региона имеют вид [a-zA-Z]{2} | [0-9]{3}

Пример: «US» (Соединённые Штаты), «FR» (Франция), «029» (Карибский бассейн)

вариант

Любое произвольное значение, используемое для обозначения вариации Locale. Если имеется два или более значений варианта, каждое из которых указывает свою семантику, эти значения должны быть упорядочены по важности, начиная с наиболее важного, через символ подчеркивания('_'). Поле варианта чувствительно к регистру.

Примечание: IETF BCP 47 накладывает синтаксические ограничения на подтеги варианта. Также подтеги BCP 47 строго используются для обозначения дополнительных вариаций, определяющих язык или его диалекты, которые не покрываются никакими комбинациями подтегов языка, алфавита и региона. Полный список допустимых кодов варианта можно найти в реестре подтегов языка IANA (поиск по «Тип: вариант»).

Однако, поле «вариант» в Locale исторически использовалось для любого типа вариаций, а не только вариаций языка. Например, некоторые поддерживаемые варианты в средах выполнения Java SE Runtime Environment указывают альтернативные культурные поведения, такие как тип календаря или тип числового алфавита. В BCP 47 такая информация, которая не идентифицирует язык, поддерживается расширениями подтегов или подтегами частного использования.

Корректно сформированные значения варианта имеют вид SUBTAG (('_'|'-') SUBTAG)* где SUBTAG = [0-9][0-9a-zA-Z]{3} | [0-9a-zA-Z]{5,8}. (Примечание: BCP 47 использует только дефис ('-') в качестве разделителя, это более гибко).

Пример: «polyton» (политонический греческий), «POSIX»

расширения

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

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

Пример: ключ="u"/значение="ca-japanese" (Японский календарь), ключ="x"/значение="java-1-7"

Примечание: Хотя BCP 47 требует, чтобы значения полей были зарегистрированы в реестре подтегов языка IANA, класс Locale не предоставляет никаких функций проверки. Класс Builder проверяет только, удовлетворяет ли отдельное поле синтаксическим требованиям (является ли оно корректно сформированным), но не проверяет само значение. Подробнее см. Locale.Builder.

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

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

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

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

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

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

Создание объекта Locale

Существует несколько способов создания объекта Locale.

Построитель

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

Конструкторы

Класс Locale предоставляет три конструктора:

     Locale(String language)
     Locale(String language, String country)
     Locale(String language, String country, String variant)
 

Эти конструкторы позволяют создать объект Locale с языком, страной и вариантом, но вы не можете указать алфавит или расширения.

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

Метод forLanguageTag(java.lang.String) создаёт объект Locale для корректно сформированного тега языка BCP 47.

Константы Locale

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

     Locale.US
 

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

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

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

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

Фильтрация

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

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

Поиск

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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