{ "type": "module", "source": "doc/api/intl.md", "introduced_in": "v8.2.0", "miscs": [ { "textRaw": "Internationalization support", "name": "Internationalization support", "introduced_in": "v8.2.0", "type": "misc", "desc": "

Node.js has many features that make it easier to write internationalized\nprograms. Some of them are:

\n\n

Node.js and the underlying V8 engine use\nInternational Components for Unicode (ICU) to implement these features\nin native C/C++ code. The full ICU data set is provided by Node.js by default.\nHowever, due to the size of the ICU data file, several\noptions are provided for customizing the ICU data set either when\nbuilding or running Node.js.

", "miscs": [ { "textRaw": "Options for building Node.js", "name": "options_for_building_node.js", "desc": "

To control how ICU is used in Node.js, four configure options are available\nduring compilation. Additional details on how to compile Node.js are documented\nin BUILDING.md.

\n\n

An overview of available Node.js and JavaScript features for each configure\noption:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Featurenonesystem-icusmall-icufull-icu
String.prototype.normalize()none (function is no-op)fullfullfull
String.prototype.to*Case()fullfullfullfull
Intlnone (object does not exist)partial/full (depends on OS)partial (English-only)full
String.prototype.localeCompare()partial (not locale-aware)fullfullfull
String.prototype.toLocale*Case()partial (not locale-aware)fullfullfull
Number.prototype.toLocaleString()partial (not locale-aware)partial/full (depends on OS)partial (English-only)full
Date.prototype.toLocale*String()partial (not locale-aware)partial/full (depends on OS)partial (English-only)full
Legacy URL Parserpartial (no IDN support)fullfullfull
WHATWG URL Parserpartial (no IDN support)fullfullfull
require('node:buffer').transcode()none (function does not exist)fullfullfull
REPLpartial (inaccurate line editing)fullfullfull
require('node:util').TextDecoderpartial (basic encodings support)partial/full (depends on OS)partial (Unicode-only)full
RegExp Unicode Property Escapesnone (invalid RegExp error)fullfullfull
\n

The \"(not locale-aware)\" designation denotes that the function carries out its\noperation just like the non-Locale version of the function, if one\nexists. For example, under none mode, Date.prototype.toLocaleString()'s\noperation is identical to that of Date.prototype.toString().

", "modules": [ { "textRaw": "Disable all internationalization features (`none`)", "name": "disable_all_internationalization_features_(`none`)", "desc": "

If this option is chosen, ICU is disabled and most internationalization\nfeatures mentioned above will be unavailable in the resulting node binary.

", "type": "module", "displayName": "Disable all internationalization features (`none`)" }, { "textRaw": "Build with a pre-installed ICU (`system-icu`)", "name": "build_with_a_pre-installed_icu_(`system-icu`)", "desc": "

Node.js can link against an ICU build already installed on the system. In fact,\nmost Linux distributions already come with ICU installed, and this option would\nmake it possible to reuse the same set of data used by other components in the\nOS.

\n

Functionalities that only require the ICU library itself, such as\nString.prototype.normalize() and the WHATWG URL parser, are fully\nsupported under system-icu. Features that require ICU locale data in\naddition, such as Intl.DateTimeFormat may be fully or partially\nsupported, depending on the completeness of the ICU data installed on the\nsystem.

", "type": "module", "displayName": "Build with a pre-installed ICU (`system-icu`)" }, { "textRaw": "Embed a limited set of ICU data (`small-icu`)", "name": "embed_a_limited_set_of_icu_data_(`small-icu`)", "desc": "

This option makes the resulting binary link against the ICU library statically,\nand includes a subset of ICU data (typically only the English locale) within\nthe node executable.

\n

Functionalities that only require the ICU library itself, such as\nString.prototype.normalize() and the WHATWG URL parser, are fully\nsupported under small-icu. Features that require ICU locale data in addition,\nsuch as Intl.DateTimeFormat, generally only work with the English locale:

\n
const january = new Date(9e8);\nconst english = new Intl.DateTimeFormat('en', { month: 'long' });\nconst spanish = new Intl.DateTimeFormat('es', { month: 'long' });\n\nconsole.log(english.format(january));\n// Prints \"January\"\nconsole.log(spanish.format(january));\n// Prints either \"M01\" or \"January\" on small-icu, depending on the user’s default locale\n// Should print \"enero\"\n
\n

This mode provides a balance between features and binary size.

", "modules": [ { "textRaw": "Providing ICU data at runtime", "name": "providing_icu_data_at_runtime", "desc": "

If the small-icu option is used, one can still provide additional locale data\nat runtime so that the JS methods would work for all ICU locales. Assuming the\ndata file is stored at /some/directory, it can be made available to ICU\nthrough either:

\n\n

(If both are specified, the --icu-data-dir CLI parameter takes precedence.)

\n

ICU is able to automatically find and load a variety of data formats, but the\ndata must be appropriate for the ICU version, and the file correctly named.\nThe most common name for the data file is icudt6X[bl].dat, where 6X denotes\nthe intended ICU version, and b or l indicates the system's endianness.\nCheck \"ICU Data\" article in the ICU User Guide for other supported formats\nand more details on ICU data in general.

\n

The full-icu npm module can greatly simplify ICU data installation by\ndetecting the ICU version of the running node executable and downloading the\nappropriate data file. After installing the module through npm i full-icu,\nthe data file will be available at ./node_modules/full-icu. This path can be\nthen passed either to NODE_ICU_DATA or --icu-data-dir as shown above to\nenable full Intl support.

", "type": "module", "displayName": "Providing ICU data at runtime" } ], "type": "module", "displayName": "Embed a limited set of ICU data (`small-icu`)" }, { "textRaw": "Embed the entire ICU (`full-icu`)", "name": "embed_the_entire_icu_(`full-icu`)", "desc": "

This option makes the resulting binary link against ICU statically and include\na full set of ICU data. A binary created this way has no further external\ndependencies and supports all locales, but might be rather large. This is\nthe default behavior if no --with-intl flag is passed. The official binaries\nare also built in this mode.

", "type": "module", "displayName": "Embed the entire ICU (`full-icu`)" } ], "type": "misc", "displayName": "Options for building Node.js" }, { "textRaw": "Detecting internationalization support", "name": "detecting_internationalization_support", "desc": "

To verify that ICU is enabled at all (system-icu, small-icu, or\nfull-icu), simply checking the existence of Intl should suffice:

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

Alternatively, checking for process.versions.icu, a property defined only\nwhen ICU is enabled, works too:

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

To check for support for a non-English locale (i.e. full-icu or\nsystem-icu), Intl.DateTimeFormat can be a good distinguishing factor:

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

For more verbose tests for Intl support, the following resources may be found\nto be helpful:

\n", "type": "misc", "displayName": "Detecting internationalization support" } ] } ] }