Internationalization API

Internationalization API предоставляет следующие возможности:

локализованное (далее предполагается) сравнение строк
форматирование чисел, включая валюту, различные единицы измерения и проценты
форматирование даты и времени, включая относительные периоды, такие как завтра, вчера, через неделю и т.д.
форматирование названий языков, регионов, скриптов и валют
форматирование списков с соединительным союзом И или разделительным союзом ИЛИ
"плюрализация" - перевод во множественное число
преобразование регистра

В настоящее время Internationalization API поддерживается всеми современными браузерами.

Несмотря на то, что в JavaScript существуют такие методы для локализации как:

их зачастую оказывается недостаточно.

Кроме того, поведение данных методов определяется конкретной реализацией ECMAScript, т.е. браузером.

Функционал, определенный в Internationalization API, инкапсулирован в объекте Intl. Данный объект не имеет внутреннего метода [[Construct]], поэтому не может вызываться как конструктор с помощью ключевого слова new. Он также не имеет внутреннего метода [[Call]], поэтому не может вызываться как функция.

Intl включает в себя следующие интерфейсы-конструкторы:

Collator - сравнение строк
DateTimeFormat - форматирование даты и времени
DisplayNames - форматирование названий языков, регионов и т.д. на других языках
ListFormat - форматирование списков
Locale - определение локали
NumberFormat - форматирование чисел
PluralRules - плюрализация
RelativeTimeFormat - форматирование относительных периодов времени

Возможные значения:

Пример получения текущей даты и времени в дефолтной локали

// [] означает текущую локаль (локаль по умолчанию)
const currentDateAndTime = new Intl.DateTimeFormat([], {
  dateStyle: 'short',
  timeStyle: 'short'
}).format()

console.log(currentDateAndTime) // 03.08.2021, 15:57

`Locale`

Конструктор Locale используется для создания экземпляров идентификаторов локали. Первым обязательным аргументом, передаваемым Locale, является локаль, которая может состоять из следующего:

код языка
код диалекта
код региона или страны
один или несколько уникальных вариантных подтегов (subtags)
одна или несколько последовательностей из расширения BCP 47
последовательность из расширения для частного использования

В большинстве случаев достаточно указать код языка или код языка и код страны через дефис:

const ru = new Intl.Locale('ru-RU')

Вторым опциональным аргументом Locale является объект с настройками:

const ru = new Intl.Locale(
  'ru',
  { region: 'RU', hourCycle: 'h24', calendar: 'gregory' }
)

Локаль может быть строкой или объектом. Пустой массив означает использование текущей локали пользователя:

const now = new Intl.DateTimeFormat([], { timeStyle: 'short' }).format()

`DateTimeFormat`

Конструктор DateTimeFormat используется для форматирования даты и времени. Он принимает локаль и объект с настройками.

Сигнатура

new Intl.DateTimeFormat(locale: object | string | [], options: object).format(date)
// [] - локаль по умолчанию
// date - дата, время или дата и время

Настройки

Свойство	Описание
timeZone	часовой пояс: `UTC`, `America/New_York`, `Europe/Paris` и т.д.
calendar	календарь: `chinese`, `gregory`, `hebrew`, `indian`, `islamic` и т.д.
numberingSystem	система счисления: `arab`, `beng`, `fullwide`, `latin` и т.д.
localeMatcher	алгоритм для поиска совпадений: `lookup`, `best fit`
formatMatcher	алгоритм для форматирования: `basic`, `best fit`
hour12	если имеет значение `true`, используется 12-часовой формат
hourCycle	часовой формат: `h11`, `h12`, `h23`, `h24`
dateStyle	стиль форматирования даты: `full`, `long`, `medium`, `short`
weekday	день недели: `long`, `short`, `narrow`
day	день месяца: `numeric`, `2-digit`
month	месяц: `numeric`, `2-digit`, `long`, `short`, `narrow`
year	год: `numeric`, `2-digit`
era	эпоха: `long`, `short`, `narrow`
timeStyle	стиль форматирования времени: `full`, `long`, `medium`, `short`
hour	часы: `numeric`, `2-digit`
minute	минуты: `numeric`, `2-digit`
second	секунды: `numeric`, `2-digit`
dayPeriod	часть дня (утро, вечер и т.п.): `narrow`, `short`, `long`
timeZoneName	название часового пояса (UTC, PTC): `long`, `short`

Настройки localeMatcher и formatMatcher могут передаваться любому конструктору, предоставляемому Intl, но используются редко.

По умолчанию new Intl.DateTimeFormat().format() возвращает текущую дату в кратком виде (dateStyle: short).

Примеры

const formatDateTime = ({ locale = [], date = Date.now(), ...options } = {}) =>
  new Intl.DateTimeFormat(locale, options).format(date)

