{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.0.json","id":"intl","path":"/intl","type":"misc","module":null,"title":"Internationalization support","introducedIn":"v8.2.0","sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Node.js has many features that make it easier to write internationalized\nprograms. Some of them are:\n\n* Locale-sensitive or Unicode-aware functions in the [ECMAScript Language\n  Specification](https://tc39.github.io/ecma262/):\n  * [`String.prototype.normalize()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize)\n  * [`String.prototype.toLowerCase()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase)\n  * [`String.prototype.toUpperCase()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase)\n* All functionality described in the [ECMAScript Internationalization API\n  Specification](https://tc39.github.io/ecma402/) (aka ECMA-402):\n  * [`Intl`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) object\n  * Locale-sensitive methods like [`String.prototype.localeCompare()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) and\n    [`Date.prototype.toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString)\n* The [WHATWG URL parser](url.html#the-whatwg-url-api)'s [internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) (IDNs) support\n* [`require('node:buffer').transcode()`](buffer.html#buffertranscodesource-fromenc-toenc)\n* More accurate [REPL](repl.html#repl) line editing\n* [`require('node:util').TextDecoder`](util.html#class-utiltextdecoder)\n* [`RegExp` Unicode Property Escapes](https://github.com/tc39/proposal-regexp-unicode-property-escapes)\n\nNode.js and the underlying V8 engine use\n[International Components for Unicode (ICU)](http://site.icu-project.org/) 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.","summary":"Node.js has many features that make it easier to write internationalized programs. Some of them are:","examples":[],"children":[{"kind":"section","id":"options-for-building-nodejs","name":"Options for building Node.js","title":"Options for building Node.js","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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](https://github.com/nodejs/node/blob/HEAD/BUILDING.md).\n\n* `--with-intl=none`/`--without-intl`\n* `--with-intl=system-icu`\n* `--with-intl=small-icu`\n* `--with-intl=full-icu` (default)\n\nAn overview of available Node.js and JavaScript features for each `configure`\noption:\n\n| Feature                                                                                                                                       | `none`                            | `system-icu`                 | `small-icu`            | `full-icu` |\n| --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------- | ---------------------- | ---------- |\n| [`String.prototype.normalize()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize)           | none (function is no-op)          | full                         | full                   | full       |\n| `String.prototype.to*Case()`                                                                                                                  | full                              | full                         | full                   | full       |\n| [`Intl`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)                                               | none (object does not exist)      | partial/full (depends on OS) | partial (English-only) | full       |\n| [`String.prototype.localeCompare()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare)   | partial (not locale-aware)        | full                         | full                   | full       |\n| `String.prototype.toLocale*Case()`                                                                                                            | partial (not locale-aware)        | full                         | full                   | full       |\n| [`Number.prototype.toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString) | partial (not locale-aware)        | partial/full (depends on OS) | partial (English-only) | full       |\n| `Date.prototype.toLocale*String()`                                                                                                            | partial (not locale-aware)        | partial/full (depends on OS) | partial (English-only) | full       |\n| [Legacy URL Parser](url.html#legacy-url-api)                                                                                                  | partial (no IDN support)          | full                         | full                   | full       |\n| [WHATWG URL Parser](url.html#the-whatwg-url-api)                                                                                              | partial (no IDN support)          | full                         | full                   | full       |\n| [`require('node:buffer').transcode()`](buffer.html#buffertranscodesource-fromenc-toenc)                                                       | none (function does not exist)    | full                         | full                   | full       |\n| [REPL](repl.html#repl)                                                                                                                        | partial (inaccurate line editing) | full                         | full                   | full       |\n| [`require('node:util').TextDecoder`](util.html#class-utiltextdecoder)                                                                         | partial (basic encodings support) | partial/full (depends on OS) | partial (Unicode-only) | full       |\n| [`RegExp` Unicode Property Escapes](https://github.com/tc39/proposal-regexp-unicode-property-escapes)                                         | none (invalid `RegExp` error)     | full                         | full                   | full       |\n\nThe \"(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()`.","summary":"To control how ICU is used in Node.js, four `configure` options are available during compilation. Additional details on how to compile Node.js are documented in BUILDING.md.","examples":[],"children":[{"kind":"section","id":"disable-all-internationalization-features-none","name":"Disable all internationalization features (none)","title":"Disable all internationalization features (`none`)","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"If this option is chosen, ICU is disabled and most internationalization\nfeatures mentioned above will be **unavailable** in the resulting `node` binary.","summary":"If this option is chosen, ICU is disabled and most internationalization features mentioned above will be **unavailable** in the resulting `node` binary.","examples":[],"children":[]},{"kind":"section","id":"build-with-a-pre-installed-icu-system-icu","name":"Build with a pre-installed ICU (system-icu)","title":"Build with a pre-installed ICU (`system-icu`)","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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\nFunctionalities that only require the ICU library itself, such as\n[`String.prototype.normalize()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) and the [WHATWG URL parser](url.html#the-whatwg-url-api), are fully\nsupported under `system-icu`. Features that require ICU locale data in\naddition, such as [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) *may* be fully or partially\nsupported, depending on the completeness of the ICU data installed on the\nsystem.","summary":"Node.js can link against an ICU build already installed on the system. In fact, most Linux distributions already come with ICU installed, and this option would make it possible to reuse the same set of data used by other components in the OS.","examples":[],"children":[]},{"kind":"section","id":"embed-a-limited-set-of-icu-data-small-icu","name":"Embed a limited set of ICU data (small-icu)","title":"Embed a limited set of ICU data (`small-icu`)","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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\nFunctionalities that only require the ICU library itself, such as\n[`String.prototype.normalize()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) and the [WHATWG URL parser](url.html#the-whatwg-url-api), are fully\nsupported under `small-icu`. Features that require ICU locale data in addition,\nsuch as [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), generally only work with the English locale:\n\n```js\nconst 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\nThis mode provides a balance between features and binary size.","summary":"This option makes the resulting binary link against the ICU library statically, and includes a subset of ICU data (typically only the English locale) within the `node` executable.","examples":[{"language":"js","displayName":null,"code":"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\""}],"children":[{"kind":"section","id":"providing-icu-data-at-runtime","name":"Providing ICU data at runtime","title":"Providing ICU data at runtime","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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 `/runtime/directory/with/dat/file`, it can be made\navailable to ICU through either:\n\n* The `--with-icu-default-data-dir` configure option:\n\n  ```bash\n  ./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu\n  ```\n\n  This only embeds the default data directory path into the binary.\n  The actual data file is going to be loaded at runtime from this directory\n  path.\n\n* The [`NODE_ICU_DATA`](cli.html#node_icu_datafile) environment variable:\n\n  ```bash\n  env NODE_ICU_DATA=/runtime/directory/with/dat/file node\n  ```\n\n* The [`--icu-data-dir`](cli.html#--icu-data-dirfile) CLI parameter:\n\n  ```bash\n  node --icu-data-dir=/runtime/directory/with/dat/file\n  ```\n\nWhen more than one of them is specified, the `--icu-data-dir` CLI parameter has\nthe highest precedence, then the `NODE_ICU_DATA`  environment variable, then\nthe `--with-icu-default-data-dir` configure option.\n\nICU 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 `icudtX[bl].dat`, where `X` denotes\nthe intended ICU version, and `b` or `l` indicates the system's endianness.\nNode.js would fail to load if the expected data file cannot be read from the\nspecified directory. The name of the data file corresponding to the current\nNode.js version can be computed with:\n\n```js\n`icudt${process.versions.icu.split('.')[0]}${os.endianness()[0].toLowerCase()}.dat`;\n```\n\nCheck [\"ICU Data\"](http://userguide.icu-project.org/icudata) article in the ICU User Guide for other supported formats\nand more details on ICU data in general.\n\nThe [full-icu](https://www.npmjs.com/package/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.","summary":"If the `small-icu` option is used, one can still provide additional locale data at runtime so that the JS methods would work for all ICU locales. Assuming the data file is stored at `/runtime/directory/with/dat/file`, it can be made available to ICU through either:","examples":[{"language":"bash","displayName":null,"code":"./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu"},{"language":"bash","displayName":null,"code":"env NODE_ICU_DATA=/runtime/directory/with/dat/file node"},{"language":"bash","displayName":null,"code":"node --icu-data-dir=/runtime/directory/with/dat/file"},{"language":"js","displayName":null,"code":"`icudt${process.versions.icu.split('.')[0]}${os.endianness()[0].toLowerCase()}.dat`;"}],"children":[]}]},{"kind":"section","id":"embed-the-entire-icu-full-icu","name":"Embed the entire ICU (full-icu)","title":"Embed the entire ICU (`full-icu`)","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"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.","summary":"This option makes the resulting binary link against ICU statically and include a full set of ICU data. A binary created this way has no further external dependencies and supports all locales, but might be rather large. This is the default behavior if no `--with-intl` flag is passed. The official binaries are also built in this mode.","examples":[],"children":[]}]},{"kind":"section","id":"detecting-internationalization-support","name":"Detecting internationalization support","title":"Detecting internationalization support","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"To verify that ICU is enabled at all (`system-icu`, `small-icu`, or\n`full-icu`), simply checking the existence of `Intl` should suffice:\n\n```js\nconst hasICU = typeof Intl === 'object';\n```\n\nAlternatively, checking for `process.versions.icu`, a property defined only\nwhen ICU is enabled, works too:\n\n```js\nconst hasICU = typeof process.versions.icu === 'string';\n```\n\nTo check for support for a non-English locale (i.e. `full-icu` or\n`system-icu`), [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) can be a good distinguishing factor:\n\n```js\nconst 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\nFor more verbose tests for `Intl` support, the following resources may be found\nto be helpful:\n\n* [btest402](https://github.com/srl295/btest402): Generally used to check whether Node.js with `Intl` support is\n  built correctly.\n* [Test262](https://github.com/tc39/test262/tree/HEAD/test/intl402): ECMAScript's official conformance test suite includes a section\n  dedicated to ECMA-402.","summary":"To verify that ICU is enabled at all (`system-icu`, `small-icu`, or `full-icu`), simply checking the existence of `Intl` should suffice:","examples":[{"language":"js","displayName":null,"code":"const hasICU = typeof Intl === 'object';"},{"language":"js","displayName":null,"code":"const hasICU = typeof process.versions.icu === 'string';"},{"language":"js","displayName":null,"code":"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})();"}],"children":[]}]}