国际化支持#

Node.js 具有许多功能，可以更轻松地编写国际化程序。 其中一些是

Node.js 和底层 V8 引擎使用 Unicode 国际组件 (ICU) 在本机 C/C++ 代码中实现这些功能。 默认情况下，Node.js 提供完整的 ICU 数据集。 但是，由于 ICU 数据文件的大小，提供了几个选项，用于在构建或运行 Node.js 时自定义 ICU 数据集。

构建 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 (默认)

每个 configure 选项可用的 Node.js 和 JavaScript 功能概述

功能nonesystem-icusmall-icufull-icu
String.prototype.normalize()none（函数是空操作）fullfullfull
String.prototype.to*Case()fullfullfullfull
Intlnone（对象不存在）partial/full（取决于操作系统）partial（仅限英语）full
String.prototype.localeCompare()partial（不识别区域设置）fullfullfull
String.prototype.toLocale*Case()partial（不识别区域设置）fullfullfull
Number.prototype.toLocaleString()partial（不识别区域设置）partial/full（取决于操作系统）partial（仅限英语）full
Date.prototype.toLocale*String()partial（不识别区域设置）partial/full（取决于操作系统）partial（仅限英语）full
旧版 URL 解析器partial（不支持 IDN）fullfullfull
WHATWG URL 解析器partial（不支持 IDN）fullfullfull
require('node:buffer').transcode()none（函数不存在）fullfullfull
REPLpartial（不准确的行编辑）fullfullfull
require('node:util').TextDecoderpartial（基本编码支持）partial/full（取决于操作系统）partial（仅限 Unicode）full
RegExp Unicode 属性转义none（无效的 RegExp 错误）fullfullfull

“（不识别区域设置）”表示该函数的执行方式与该函数的非 Locale 版本相同（如果存在）。 例如，在 none 模式下，Date.prototype.toLocaleString() 的操作与 Date.prototype.toString() 的操作相同。

禁用所有国际化功能 (none)#

如果选择此选项，则会禁用 ICU，并且上述大多数国际化功能在生成的 node 二进制文件中将不可用。

使用预先安装的 ICU 构建 (system-icu)#

Node.js 可以链接到系统上已安装的 ICU 构建。 实际上，大多数 Linux 发行版已经安装了 ICU，并且此选项可以重用操作系统中其他组件使用的同一组数据。

仅需要 ICU 库本身的功能，例如 String.prototype.normalize() 和 WHATWG URL 解析器，在 system-icu 下得到完全支持。 此外，需要 ICU 区域设置数据的功能，例如 Intl.DateTimeFormat 可能会得到完全或部分支持，具体取决于系统上安装的 ICU 数据的完整性。

嵌入有限的 ICU 数据 (small-icu)#

此选项使生成的二进制文件静态链接到 ICU 库，并在 node 可执行文件中包含 ICU 数据的子集（通常只有英语区域设置）。

仅需要 ICU 库本身的功能，例如 String.prototype.normalize() 和 WHATWG URL 解析器，在 small-icu 下得到完全支持。 此外，需要 ICU 区域设置数据的功能，例如 Intl.DateTimeFormat，通常仅适用于英语区域设置

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));
// Prints "January"
console.log(spanish.format(january));
// Prints either "M01" or "January" on small-icu, depending on the user’s default locale
// Should print "enero"

此模式在功能和二进制文件大小之间提供平衡。

在运行时提供 ICU 数据#

如果使用 small-icu 选项，仍然可以在运行时提供其他区域设置数据，以便 JS 方法可以用于所有 ICU 区域设置。 假设数据文件存储在 /runtime/directory/with/dat/file 中，可以通过以下任一方式使其可用于 ICU

  • --with-icu-default-data-dir 配置选项

    ./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu

    这只会将默认数据目录路径嵌入到二进制文件中。 实际的数据文件将在运行时从此目录路径加载。

  • NODE_ICU_DATA 环境变量

    env NODE_ICU_DATA=/runtime/directory/with/dat/file node

  • --icu-data-dir CLI 参数

    node --icu-data-dir=/runtime/directory/with/dat/file

当指定了多个参数时，--icu-data-dir CLI 参数的优先级最高，然后是 NODE_ICU_DATA 环境变量，然后是 --with-icu-default-data-dir 配置选项。

ICU 能够自动查找和加载各种数据格式，但是数据必须适合 ICU 版本，并且文件名称正确。 数据文件最常见的名称是 icudtX[bl].dat，其中 X 表示预期的 ICU 版本，b 或 l 表示系统的字节序。 如果无法从指定目录读取预期的数据文件，则 Node.js 将无法加载。 可以使用以下方法计算与当前 Node.js 版本对应的数据文件的名称

`icudt${process.versions.icu.split('.')[0]}${os.endianness()[0].toLowerCase()}.dat`;

有关其他支持的格式以及有关 ICU 数据的更多详细信息，请查看 ICU 用户指南中的"ICU 数据"文章。

full-icu npm 模块可以通过检测正在运行的 node 可执行文件的 ICU 版本并下载相应的数据文件来大大简化 ICU 数据的安装。 通过 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 的存在就足够了

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

或者，检查 process.versions.icu（仅在启用 ICU 时定义的属性）也有效

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

要检查对非英语区域设置（即 full-icu 或 system-icu）的支持，Intl.DateTimeFormat 可以是一个很好的区分因素

const hasFullICU = (() => {
  try {
    const january = new Date(9e8);
    const spanish = new Intl.DateTimeFormat('es', { month: 'long' });
    return spanish.format(january) === 'enero';
  } catch (err) {
    return false;
  }
})();

对于更详细的 Intl 支持测试，以下资源可能会有所帮助

  • btest402：通常用于检查是否正确构建了具有 Intl 支持的 Node.js。
  • Test262：ECMAScript 的官方一致性测试套件包括一个专门针对 ECMA-402 的部分。