CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width"> <meta name="nodejs.org:node-version" content="v23.3.0"> <title>Internationalization support | Node.js v23.3.0 Documentation</title> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> <link rel="stylesheet" href="assets/style.css"> <link rel="stylesheet" href="assets/hljs.css"> <link rel="canonical" href="https://nodejs.org/api/intl.html"> <script async defer src="assets/api.js" type="text/javascript"></script> <script> const storedTheme = localStorage.getItem('theme'); // Follow operating system theme preference if (storedTheme === null && window.matchMedia) { const mq = window.matchMedia('(prefers-color-scheme: dark)'); if (mq.matches) { document.documentElement.classList.add('dark-mode'); } } else if (storedTheme === 'dark') { document.documentElement.classList.add('dark-mode'); } </script> </head> <body class="alt apidoc" id="api-section-intl"> <div id="content" class="clearfix"> <div role="navigation" id="column2" class="interior"> <div id="intro" class="interior"> <a href="/" title="Go back to the home page"> Node.js </a> </div> <ul> <li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> <li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> </ul> <hr class="line"> <ul> <li><a href="assert.html" class="nav-assert">Assertion testing</a></li> <li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> <li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> <li><a href="buffer.html" class="nav-buffer">Buffer</a></li> <li><a href="addons.html" class="nav-addons">C++ addons</a></li> <li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> <li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> <li><a href="child_process.html" class="nav-child_process">Child processes</a></li> <li><a href="cluster.html" class="nav-cluster">Cluster</a></li> <li><a href="cli.html" class="nav-cli">Command-line options</a></li> <li><a href="console.html" class="nav-console">Console</a></li> <li><a href="corepack.html" class="nav-corepack">Corepack</a></li> <li><a href="crypto.html" class="nav-crypto">Crypto</a></li> <li><a href="debugger.html" class="nav-debugger">Debugger</a></li> <li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> <li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> <li><a href="dns.html" class="nav-dns">DNS</a></li> <li><a href="domain.html" class="nav-domain">Domain</a></li> <li><a href="errors.html" class="nav-errors">Errors</a></li> <li><a href="events.html" class="nav-events">Events</a></li> <li><a href="fs.html" class="nav-fs">File system</a></li> <li><a href="globals.html" class="nav-globals">Globals</a></li> <li><a href="http.html" class="nav-http">HTTP</a></li> <li><a href="http2.html" class="nav-http2">HTTP/2</a></li> <li><a href="https.html" class="nav-https">HTTPS</a></li> <li><a href="inspector.html" class="nav-inspector">Inspector</a></li> <li><a href="intl.html" class="nav-intl active">Internationalization</a></li> <li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> <li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> <li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> <li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> <li><a href="typescript.html" class="nav-typescript">Modules: TypeScript</a></li> <li><a href="net.html" class="nav-net">Net</a></li> <li><a href="os.html" class="nav-os">OS</a></li> <li><a href="path.html" class="nav-path">Path</a></li> <li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> <li><a href="permissions.html" class="nav-permissions">Permissions</a></li> <li><a href="process.html" class="nav-process">Process</a></li> <li><a href="punycode.html" class="nav-punycode">Punycode</a></li> <li><a href="querystring.html" class="nav-querystring">Query strings</a></li> <li><a href="readline.html" class="nav-readline">Readline</a></li> <li><a href="repl.html" class="nav-repl">REPL</a></li> <li><a href="report.html" class="nav-report">Report</a></li> <li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> <li><a href="sqlite.html" class="nav-sqlite">SQLite</a></li> <li><a href="stream.html" class="nav-stream">Stream</a></li> <li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> <li><a href="test.html" class="nav-test">Test runner</a></li> <li><a href="timers.html" class="nav-timers">Timers</a></li> <li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> <li><a href="tracing.html" class="nav-tracing">Trace events</a></li> <li><a href="tty.html" class="nav-tty">TTY</a></li> <li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> <li><a href="url.html" class="nav-url">URL</a></li> <li><a href="util.html" class="nav-util">Utilities</a></li> <li><a href="v8.html" class="nav-v8">V8</a></li> <li><a href="vm.html" class="nav-vm">VM</a></li> <li><a href="wasi.html" class="nav-wasi">WASI</a></li> <li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> <li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> <li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> <li><a href="zlib.html" class="nav-zlib">Zlib</a></li> </ul> <hr class="line"> <ul> <li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> </ul> </div> <div id="column1" data-id="intl" class="interior"> <header class="header"> <div class="header-container"> <h1>Node.js v23.3.0 documentation</h1> <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> <path fill="none" d="M0 0h24v24H0z" /> <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> </svg> <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> <path d="M0 0h24v24H0z" fill="none" /> <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> </svg> </button> </div> <div id="gtoc"> <ul> <li class="pinned-header">Node.js v23.3.0</li> <li class="picker-header"> <a href="#"> <span class="picker-arrow"></span> Table of contents </a> <div class="picker"><div class="toc"><ul> <li><a href="#internationalization-support">Internationalization support</a> <ul> <li><a href="#options-for-building-nodejs">Options for building Node.js</a> <ul> <li><a href="#disable-all-internationalization-features-none">Disable all internationalization features (<code>none</code>)</a></li> <li><a href="#build-with-a-pre-installed-icu-system-icu">Build with a pre-installed ICU (<code>system-icu</code>)</a></li> <li><a href="#embed-a-limited-set-of-icu-data-small-icu">Embed a limited set of ICU data (<code>small-icu</code>)</a> <ul> <li><a href="#providing-icu-data-at-runtime">Providing ICU data at runtime</a></li> </ul> </li> <li><a href="#embed-the-entire-icu-full-icu">Embed the entire ICU (<code>full-icu</code>)</a></li> </ul> </li> <li><a href="#detecting-internationalization-support">Detecting internationalization support</a></li> </ul> </li> </ul></div></div> </li> <li class="picker-header"> <a href="#"> <span class="picker-arrow"></span> Index </a> <div class="picker"><ul> <li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> <li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> <li> <a href="index.html">Index</a> </li> </ul> <hr class="line"> <ul> <li><a href="assert.html" class="nav-assert">Assertion testing</a></li> <li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> <li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> <li><a href="buffer.html" class="nav-buffer">Buffer</a></li> <li><a href="addons.html" class="nav-addons">C++ addons</a></li> <li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> <li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> <li><a href="child_process.html" class="nav-child_process">Child processes</a></li> <li><a href="cluster.html" class="nav-cluster">Cluster</a></li> <li><a href="cli.html" class="nav-cli">Command-line options</a></li> <li><a href="console.html" class="nav-console">Console</a></li> <li><a href="corepack.html" class="nav-corepack">Corepack</a></li> <li><a href="crypto.html" class="nav-crypto">Crypto</a></li> <li><a href="debugger.html" class="nav-debugger">Debugger</a></li> <li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> <li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> <li><a href="dns.html" class="nav-dns">DNS</a></li> <li><a href="domain.html" class="nav-domain">Domain</a></li> <li><a href="errors.html" class="nav-errors">Errors</a></li> <li><a href="events.html" class="nav-events">Events</a></li> <li><a href="fs.html" class="nav-fs">File system</a></li> <li><a href="globals.html" class="nav-globals">Globals</a></li> <li><a href="http.html" class="nav-http">HTTP</a></li> <li><a href="http2.html" class="nav-http2">HTTP/2</a></li> <li><a href="https.html" class="nav-https">HTTPS</a></li> <li><a href="inspector.html" class="nav-inspector">Inspector</a></li> <li><a href="intl.html" class="nav-intl active">Internationalization</a></li> <li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> <li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> <li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> <li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> <li><a href="typescript.html" class="nav-typescript">Modules: TypeScript</a></li> <li><a href="net.html" class="nav-net">Net</a></li> <li><a href="os.html" class="nav-os">OS</a></li> <li><a href="path.html" class="nav-path">Path</a></li> <li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> <li><a href="permissions.html" class="nav-permissions">Permissions</a></li> <li><a href="process.html" class="nav-process">Process</a></li> <li><a href="punycode.html" class="nav-punycode">Punycode</a></li> <li><a href="querystring.html" class="nav-querystring">Query strings</a></li> <li><a href="readline.html" class="nav-readline">Readline</a></li> <li><a href="repl.html" class="nav-repl">REPL</a></li> <li><a href="report.html" class="nav-report">Report</a></li> <li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> <li><a href="sqlite.html" class="nav-sqlite">SQLite</a></li> <li><a href="stream.html" class="nav-stream">Stream</a></li> <li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> <li><a href="test.html" class="nav-test">Test runner</a></li> <li><a href="timers.html" class="nav-timers">Timers</a></li> <li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> <li><a href="tracing.html" class="nav-tracing">Trace events</a></li> <li><a href="tty.html" class="nav-tty">TTY</a></li> <li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> <li><a href="url.html" class="nav-url">URL</a></li> <li><a href="util.html" class="nav-util">Utilities</a></li> <li><a href="v8.html" class="nav-v8">V8</a></li> <li><a href="vm.html" class="nav-vm">VM</a></li> <li><a href="wasi.html" class="nav-wasi">WASI</a></li> <li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> <li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> <li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> <li><a href="zlib.html" class="nav-zlib">Zlib</a></li> </ul> <hr class="line"> <ul> <li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> </ul></div> </li> <li class="picker-header"> <a href="#"> <span class="picker-arrow"></span> Other versions </a> <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v23.x/api/intl.html">23.x</a></li> <li><a href="https://nodejs.org/docs/latest-v22.x/api/intl.html">22.x <b>LTS</b></a></li> <li><a href="https://nodejs.org/docs/latest-v21.x/api/intl.html">21.x</a></li> <li><a href="https://nodejs.org/docs/latest-v20.x/api/intl.html">20.x <b>LTS</b></a></li> <li><a href="https://nodejs.org/docs/latest-v19.x/api/intl.html">19.x</a></li> <li><a href="https://nodejs.org/docs/latest-v18.x/api/intl.html">18.x <b>LTS</b></a></li> <li><a href="https://nodejs.org/docs/latest-v17.x/api/intl.html">17.x</a></li> <li><a href="https://nodejs.org/docs/latest-v16.x/api/intl.html">16.x</a></li> <li><a href="https://nodejs.org/docs/latest-v15.x/api/intl.html">15.x</a></li> <li><a href="https://nodejs.org/docs/latest-v14.x/api/intl.html">14.x</a></li> <li><a href="https://nodejs.org/docs/latest-v13.x/api/intl.html">13.x</a></li> <li><a href="https://nodejs.org/docs/latest-v12.x/api/intl.html">12.x</a></li> <li><a href="https://nodejs.org/docs/latest-v11.x/api/intl.html">11.x</a></li> <li><a href="https://nodejs.org/docs/latest-v10.x/api/intl.html">10.x</a></li> <li><a href="https://nodejs.org/docs/latest-v9.x/api/intl.html">9.x</a></li> <li><a href="https://nodejs.org/docs/latest-v8.x/api/intl.html">8.x</a></li></ol></div> </li> <li class="picker-header"> <a href="#"> <span class="picker-arrow"></span> Options </a> <div class="picker"> <ul> <li> <a href="all.html">View on single page</a> </li> <li> <a href="intl.json">View as JSON</a> </li> <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/intl.md">Edit on GitHub</a></li> </ul> </div> </li> </ul> </div> <hr> </header> <details role="navigation" id="toc" open><summary>Table of contents</summary><ul> <li><a href="#internationalization-support">Internationalization support</a> <ul> <li><a href="#options-for-building-nodejs">Options for building Node.js</a> <ul> <li><a href="#disable-all-internationalization-features-none">Disable all internationalization features (<code>none</code>)</a></li> <li><a href="#build-with-a-pre-installed-icu-system-icu">Build with a pre-installed ICU (<code>system-icu</code>)</a></li> <li><a href="#embed-a-limited-set-of-icu-data-small-icu">Embed a limited set of ICU data (<code>small-icu</code>)</a> <ul> <li><a href="#providing-icu-data-at-runtime">Providing ICU data at runtime</a></li> </ul> </li> <li><a href="#embed-the-entire-icu-full-icu">Embed the entire ICU (<code>full-icu</code>)</a></li> </ul> </li> <li><a href="#detecting-internationalization-support">Detecting internationalization support</a></li> </ul> </li> </ul></details> <div role="main" id="apicontent"> <h2>Internationalization support<span><a class="mark" href="#internationalization-support" id="internationalization-support">#</a></span><a aria-hidden="true" class="legacy" id="intl_internationalization_support"></a></h2> <p>Node.js has many features that make it easier to write internationalized programs. Some of them are:</p> <ul> <li>Locale-sensitive or Unicode-aware functions in the <a href="https://tc39.github.io/ecma262/">ECMAScript Language Specification</a>: <ul> <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize"><code>String.prototype.normalize()</code></a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase"><code>String.prototype.toLowerCase()</code></a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase"><code>String.prototype.toUpperCase()</code></a></li> </ul> </li> <li>All functionality described in the <a href="https://tc39.github.io/ecma402/">ECMAScript Internationalization API Specification</a> (aka ECMA-402): <ul> <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl"><code>Intl</code></a> object</li> <li>Locale-sensitive methods like <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare"><code>String.prototype.localeCompare()</code></a> and <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString"><code>Date.prototype.toLocaleString()</code></a></li> </ul> </li> <li>The <a href="url.html#the-whatwg-url-api">WHATWG URL parser</a>'s <a href="https://en.wikipedia.org/wiki/Internationalized_domain_name">internationalized domain names</a> (IDNs) support</li> <li><a href="buffer.html#buffertranscodesource-fromenc-toenc"><code>require('node:buffer').transcode()</code></a></li> <li>More accurate <a href="repl.html#repl">REPL</a> line editing</li> <li><a href="util.html#class-utiltextdecoder"><code>require('node:util').TextDecoder</code></a></li> <li><a href="https://github.com/tc39/proposal-regexp-unicode-property-escapes"><code>RegExp</code> Unicode Property Escapes</a></li> </ul> <p>Node.js and the underlying V8 engine use <a href="http://site.icu-project.org/">International Components for Unicode (ICU)</a> to implement these features in native C/C++ code. The full ICU data set is provided by Node.js by default. However, due to the size of the ICU data file, several options are provided for customizing the ICU data set either when building or running Node.js.</p> <section><h3>Options for building Node.js<span><a class="mark" href="#options-for-building-nodejs" id="options-for-building-nodejs">#</a></span><a aria-hidden="true" class="legacy" id="intl_options_for_building_node_js"></a></h3> <p>To control how ICU is used in Node.js, four <code>configure</code> options are available during compilation. Additional details on how to compile Node.js are documented in <a href="https://github.com/nodejs/node/blob/HEAD/BUILDING.md">BUILDING.md</a>.</p> <ul> <li><code>--with-intl=none</code>/<code>--without-intl</code></li> <li><code>--with-intl=system-icu</code></li> <li><code>--with-intl=small-icu</code></li> <li><code>--with-intl=full-icu</code> (default)</li> </ul> <p>An overview of available Node.js and JavaScript features for each <code>configure</code> option:</p> <table><thead><tr><th>Feature</th><th><code>none</code></th><th><code>system-icu</code></th><th><code>small-icu</code></th><th><code>full-icu</code></th></tr></thead><tbody><tr><td><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize"><code>String.prototype.normalize()</code></a></td><td>none (function is no-op)</td><td>full</td><td>full</td><td>full</td></tr><tr><td><code>String.prototype.to*Case()</code></td><td>full</td><td>full</td><td>full</td><td>full</td></tr><tr><td><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl"><code>Intl</code></a></td><td>none (object does not exist)</td><td>partial/full (depends on OS)</td><td>partial (English-only)</td><td>full</td></tr><tr><td><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare"><code>String.prototype.localeCompare()</code></a></td><td>partial (not locale-aware)</td><td>full</td><td>full</td><td>full</td></tr><tr><td><code>String.prototype.toLocale*Case()</code></td><td>partial (not locale-aware)</td><td>full</td><td>full</td><td>full</td></tr><tr><td><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString"><code>Number.prototype.toLocaleString()</code></a></td><td>partial (not locale-aware)</td><td>partial/full (depends on OS)</td><td>partial (English-only)</td><td>full</td></tr><tr><td><code>Date.prototype.toLocale*String()</code></td><td>partial (not locale-aware)</td><td>partial/full (depends on OS)</td><td>partial (English-only)</td><td>full</td></tr><tr><td><a href="url.html#legacy-url-api">Legacy URL Parser</a></td><td>partial (no IDN support)</td><td>full</td><td>full</td><td>full</td></tr><tr><td><a href="url.html#the-whatwg-url-api">WHATWG URL Parser</a></td><td>partial (no IDN support)</td><td>full</td><td>full</td><td>full</td></tr><tr><td><a href="buffer.html#buffertranscodesource-fromenc-toenc"><code>require('node:buffer').transcode()</code></a></td><td>none (function does not exist)</td><td>full</td><td>full</td><td>full</td></tr><tr><td><a href="repl.html#repl">REPL</a></td><td>partial (inaccurate line editing)</td><td>full</td><td>full</td><td>full</td></tr><tr><td><a href="util.html#class-utiltextdecoder"><code>require('node:util').TextDecoder</code></a></td><td>partial (basic encodings support)</td><td>partial/full (depends on OS)</td><td>partial (Unicode-only)</td><td>full</td></tr><tr><td><a href="https://github.com/tc39/proposal-regexp-unicode-property-escapes"><code>RegExp</code> Unicode Property Escapes</a></td><td>none (invalid <code>RegExp</code> error)</td><td>full</td><td>full</td><td>full</td></tr></tbody></table> <p>The "(not locale-aware)" designation denotes that the function carries out its operation just like the non-<code>Locale</code> version of the function, if one exists. For example, under <code>none</code> mode, <code>Date.prototype.toLocaleString()</code>'s operation is identical to that of <code>Date.prototype.toString()</code>.</p> <h4>Disable all internationalization features (<code>none</code>)<span><a class="mark" href="#disable-all-internationalization-features-none" id="disable-all-internationalization-features-none">#</a></span><a aria-hidden="true" class="legacy" id="intl_disable_all_internationalization_features_none"></a></h4> <p>If this option is chosen, ICU is disabled and most internationalization features mentioned above will be <strong>unavailable</strong> in the resulting <code>node</code> binary.</p> <h4>Build with a pre-installed ICU (<code>system-icu</code>)<span><a class="mark" href="#build-with-a-pre-installed-icu-system-icu" id="build-with-a-pre-installed-icu-system-icu">#</a></span><a aria-hidden="true" class="legacy" id="intl_build_with_a_pre_installed_icu_system_icu"></a></h4> <p>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.</p> <p>Functionalities that only require the ICU library itself, such as <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize"><code>String.prototype.normalize()</code></a> and the <a href="url.html#the-whatwg-url-api">WHATWG URL parser</a>, are fully supported under <code>system-icu</code>. Features that require ICU locale data in addition, such as <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat"><code>Intl.DateTimeFormat</code></a> <em>may</em> be fully or partially supported, depending on the completeness of the ICU data installed on the system.</p> <h4>Embed a limited set of ICU data (<code>small-icu</code>)<span><a class="mark" href="#embed-a-limited-set-of-icu-data-small-icu" id="embed-a-limited-set-of-icu-data-small-icu">#</a></span><a aria-hidden="true" class="legacy" id="intl_embed_a_limited_set_of_icu_data_small_icu"></a></h4> <p>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 <code>node</code> executable.</p> <p>Functionalities that only require the ICU library itself, such as <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize"><code>String.prototype.normalize()</code></a> and the <a href="url.html#the-whatwg-url-api">WHATWG URL parser</a>, are fully supported under <code>small-icu</code>. Features that require ICU locale data in addition, such as <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat"><code>Intl.DateTimeFormat</code></a>, generally only work with the English locale:</p> <pre><code class="language-js"><span class="hljs-keyword">const</span> january = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Date</span>(<span class="hljs-number">9e8</span>); <span class="hljs-keyword">const</span> english = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Intl</span>.<span class="hljs-title class_">DateTimeFormat</span>(<span class="hljs-string">'en'</span>, { <span class="hljs-attr">month</span>: <span class="hljs-string">'long'</span> }); <span class="hljs-keyword">const</span> spanish = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Intl</span>.<span class="hljs-title class_">DateTimeFormat</span>(<span class="hljs-string">'es'</span>, { <span class="hljs-attr">month</span>: <span class="hljs-string">'long'</span> }); <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(english.<span class="hljs-title function_">format</span>(january)); <span class="hljs-comment">// Prints "January"</span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(spanish.<span class="hljs-title function_">format</span>(january)); <span class="hljs-comment">// Prints either "M01" or "January" on small-icu, depending on the user鈥檚 default locale</span> <span class="hljs-comment">// Should print "enero"</span></code> <button class="copy-button">copy</button></pre> <p>This mode provides a balance between features and binary size.</p> <h5>Providing ICU data at runtime<span><a class="mark" href="#providing-icu-data-at-runtime" id="providing-icu-data-at-runtime">#</a></span><a aria-hidden="true" class="legacy" id="intl_providing_icu_data_at_runtime"></a></h5> <p>If the <code>small-icu</code> 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 <code>/runtime/directory/with/dat/file</code>, it can be made available to ICU through either:</p> <ul> <li> <p>The <code>--with-icu-default-data-dir</code> configure option:</p> <pre><code class="language-bash">./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu</code> <button class="copy-button">copy</button></pre> <p>This only embeds the default data directory path into the binary. The actual data file is going to be loaded at runtime from this directory path.</p> </li> <li> <p>The <a href="cli.html#node_icu_datafile"><code>NODE_ICU_DATA</code></a> environment variable:</p> <pre><code class="language-bash"><span class="hljs-built_in">env</span> NODE_ICU_DATA=/runtime/directory/with/dat/file node</code> <button class="copy-button">copy</button></pre> </li> <li> <p>The <a href="cli.html#--icu-data-dirfile"><code>--icu-data-dir</code></a> CLI parameter:</p> <pre><code class="language-bash">node --icu-data-dir=/runtime/directory/with/dat/file</code> <button class="copy-button">copy</button></pre> </li> </ul> <p>When more than one of them is specified, the <code>--icu-data-dir</code> CLI parameter has the highest precedence, then the <code>NODE_ICU_DATA</code> environment variable, then the <code>--with-icu-default-data-dir</code> configure option.</p> <p>ICU is able to automatically find and load a variety of data formats, but the data must be appropriate for the ICU version, and the file correctly named. The most common name for the data file is <code>icudtX[bl].dat</code>, where <code>X</code> denotes the intended ICU version, and <code>b</code> or <code>l</code> indicates the system's endianness. Node.js would fail to load if the expected data file cannot be read from the specified directory. The name of the data file corresponding to the current Node.js version can be computed with:</p> <pre><code class="language-js"><span class="hljs-string">`icudt<span class="hljs-subst">${process.versions.icu.split(<span class="hljs-string">'.'</span>)[<span class="hljs-number">0</span>]}</span><span class="hljs-subst">${os.endianness()[<span class="hljs-number">0</span>].toLowerCase()}</span>.dat`</span>;</code> <button class="copy-button">copy</button></pre> <p>Check <a href="http://userguide.icu-project.org/icudata">"ICU Data"</a> article in the ICU User Guide for other supported formats and more details on ICU data in general.</p> <p>The <a href="https://www.npmjs.com/package/full-icu">full-icu</a> npm module can greatly simplify ICU data installation by detecting the ICU version of the running <code>node</code> executable and downloading the appropriate data file. After installing the module through <code>npm i full-icu</code>, the data file will be available at <code>./node_modules/full-icu</code>. This path can be then passed either to <code>NODE_ICU_DATA</code> or <code>--icu-data-dir</code> as shown above to enable full <code>Intl</code> support.</p> <h4>Embed the entire ICU (<code>full-icu</code>)<span><a class="mark" href="#embed-the-entire-icu-full-icu" id="embed-the-entire-icu-full-icu">#</a></span><a aria-hidden="true" class="legacy" id="intl_embed_the_entire_icu_full_icu"></a></h4> <p>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 <code>--with-intl</code> flag is passed. The official binaries are also built in this mode.</p> </section><section><h3>Detecting internationalization support<span><a class="mark" href="#detecting-internationalization-support" id="detecting-internationalization-support">#</a></span><a aria-hidden="true" class="legacy" id="intl_detecting_internationalization_support"></a></h3> <p>To verify that ICU is enabled at all (<code>system-icu</code>, <code>small-icu</code>, or <code>full-icu</code>), simply checking the existence of <code>Intl</code> should suffice:</p> <pre><code class="language-js"><span class="hljs-keyword">const</span> hasICU = <span class="hljs-keyword">typeof</span> <span class="hljs-title class_">Intl</span> === <span class="hljs-string">'object'</span>;</code> <button class="copy-button">copy</button></pre> <p>Alternatively, checking for <code>process.versions.icu</code>, a property defined only when ICU is enabled, works too:</p> <pre><code class="language-js"><span class="hljs-keyword">const</span> hasICU = <span class="hljs-keyword">typeof</span> process.<span class="hljs-property">versions</span>.<span class="hljs-property">icu</span> === <span class="hljs-string">'string'</span>;</code> <button class="copy-button">copy</button></pre> <p>To check for support for a non-English locale (i.e. <code>full-icu</code> or <code>system-icu</code>), <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat"><code>Intl.DateTimeFormat</code></a> can be a good distinguishing factor:</p> <pre><code class="language-js"><span class="hljs-keyword">const</span> hasFullICU = (<span class="hljs-function">() =></span> { <span class="hljs-keyword">try</span> { <span class="hljs-keyword">const</span> january = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Date</span>(<span class="hljs-number">9e8</span>); <span class="hljs-keyword">const</span> spanish = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Intl</span>.<span class="hljs-title class_">DateTimeFormat</span>(<span class="hljs-string">'es'</span>, { <span class="hljs-attr">month</span>: <span class="hljs-string">'long'</span> }); <span class="hljs-keyword">return</span> spanish.<span class="hljs-title function_">format</span>(january) === <span class="hljs-string">'enero'</span>; } <span class="hljs-keyword">catch</span> (err) { <span class="hljs-keyword">return</span> <span class="hljs-literal">false</span>; } })();</code> <button class="copy-button">copy</button></pre> <p>For more verbose tests for <code>Intl</code> support, the following resources may be found to be helpful:</p> <ul> <li><a href="https://github.com/srl295/btest402">btest402</a>: Generally used to check whether Node.js with <code>Intl</code> support is built correctly.</li> <li><a href="https://github.com/tc39/test262/tree/HEAD/test/intl402">Test262</a>: ECMAScript's official conformance test suite includes a section dedicated to ECMA-402.</li> </ul></section>  </div> </div> </div> </body> </html>