console.log(
  '\n',
  // русский
  formatDateTime(), // 17.08.2021
  '\n',
  // американский английский
  formatDateTime({ locale: 'en-US', dateStyle: 'short', timeStyle: 'short' }), // 8/17/21, 3:56 PM,
  '\n',
  // британский английский
  formatDateTime({ locale: 'en-GB', dateStyle: 'long', timeStyle: 'short' }), // 17 August 2021 at 15:57
  '\n',
  // японский
  formatDateTime({ locale: 'ja-JP', dateStyle: 'short' }), // 2021/08/17
  '\n',
  // испанский
  formatDateTime({ locale: 'es-ES', dateStyle: 'full', timeStyle: 'full' }), // martes, 17 de agosto de 2021, 15:57:49 (hora estándar de Ekaterimburgo)
  '\n',
  // французский
  formatDateTime({
    locale: 'fr-FR',
    weekday: 'long',
    day: '2-digit',
    month: 'long',
    year: 'numeric',
    hour: '2-digit'
  }) // mardi 17 août 2021, 15 h
)

Другие методы

formatToParts() - возвращает массив объектов, содержащих форматированную дату в виде пар ключ/значение ({ type: 'weekday', value: 'Monday' })
formatRange(startDate, endDate) - возвращает диапазон, например, 01/10/2022, 10:00 AM - 12:00 PM
formatRangeToParts()
resolveOptions() - возвращает объект со свойствами, значениями которых являются вычисленные настройки форматирования для локали, даты и времени

`RelativeTimeFormat`

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

Сигнатура

new Intl.RelativeTimeFormat(locale, options).format(amount, unit)
// amount - количество единиц времени
// unit - единица времени: `day`, `month`, `year` и т.д.

Положительное число в amount означает будущее, отрицательное - прошлое.

Настройки

Свойство	Описание
numeric	`always` - "1 день назад" (дефолтное значение), `auto` - "вчера"
style	`long` (дефолтное значение), `short`, `narrow`

В данном случае метод format в качестве аргументов принимает число и единицу времени.

Примеры

const formatRelativeTime = ({
  locale = [],
  value = '1 day',
  ...options
} = {}) => {
  const [amount, unit] = value.split(/[\s_]/)
  return new Intl.RelativeTimeFormat(locale, options).format(amount, unit)
}

console.log(
  '\n',
  formatRelativeTime(), // через 1 день
  '\n',
  formatRelativeTime({ locale: 'en-US', value: '-1 day', numeric: 'auto' }), // yesterday
  '\n',
  formatRelativeTime({
    locale: 'fr-FR',
    value: '1 week',
    style: 'long'
  }), // dans 1 semaine
  '\n',
  formatRelativeTime({
    locale: 'ja-JP',
    value: '-1 month',
    numeric: 'auto',
    style: 'long'
  }) // 先月
)

`NumberFormat`

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

Сигнатура

new Intl.NumberFormat(locale, options).format(number)

Настройки

Свойство	Описание
style	вид единиц: `decimal` - число с плавающей точкой, `currency` - валюта, `percent` - проценты, `unit` - единицы измерения. От этой настройки зависят другие
notation	стиль форматирования: `standard`, `scientific`, `engineering`, `compact`
numberingSystem	система счисления: `arab`, `beng`, `deva`, `fullwide`, `latn` и др.
minimumIntegerDigits	минимальное количество цифр целой части числа (от 1 до 21; по умолчанию 1)
minimumFractionDigits	минимальное количество цифр после запятой (от 0 до 20; по умолчанию 0)
maximumFractionDigits	максимальное количество цифр после запятой (от 0 до 20; по умолчанию наибольшее значение из minimumFractionDigits и 3)
minimumSignificantDigits	минимальное количество значащих цифр (от 1 до 21; по умолчанию 1)
maximumSignificantDigits	минимальное количество значащих цифр (от 1 до 21; по умолчанию minimumSignificantDigits)
signDisplay	отображение символов `+/-`: `auto`, `never`, `always`, `exceptZero`
useGrouping	если имеет значение `false`, разделители тысяч будут игнорироваться
compactDisplay	форматирование при использовании нотации `compact`
currency	код валюты при использовании стиля `currency`: `USD`, `EUR`, `RUB` и т.д.
currencyDisplay	отображение символа/названия валюты при использовании стиля `currency`: `symbol`, `narrowSymbol`, `code`, `name`
currencySign	форматирование отрицательных значений при использовании стиля `currency`: `standard`, `accounting`
unit	вид единицы измерения: `centimeter`, `meter`, `minute`, `hour`, `byte` и т.д.
unitDisplay	формат отображения единицы измерения: `long`, `short`, `narrow`

Примеры

const formatNumber = ({ locale = [], number = 1234.56, ...options } = {}) =>
  new Intl.NumberFormat(locale, options).format(number)

