Intl

Объект пространства имен Intl содержит несколько конструкторов, а также функциональность, общую для интернационализационных конструкторов и других функций, зависящих от языка. Вместе они составляют ECMAScript Internationalization API, который предоставляет чувствительное к языку сравнение строк, форматирование чисел, форматирование дат и времени и многое другое.

Описание

В отличие от большинства глобальных объектов, Intl не является конструктором. Вы не можете использовать его с оператором new или вызывать объект Intl как функцию. Все свойства и методы Intl являются статическими (как и объект Math).

Интернационализационные конструкторы, а также несколько зависящих от языка методов других конструкторов (перечисленных в разделе См. также) используют общий шаблон для идентификации локалей и определения той, которую они фактически будут использовать: все они принимают аргументы locales и options, а также согласовывают запрошенные локали с поддерживаемыми локалями, используя алгоритм, указанный в свойстве options.localeMatcher.

Аргумент locales

Аргумент locales используется для определения локали, используемой в данной операции. Реализация JavaScript анализирует locales, а затем вычисляет понятную ей локаль, которая наиболее точно соответствует выраженному предпочтению. locales может быть:

• undefined (или опущен): Будет использована локаль по умолчанию для реализации.
• Локаль: Идентификатор локали или объект Intl.Locale, который оборачивает идентификатор локали.
• Список локалей: Любое другое значение, которое будет преобразовано в объект, а затем обработано как массив локалей.

В последних двух случаях фактической используемой локалью является наиболее поддерживаемая локаль, определенная согласованием локалей. Если идентификатор локали не является строкой или объектом, выбрасывается TypeError. Если идентификатор локали является строкой, синтаксически некорректной, выбрасывается RangeError. Если идентификатор локали корректен, но реализация его не распознает, он игнорируется, и рассматривается следующая локаль в списке, в конечном итоге возвращаясь к локали системы. Однако не следует полагаться на игнорирование конкретного имени локали, поскольку реализация может добавлять данные для любых локалей в будущем. Например, new Intl.DateTimeFormat("default") использует локаль по умолчанию для реализации только потому, что "default" синтаксически корректен, но не распознается как какая-либо локаль.

Идентификатор локали — это строка, состоящая из:

1. Языковой подтег из 2–3 или 5–8 букв
2. Скриптовый подтег из 4 букв Необязательно
3. Региональный подтег из 2 букв или 3 цифр Необязательно
4. Один или несколько вариативных подтегов (все из которых должны быть уникальными), каждый из которых состоит из 5–8 буквенно-цифровых символов или цифры, за которой следуют 3 буквенно-цифровых символа Необязательно
5. Одна или несколько последовательностей расширений BCP 47 Необязательно
6. Последовательность расширения для частного использования Необязательно

Каждый подтег и последовательность разделены дефисами. Идентификаторы локалей являются регистронезависимыми ASCII. Однако принято использовать верхний регистр (первая буква заглавная, остальные строчные) для скриптовых подтегов, верхний регистр для региональных подтегов и нижний регистр для всего остального. Например:

• "hi": Хинди (язык)
• "de-AT": Немецкий (язык), используемый в Австрии (регион)
• "zh-Hans-CN": Китайский (язык), написанный упрощенными иероглифами (скрипт), используемый в Китае (регион)
• "en-emodeng": Английский (язык) в диалекте "Ранний современный английский" (вариант)

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

Последовательности расширений BCP 47 состоят из одной цифры или буквы (кроме "x") и одного или нескольких подтегов длиной от двух до восьми букв или цифр, разделенных дефисами. Для каждой цифры или буквы разрешена только одна последовательность: "de-a-foo-a-foo" недопустимо. Подтеги расширений BCP 47 определены в Проекте Unicode CLDR. В настоящее время определены только два расширения:

• Расширение "u" (Unicode) может использоваться для запроса дополнительной настройки объектов API Intl. Примеры:
  • "de-DE-u-co-phonebk": Используйте вариант телефонной книги немецкого порядка сортировки, который интерпретирует умлаутированные гласные как соответствующие пары символов: ä → ae, ö → oe, ü → ue.
  • "th-TH-u-nu-thai": Используйте тайские цифры (๐, ๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙) при форматировании чисел.
  • "ja-JP-u-ca-japanese": Используйте японский календарь при форматировании дат и времени, так что 2013 год выражается как 25-й год периода Хэйсэй, или 平成 25.
  • "en-GB-u-ca-islamic-umalqura": использовать британский английский с календарем Умм аль-Кура (Хиджра), где дата по григорианскому календарю 14 октября 2017 года соответствует дате 24 Мухаррама 1439 года по хиджре.
• Расширение "t" (трансформированное) указывает на трансформированное содержимое: например, текст, переведенный с другой локали. В настоящее время никакая функциональность Intl не учитывает расширение "t". Однако это расширение иногда содержит вложенную локаль (без расширений): например, трансформированное расширение в "de-t-en" содержит идентификатор локали для английского языка. Если вложена локаль присутствует, она должна быть допустимым идентификатором локали. Например, поскольку "en-emodeng-emodeng" недопустим (поскольку содержит повторяющийся вариативный подтег emodeng), "de-t-en-emodeng-emodeng" также недопустим.

