Поддержка интернационализации¶

v18.x.x

Node.js имеет множество функций, которые облегчают написание интернационализированных программ. Вот некоторые из них:

• Функции, чувствительные к локали или Unicode в ECMAScript Language Specification:
  • String.prototype.normalize()
  • String.prototype.toLowerCase()
  • String.prototype.toUpperCase()
• Вся функциональность, описанная в ECMAScript Internationalization API Specification (она же ECMA-402):
  • Intl объект
  • Методы, чувствительные к локализации, такие как String.prototype.localeCompare() и Date.prototype.toLocaleString()
• Поддержка интернационализированных доменных имен (IDN) в WHATWG URL parser.
• require('node:buffer').transcode()
• Более точное редактирование строк REPL
• require('node:util').TextDecoder
• RegExp Unicode Property Escapes

Node.js и лежащий в основе движок V8 используют International Components for Unicode (ICU) для реализации этих возможностей в родном коде на C/C++. Полный набор данных ICU предоставляется Node.js по умолчанию. Однако, из-за размера файла данных ICU, предоставляется несколько опций для настройки набора данных ICU при сборке или запуске Node.js.

Опции для сборки Node.js¶

Чтобы контролировать использование ICU в Node.js, во время компиляции доступны четыре опции configure. Дополнительные подробности о том, как компилировать Node.js, описаны в BUILDING.md.

• --with-intl=none/--without-intl
• --with-intl=system-icu
• --with-intl=small-icu
• --with-intl=full-icu (default)

Обзор доступных возможностей Node.js и JavaScript для каждой опции configure:

Обозначение "(not locale-aware)" означает, что функция выполняет свою работу так же, как и нелокальная версия функции, если таковая существует. Например, в режиме none работа Date.prototype.toLocaleString() идентична работе Date.prototype.toString().

Отключить все функции интернационализации (none)¶

Если выбрана эта опция, ICU отключается и большинство функций интернационализации, упомянутых выше, будут недоступны в результирующем бинарном файле node.

Сборка с предустановленным ICU (system-icu)¶

Node.js может ссылаться на сборку ICU, уже установленную в системе. На самом деле, большинство дистрибутивов Linux уже поставляются с установленным ICU, и эта опция позволит повторно использовать тот же набор данных, который используется другими компонентами ОС.

Функции, которые требуют только саму библиотеку ICU, такие как String.prototype.normalize() и парсер URL WHATWG, полностью поддерживаются под system-icu. Функции, требующие дополнительных данных локали ICU, такие как Intl.DateTimeFormat могут поддерживаться полностью или частично, в зависимости от полноты данных ICU, установленных в системе.

Встраивание ограниченного набора данных ICU (small-icu)¶

Эта опция делает результирующий двоичный файл статически связанным с библиотекой ICU и включает подмножество данных ICU (обычно только английскую локаль) в исполняемый файл node.

Функции, требующие только саму библиотеку ICU, такие как String.prototype.normalize() и парсер URL WHATWG, полностью поддерживаются в small-icu. Функции, которые дополнительно требуют данные локали ICU, такие как Intl.DateTimeFormat, обычно работают только с английской локалью:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

const january = new Date(9e8);
const english = new Intl.DateTimeFormat('en', {
    month: 'long',
});
const spanish = new Intl.DateTimeFormat('es', {
    month: 'long',
});

console.log(english.format(january));
// Печатает "январь"
console.log(spanish.format(january));
// Выводит либо "M01", либо "January" на small-icu, в зависимости от локали пользователя по умолчанию.
// Должно выводиться "enero"

Этот режим обеспечивает баланс между возможностями и размером двоичного файла.

Предоставление данных ICU во время выполнения.¶

Если используется опция small-icu, можно предоставить дополнительные данные о локали во время выполнения, чтобы методы JS работали для всех локалей ICU. Предполагая, что файл данных хранится в /some/directory, его можно сделать доступным для ICU либо через:

• NODE_ICU_DATA переменную окружения:

  1	env NODE_ICU_DATA=/some/directory node

• CLI-параметр --icu-data-dir:

  1	node --icu-data-dir=/some/directory

(Если указаны оба параметра, приоритет имеет параметр CLI --icu-data-dir).

ICU может автоматически находить и загружать данные различных форматов, но данные должны соответствовать версии ICU, а файл должен быть правильно назван. Наиболее распространенное имя файла данных - icudt6X[bl].dat, где 6X обозначает предполагаемую версию ICU, а b или l - эндианальность системы. Смотрите статью "ICU Data" в Руководстве пользователя ICU для других поддерживаемых форматов и более подробную информацию о данных ICU в целом.

Модуль full-icu npm может значительно упростить установку данных ICU, определяя версию ICU запущенного исполняемого файла node и загружая соответствующий файл данных. После установки модуля через npm i full-icu, файл данных будет доступен по адресу ./node_modules/full-icu. Этот путь можно передать в NODE_ICU_DATA или --icu-data-dir, как показано выше, чтобы включить полную поддержку Intl.

Встраивание всего ICU (full-icu)¶

Эта опция заставляет результирующий двоичный файл статически связываться с ICU и включать полный набор данных ICU. Созданный таким образом двоичный файл не имеет дополнительных внешних зависимостей и поддерживает все локали, но может быть довольно большим. Это поведение по умолчанию, если не передан флаг --with-intl. Официальные двоичные файлы также собираются в этом режиме.

Обнаружение поддержки интернационализации¶

Чтобы убедиться, что ICU вообще включен (system-icu, small-icu или full-icu), достаточно просто проверить существование Intl:

1

const hasICU = typeof Intl === 'object';

Альтернативно, проверка на process.versions.icu, свойство, определяемое только при включенном ICU, тоже работает:

1

const hasICU = typeof process.versions.icu === 'string';

Для проверки поддержки неанглийской локали (т. е. full-icu или system-icu), Intl.DateTimeFormat может быть хорошим отличительным фактором:

1
2
3
4
5
6
7
8
9

const hasFullICU = (() => {
  попытка {
    const january = new Date(9e8);
    const spanish = new Intl.DateTimeFormat("es", { month: "long" });
    return spanish.format(january) === "enero";
  } catch (err) {
    return false;
  }
})();

Для более подробных тестов на поддержку Intl могут быть полезны следующие ресурсы:

• btest402: Обычно используется для проверки правильности сборки Node.js с поддержкой Intl.
• Test262: Официальный набор тестов соответствия ECMAScript включает раздел, посвященный ECMA-402.