console.log(
  '\n',
  formatNumber(),
  '\n', // 1 234,56
  formatNumber({ locale: 'en-US' }),
  '\n', // 1,234.56
  formatNumber({ locale: 'de-DE', style: 'currency', currency: 'EUR' }),
  '\n', // 1.234,56 €
  formatNumber({ locale: 'fr-FR', style: 'percent' }),
  '\n', // 123 456 %
  formatNumber({
    locale: 'it-IT',
    style: 'unit',
    unit: 'celsius',
    minimumFractionDigits: 3
  }),
  '\n' // 1.234,560 °C
)

`DisplayNames`

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

Сигнатура

new Intl.DisplayNames(locale, options).of(localeOf)

Настройки

Свойство	Описание
type	тип названия: `language`, `region`, `script`, `currency`
style	стиль форматирования: `long`, `short`, `narrow`
fallback	резерв: `code`, `none`

Обратите внимание: настройка type является обязательной. При этом хорошо поддерживается только type со значением language.

Примеры

const formatNames = ({
  locale = [],
  localeOf = 'en-US',
  type = 'language',
  ...options
} = {}) => new Intl.DisplayNames(locale, { type, ...options }).of(localeOf)

console.log(
  '\n',
  formatNames(),
  '\n', // американский английский
  formatNames({
    localeOf: 'Egyp',
    type: 'script'
  }),
  '\n', // египетская иероглифическая
  formatNames({
    locale: 'fr-FR',
    localeOf: 'AU',
    type: 'region'
  }),
  '\n', // Australie - Авcтралия по-французски
  formatNames({
    locale: 'pl-PL',
    localeOf: 'GBP',
    type: 'currency',
    style: 'long'
  }),
  '\n' // funt szterling - английские фунты стерлингов на польском
)

`ListFormat`

Конструктор ListFormat используется для форматирования списков путем подстановки соединительного союза И или разделительного союза ИЛИ. Данный метод принимает локаль и объект с настройками.

Сигнатура

new Intl.ListFormat(locale, options).format(list)

Настройки

Свойство	Описание
type	формат вывода: `conjunction` (и; дефолтное значение), `disjunction` (или), `unit` (нет)
style	стиль форматирования: `long`, `short`, `narrow`

Примеры

const browsers = ['Chrome', 'Firefox', 'Safari']

const formatList = ({
  locale = [],
  list = browsers,
  ...options
} = {}) => new Intl.ListFormat(locale, options).format(list)

console.log(
  '\n',
  formatList(),
  '\n', // Chrome, Firefox и Safari
  formatList({ locale: 'en-US', style: 'short' }),
  '\n', // Chrome, Firefox, & Safari
  formatList({ locale: 'ja-JP', type: 'disjunction' }),
  '\n' // Chrome、Firefox、またはSafari
)

`Collator`

Конструктор Collator используется для сравнения строк с учетом локали. Данный метод принимает локаль и объект с настройками.

Сигнатура

new Intl.Collator(locale, options).compare(str1, str2)

Настройки

Свойство	Описание
usage	`sort` - сортировка (дефолтное значение) или `search` - поиск
sensitivity	чувствительность: `base`, `accent`, `case`, `variant`
collation	сопоставление вариантов для нескольких языков
numeric	`true` означает сравнение чисел
ignorePunctuation	`true` означает игнорирование пунктуации
caseFirst	`upper` - сначала идут строки, начинающиеся с большой буквы, `lower` - сначала идут строки, начинающиеся с маленькой буквы

Результат

0 - строки равны
-1 - первая строка "меньше" второй
1 - первая строка "больше" второй

Примеры

const compareValues = ({ locale = [], values = [], ...options } = {}) =>
  new Intl.Collator(locale, options).compare(...values)

console.log(
  '\n',
  compareValues({ values: ['a', 'á'], sensitivity: 'base' }),
  '\n', // 0 -> одинаковые
  compareValues({ values: ['2', '10'] }),
  '\n', // 1 -> '2' > '10'
  compareValues({ values: ['2', '10'], numeric: true }),
  '\n' // -1 -> 2 < 10
)

`PluralRules`

Конструктор PluralRules используется для плюрализации (перевода во множественное число). Данный метод принимает локаль и объект с настройками.

Сигнатура

new Intl.PluralRules(locale, options).select(number)

Настройки

Свойство	Описание
type	`cardinal` - количество элементов (дефолтное значение), `ordinal` - порядок элемента (первый, второй, третий и т.д.)

Примеры

const pluralize = ({ locale = [], number = 1, ...options } = {}) =>
  new Intl.PluralRules(locale, options).select(number)

console.log(
  '\n',
  pluralize(),
  '\n', // one
  pluralize({ locale: 'ru-RU', type: 'ordinal' }),
  '\n' // other
)

Как видите, в настоящее время данный метод поддерживает только локаль en-US.