Intl

Об'єкт – простір імен Intl містить декілька конструкторів, а також функціональність, спільну для конструкторів інтернаціоналізації та інших функцій, чутливих до мови. Разом вони становлять API інтернаціоналізації ECMAScript, який надає можливості для: порівняння рядків, форматування чисел, форматування дат і часу та інше, чутливе до мови.

Опис

На відміну від більшості глобальних об'єктів, 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") та однієї або більше підміток з 2-8 літер або цифр, відділених дефісами. Для кожної цифри або літери дозволено лише одну послідовність: "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": use British English with the Islamic (Hijri) calendar, where the Gregorian date 14 October, 2017 is the Hijri date 24 Muharram, 1439.
  • "en-GB-u-ca-islamic": використовувати британську англійську з мусульманським календарем (від Хіджри), в якому григоріанська дата 14 жовтня 2017 року виражається як дата Хіджри 24 Мухаррам 1439 року.

• Розширення "t" (трансформована) позначає перетворений вміст: наприклад, текст, що перекладений з іншої локалі. Наразі жодна функціональність Intl не враховує розширення "t". Проте це розширення іноді містить вкладену локаль (без розширень): наприклад, трансформоване розширення в "de-t-en" містить ідентифікатор локалі для англійської. Якщо вкладена локаль присутня, то вона повинна бути дійсним ідентифікатором локалі. Наприклад, оскільки "en-emodeng-emodeng" – недійсний ідентифікатор (оскільки містить дублікат підмітки варіанту emodeng), то "de-t-en-emodeng-emodeng" – також недійсний.

Врешті решт, послідовність розширення приватного використання, що використовує літеру "x", може зустрічатися перед однією або більше підміток з 2-8 літер або цифр, відділених дефісами. Це дозволяє застосункам кодувати інформацію для власного приватного використання, яка буде ігноруватися всіма операціями Intl.

Аргумент options

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

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

Впізнання та зіставлення локалей

Список локалей, заданих аргументом locales, після вилучення з них розширень Unicode, тлумачиться як запит від застосунку в порядку пріоритету. Середовище виконання порівнює ці локалі з локалями, які є в доступності, та вибирає найкращу. Існують два алгоритми зіставлення: алгоритм "lookup" (пошук) виконує алгоритм Пошуку, описаний в BCP 47; алгоритм "best fit" (найбільш годяще) дозволяє середовищу виконання надати локаль, яка є щонайменше так само, але, можливо, й більше, годящою для запиту, як результат алгоритму пошуку. Якщо застосунок не передає аргумент locales, або якщо середовище виконання не має локалі, що відповідає запитові, то використовується усталена локаль середовища виконання. Алгоритм може бути вибраний за допомогою властивості аргументу 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[@@toStringTag]

Початкове значення властивості @@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

log("uk-UA"); // 24.05.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);

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

Сумісність із браузерами

Дивіться також

• String.prototype.localeCompare()
• Number.prototype.toLocaleString()
• Date.prototype.toLocaleString()
• Date.prototype.toLocaleDateString()
• Date.prototype.toLocaleTimeString()
• navigator.language
• navigator.languages
• API інтернаціоналізації ECMAScript від Норберта Лінденберга (2012)