Node.js v21.7.2 ドキュメント

Node.js をビルドするためのオプション#

Node.js で ICU がどのように使用されるかを制御するために、コンパイル時に 4 つの 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 機能の概要

「(ロケール非対応)」の指定は、関数が、もし存在すれば、その関数の非 Locale バージョンと同じように動作を実行することを示します。たとえば、none モードでは、Date.prototype.toLocaleString() の動作は Date.prototype.toString() の動作と同一です。

すべての国際化機能を無効にする (none)#

このオプションを選択した場合、ICU は無効になり、上記のほとんどの国際化機能は、結果の node バイナリで利用できなくなります。

プリインストールされた ICU でビルドする (system-icu)#

Node.js は、システムにすでにインストールされている ICU ビルドに対してリンクできます。実際、ほとんどの Linux ディストリビューションには ICU がインストールされており、このオプションを使用すると、OS の他のコンポーネントで使用されているのと同じデータセットを再利用できます。

String.prototype.normalize() や WHATWG URL パーサー など、ICU ライブラリ自体のみを必要とする機能は、system-icu の下で完全にサポートされます。 Intl.DateTimeFormat など、ICU ロケールデータも必要とする機能は、システムにインストールされている ICU データの完全性に応じて、完全または部分的にサポートされる 場合があります。

限定された ICU データセットを埋め込む (small-icu)#

このオプションにより、結果のバイナリは ICU ライブラリに対して静的にリンクし、ICU データ (通常は英語ロケールのみ) のサブセットを node 実行可能ファイルに含めます。

String.prototype.normalize() や WHATWG URL パーサー など、ICU ライブラリ自体のみを必要とする機能は、small-icu の下で完全にサポートされます。Intl.DateTimeFormat など、ICU ロケールデータも必要とする機能は、一般的に英語ロケールでのみ動作します。

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" copy

このモードでは、機能とバイナリサイズのバランスが提供されます。

ランタイムで ICU データを提供する#

small-icu オプションを使用した場合でも、すべての ICU ロケールに対して JS メソッドが機能するように、実行時に追加のロケールデータを提供できます。データファイルが /runtime/directory/with/dat/file に保存されていると仮定すると、次のいずれかを使用して ICU で利用できるようにすることができます。

• --with-icu-default-data-dir configure オプション

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

  これは、デフォルトのデータディレクトリパスをバイナリに埋め込むだけです。実際のデータファイルは、このディレクトリパスから実行時にロードされます。

• NODE_ICU_DATA 環境変数

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

• --icu-data-dir CLI パラメーター

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

上記の複数が指定されている場合、--icu-data-dir CLI パラメーターが最も優先度が高く、次に NODE_ICU_DATA 環境変数、そして --with-icu-default-data-dir configure オプションが続きます。

ICU は、さまざまなデータ形式を自動的に検索してロードできますが、データは ICU バージョンに適しており、ファイル名は正しく命名されている必要があります。データファイルの最も一般的な名前は icudtX[bl].dat で、X は対象の ICU バージョンを示し、b または l はシステムのエンディアンを示します。指定されたディレクトリから予期されるデータファイルを読み取ることができない場合、Node.js はロードに失敗します。現在の Node.js バージョンに対応するデータファイルの名前は、次のように計算できます。

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

その他のサポートされる形式と 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'; copy

または、ICUが有効な場合にのみ定義されるプロパティであるprocess.versions.icuを確認することもできます。

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

英語以外のロケール（つまり、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;
  }
})(); copy

Intlのサポートに関するより詳細なテストについては、以下のリソースが役立つ可能性があります。

• btest402: 一般的に、Intlサポート付きのNode.jsが正しくビルドされているかどうかを確認するために使用されます。
• Test262: ECMAScriptの公式適合性テストスイートには、ECMA-402専用のセクションが含まれています。