国際化サポート

Node.js には、国際化されたプログラムをより簡単に記述するための多くの機能があります。その一部を以下に示します。

• ECMAScript 言語仕様 のロケール依存または Unicode 対応の関数：

  • String.prototype.normalize()
  • String.prototype.toLowerCase()
  • String.prototype.toUpperCase()

• ECMAScript Internationalization API 仕様 (別名 ECMA-402) に記述されているすべての機能：

  • Intl オブジェクト
  • String.prototype.localeCompare() や Date.prototype.toLocaleString() のようなロケール依存のメソッド

• WHATWG URL パーサー の 国際化ドメイン名 (IDN) サポート

• require('node:buffer').transcode()

• より正確な REPL 行編集

• require('node:util').TextDecoder

• RegExp Unicode プロパティエスケープ

Node.js と基盤となる V8 エンジンは、これらの機能をネイティブ C/C++コードで実装するために、International Components for Unicode（ICU）を使用します。完全な ICU データセットは、デフォルトで Node.js によって提供されます。ただし、ICU データファイルのサイズが大きいため、Node.js をビルドまたは実行するときに ICU データセットをカスタマイズするためのいくつかのオプションが提供されています。

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 機能の概要：

機能	none	system-icu	small-icu	full-icu
String.prototype.normalize()	なし（関数は no-op）	フル	フル	フル
String.prototype.to*Case()	フル	フル	フル	フル
Intl	なし（オブジェクトが存在しない）	部分的/フル（OS に依存）	部分的（英語のみ）	フル
String.prototype.localeCompare()	部分的（ロケールを認識しない）	フル	フル	フル
String.prototype.toLocale*Case()	部分的（ロケールを認識しない）	フル	フル	フル
Number.prototype.toLocaleString()	部分的（ロケールを認識しない）	部分的/フル（OS に依存）	部分的（英語のみ）	フル
Date.prototype.toLocale*String()	部分的（ロケールを認識しない）	部分的/フル（OS に依存）	部分的（英語のみ）	フル
レガシー URL パーサー	部分的（IDN サポートなし）	フル	フル	フル
WHATWG URL パーサー	部分的（IDN サポートなし）	フル	フル	フル
require('node:buffer').transcode()	なし（関数が存在しない）	フル	フル	フル
REPL	部分的（不正確な行編集）	フル	フル	フル
require('node:util').TextDecoder	部分的（基本的なエンコーディングをサポート）	部分的/フル（OS に依存）	部分的（Unicode のみ）	フル
RegExp Unicode プロパティエスケープ	なし（無効なRegExpエラー）	フル	フル	フル

"(ロケールを認識しない)" という指定は、関数が、もしあれば、関数の 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の下で完全にサポートされています。さらに ICU ロケールデータを必要とする機能（Intl.DateTimeFormatなど）は、システムにインストールされている ICU データの完全性に応じて、完全または部分的にサポートされる場合があります。

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

このオプションを使用すると、結果のバイナリは ICU ライブラリに静的にリンクされ、ICU データ（通常は英語ロケールのみ）のサブセットが node 実行可能ファイル内に含まれます。

String.prototype.normalize()やWHATWG URL パーサーなど、ICU ライブラリ自体のみを必要とする機能は、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))
// "January"と出力
console.log(spanish.format(january))
// small-icuでは、ユーザーのデフォルトロケールに応じて、"M01"または"January"と出力されます
// "enero"と出力されるべき

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

ランタイムでの ICU データの提供

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

• --with-icu-default-data-dir構成オプション：これはデフォルトのデータディレクトリパスをバイナリに埋め込むだけです。実際のデータファイルは、このディレクトリパスからランタイム時にロードされます。
• NODE_ICU_DATA環境変数：
• --icu-data-dir CLI パラメータ：

複数の指定がある場合、--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 Data"の記事を確認してください。

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'

または、ICU が有効な場合にのみ定義されるプロパティである process.versions.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 に特化したセクションが含まれています。