Наконец, может появиться последовательность расширения для частного использования с буквой "x", за которой следует один или несколько подтегов длиной от одного до восьми букв или цифр, разделенных дефисами. Это позволяет приложениям кодировать информацию для своего собственного частного использования, которая будет игнорироваться всеми операциями Intl.

Аргумент options

Аргумент options должен быть объектом со свойствами, которые различаются между конструкторами и функциями. Если аргумент options не предоставлен или имеет значение undefined, для всех свойств используются значения по умолчанию.

Все зависящие от языка конструкторы и функции поддерживают одно свойство: свойство localeMatcher, значением которого должна быть строка "lookup" или "best fit", которое выбирает один из описанных ниже алгоритмов сопоставления локалей.

Идентификация и согласование локалей

Список локалей, указанных в аргументе locales, после удаления из них расширений Unicode, интерпретируется как приоритетный запрос от приложения. Среда выполнения сравнивает его с доступными ей локалями и выбирает наилучшую доступную. Существуют два алгоритма сопоставления: "lookup" matcher следует алгоритму Lookup, указанному в BCP 47; "best fit" matcher позволяет среде выполнения предоставить локаль, которая по крайней мере, но, возможно, и более, соответствует запросу, чем результат алгоритма Lookup. Если приложение не предоставляет аргумент locales, или среда выполнения не имеет локали, соответствующей запросу, то используется локаль по умолчанию среды выполнения. Выбор matcher'а может быть осуществлен с помощью свойства аргумента options (см. ниже).

Если выбранный идентификатор локали имел последовательность расширения Unicode, это расширение теперь используется для настройки сконструированного объекта или поведения функции. Каждый конструктор или функция поддерживает только подмножество ключей, определенных для расширения Unicode, а поддерживаемые значения часто зависят от идентификатора локали. Например, ключ "co" (сортировка) поддерживается только Intl.Collator, а его значение "phonebk" поддерживается только для немецкого языка.

Статические свойства

Intl.Collator

Конструктор для компараторов, представляющих собой объекты, обеспечивающие сравнение строк с учетом языка.

Intl.DateTimeFormat

Конструктор для объектов, обеспечивающих форматирование дат и времени с учетом языка.

Intl.DisplayNames

Конструктор для объектов, обеспечивающих согласованный перевод названий языков, регионов и скриптов.

Intl.DurationFormat

Конструктор для объектов, обеспечивающих форматирование длительности с учетом локали.

Intl.ListFormat

Конструктор для объектов, обеспечивающих форматирование списков с учетом языка.

Intl.Locale

Конструктор для объектов, представляющих идентификатор локали Unicode.

Intl.NumberFormat

Конструктор для объектов, обеспечивающих форматирование чисел с учетом языка.

Intl.PluralRules

Конструктор для объектов, обеспечивающих форматирование с учетом множественного числа и языковых правил для множественного числа.

Intl.RelativeTimeFormat

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

Intl.Segmenter

Конструктор для объектов, обеспечивающих сегментацию текста с учетом локали.

Intl[Symbol.toStringTag]

Начальным значением свойства [Symbol.toStringTag] является строка "Intl". Это свойство используется в Object.prototype.toString().

Статические методы

Intl.getCanonicalLocales()

Возвращает канонические имена локалей.

Intl.supportedValuesOf()

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

Примеры

Форматирование дат и чисел

Вы можете использовать Intl для форматирования дат и чисел в форме, соответствующей определенному языку и региону:

const count = 26254.39;
const date = new Date("2012-05-24");

function log(locale) {
  console.log(
    `${new Intl.DateTimeFormat(locale).format(date)} ${new Intl.NumberFormat(
      locale,
    ).format(count)}`,
  );
}

log("en-US"); // 5/24/2012 26,254.39

log("de-DE"); // 24.5.2012 26.254,39

Использование предпочитаемого языка браузера

Вместо передачи жестко заданного имени локали в методы Intl, вы можете использовать предпочитаемый язык пользователя, предоставленный navigator.language:

const date = new Date("2012-05-24");

const formattedDate = new Intl.DateTimeFormat(navigator.language).format(date);

В качестве альтернативы свойство navigator.languages предоставляет отсортированный список предпочитаемых пользователем языков. Этот список может быть напрямую передан конструкторам Intl для реализации выбора локалей на основе предпочтений. Процесс согласования локалей используется для выбора наиболее подходящей доступной локали:

const count = 26254.39;

const formattedCount = new Intl.NumberFormat(navigator.languages).format(count);

Спецификации

Совместимость с браузерами

См. также

• Keyboard.getLayoutMap()
• navigator.language
• navigator.languages
• The ECMAScript Internationalization API by Norbert Lindenberg (2012)