1<!DOCTYPE html> 2<html lang="en"> 3<head> 4 <meta charset="utf-8"> 5 <meta name="viewport" content="width=device-width"> 6 <meta name="nodejs.org:node-version" content="v18.18.2"> 7 <title>Internationalization support | Node.js v18.18.2 Documentation</title> 8 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 9 <link rel="stylesheet" href="assets/style.css"> 10 <link rel="stylesheet" href="assets/hljs.css"> 11 <link rel="canonical" href="https://nodejs.org/api/intl.html"> 12 <script async defer src="assets/api.js" type="text/javascript"></script> 13 14</head> 15<body class="alt apidoc" id="api-section-intl"> 16 <div id="content" class="clearfix"> 17 <div id="column2" class="interior"> 18 <div id="intro" class="interior"> 19 <a href="/" title="Go back to the home page"> 20 Node.js 21 </a> 22 </div> 23 <ul> 24<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 25<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 26</ul> 27<hr class="line"> 28<ul> 29<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 30<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 31<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 32<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 33<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 34<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 35<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 36<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 37<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 38<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 39<li><a href="console.html" class="nav-console">Console</a></li> 40<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 41<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 42<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 43<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 44<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 45<li><a href="dns.html" class="nav-dns">DNS</a></li> 46<li><a href="domain.html" class="nav-domain">Domain</a></li> 47<li><a href="errors.html" class="nav-errors">Errors</a></li> 48<li><a href="events.html" class="nav-events">Events</a></li> 49<li><a href="fs.html" class="nav-fs">File system</a></li> 50<li><a href="globals.html" class="nav-globals">Globals</a></li> 51<li><a href="http.html" class="nav-http">HTTP</a></li> 52<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 53<li><a href="https.html" class="nav-https">HTTPS</a></li> 54<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 55<li><a href="intl.html" class="nav-intl active">Internationalization</a></li> 56<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 57<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 58<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 59<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 60<li><a href="net.html" class="nav-net">Net</a></li> 61<li><a href="os.html" class="nav-os">OS</a></li> 62<li><a href="path.html" class="nav-path">Path</a></li> 63<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 64<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 65<li><a href="process.html" class="nav-process">Process</a></li> 66<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 67<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 68<li><a href="readline.html" class="nav-readline">Readline</a></li> 69<li><a href="repl.html" class="nav-repl">REPL</a></li> 70<li><a href="report.html" class="nav-report">Report</a></li> 71<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 72<li><a href="stream.html" class="nav-stream">Stream</a></li> 73<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 74<li><a href="test.html" class="nav-test">Test runner</a></li> 75<li><a href="timers.html" class="nav-timers">Timers</a></li> 76<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 77<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 78<li><a href="tty.html" class="nav-tty">TTY</a></li> 79<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 80<li><a href="url.html" class="nav-url">URL</a></li> 81<li><a href="util.html" class="nav-util">Utilities</a></li> 82<li><a href="v8.html" class="nav-v8">V8</a></li> 83<li><a href="vm.html" class="nav-vm">VM</a></li> 84<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 85<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 86<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 87<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 88<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 89</ul> 90<hr class="line"> 91<ul> 92<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 93</ul> 94 </div> 95 96 <div id="column1" data-id="intl" class="interior"> 97 <header class="header"> 98 <div class="header-container"> 99 <h1>Node.js v18.18.2 documentation</h1> 100 <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 101 <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 102 <path fill="none" d="M0 0h24v24H0z" /> 103 <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"/> 104 <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"/> 105 </svg> 106 <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 107 <path d="M0 0h24v24H0z" fill="none" /> 108 <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"/> 109 </svg> 110 </button> 111 </div> 112 <div id="gtoc"> 113 <ul> 114 <li class="pinned-header">Node.js v18.18.2</li> 115 116 <li class="picker-header"> 117 <a href="#"> 118 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 119 Table of contents 120 </a> 121 122 <div class="picker"><div class="toc"><ul> 123<li><a href="#internationalization-support">Internationalization support</a> 124<ul> 125<li><a href="#options-for-building-nodejs">Options for building Node.js</a> 126<ul> 127<li><a href="#disable-all-internationalization-features-none">Disable all internationalization features (<code>none</code>)</a></li> 128<li><a href="#build-with-a-pre-installed-icu-system-icu">Build with a pre-installed ICU (<code>system-icu</code>)</a></li> 129<li><a href="#embed-a-limited-set-of-icu-data-small-icu">Embed a limited set of ICU data (<code>small-icu</code>)</a> 130<ul> 131<li><a href="#providing-icu-data-at-runtime">Providing ICU data at runtime</a></li> 132</ul> 133</li> 134<li><a href="#embed-the-entire-icu-full-icu">Embed the entire ICU (<code>full-icu</code>)</a></li> 135</ul> 136</li> 137<li><a href="#detecting-internationalization-support">Detecting internationalization support</a></li> 138</ul> 139</li> 140</ul></div></div> 141 </li> 142 143 144 <li class="picker-header"> 145 <a href="#"> 146 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 147 Index 148 </a> 149 150 <div class="picker"><ul> 151<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 152<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 153 154 <li> 155 <a href="index.html">Index</a> 156 </li> 157 </ul> 158 159<hr class="line"> 160<ul> 161<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 162<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 163<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 164<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 165<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 166<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 167<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 168<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 169<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 170<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 171<li><a href="console.html" class="nav-console">Console</a></li> 172<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 173<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 174<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 175<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 176<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 177<li><a href="dns.html" class="nav-dns">DNS</a></li> 178<li><a href="domain.html" class="nav-domain">Domain</a></li> 179<li><a href="errors.html" class="nav-errors">Errors</a></li> 180<li><a href="events.html" class="nav-events">Events</a></li> 181<li><a href="fs.html" class="nav-fs">File system</a></li> 182<li><a href="globals.html" class="nav-globals">Globals</a></li> 183<li><a href="http.html" class="nav-http">HTTP</a></li> 184<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 185<li><a href="https.html" class="nav-https">HTTPS</a></li> 186<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 187<li><a href="intl.html" class="nav-intl active">Internationalization</a></li> 188<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 189<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 190<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 191<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 192<li><a href="net.html" class="nav-net">Net</a></li> 193<li><a href="os.html" class="nav-os">OS</a></li> 194<li><a href="path.html" class="nav-path">Path</a></li> 195<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 196<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 197<li><a href="process.html" class="nav-process">Process</a></li> 198<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 199<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 200<li><a href="readline.html" class="nav-readline">Readline</a></li> 201<li><a href="repl.html" class="nav-repl">REPL</a></li> 202<li><a href="report.html" class="nav-report">Report</a></li> 203<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 204<li><a href="stream.html" class="nav-stream">Stream</a></li> 205<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 206<li><a href="test.html" class="nav-test">Test runner</a></li> 207<li><a href="timers.html" class="nav-timers">Timers</a></li> 208<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 209<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 210<li><a href="tty.html" class="nav-tty">TTY</a></li> 211<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 212<li><a href="url.html" class="nav-url">URL</a></li> 213<li><a href="util.html" class="nav-util">Utilities</a></li> 214<li><a href="v8.html" class="nav-v8">V8</a></li> 215<li><a href="vm.html" class="nav-vm">VM</a></li> 216<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 217<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 218<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 219<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 220<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 221</ul> 222<hr class="line"> 223<ul> 224<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 225</ul></div> 226 </li> 227 228 229 <li class="picker-header"> 230 <a href="#"> 231 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 232 Other versions 233 </a> 234 <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v20.x/api/intl.html">20.x</a></li> 235<li><a href="https://nodejs.org/docs/latest-v19.x/api/intl.html">19.x</a></li> 236<li><a href="https://nodejs.org/docs/latest-v18.x/api/intl.html">18.x <b>LTS</b></a></li> 237<li><a href="https://nodejs.org/docs/latest-v17.x/api/intl.html">17.x</a></li> 238<li><a href="https://nodejs.org/docs/latest-v16.x/api/intl.html">16.x</a></li> 239<li><a href="https://nodejs.org/docs/latest-v15.x/api/intl.html">15.x</a></li> 240<li><a href="https://nodejs.org/docs/latest-v14.x/api/intl.html">14.x</a></li> 241<li><a href="https://nodejs.org/docs/latest-v13.x/api/intl.html">13.x</a></li> 242<li><a href="https://nodejs.org/docs/latest-v12.x/api/intl.html">12.x</a></li> 243<li><a href="https://nodejs.org/docs/latest-v11.x/api/intl.html">11.x</a></li> 244<li><a href="https://nodejs.org/docs/latest-v10.x/api/intl.html">10.x</a></li> 245<li><a href="https://nodejs.org/docs/latest-v9.x/api/intl.html">9.x</a></li> 246<li><a href="https://nodejs.org/docs/latest-v8.x/api/intl.html">8.x</a></li></ol></div> 247 </li> 248 249 <li class="picker-header"> 250 <a href="#"> 251 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 252 Options 253 </a> 254 255 <div class="picker"> 256 <ul> 257 <li> 258 <a href="all.html">View on single page</a> 259 </li> 260 <li> 261 <a href="intl.json">View as JSON</a> 262 </li> 263 <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/intl.md">Edit on GitHub</a></li> 264 </ul> 265 </div> 266 </li> 267 </ul> 268 </div> 269 <hr> 270 </header> 271 272 <details id="toc" open><summary>Table of contents</summary><ul> 273<li><a href="#internationalization-support">Internationalization support</a> 274<ul> 275<li><a href="#options-for-building-nodejs">Options for building Node.js</a> 276<ul> 277<li><a href="#disable-all-internationalization-features-none">Disable all internationalization features (<code>none</code>)</a></li> 278<li><a href="#build-with-a-pre-installed-icu-system-icu">Build with a pre-installed ICU (<code>system-icu</code>)</a></li> 279<li><a href="#embed-a-limited-set-of-icu-data-small-icu">Embed a limited set of ICU data (<code>small-icu</code>)</a> 280<ul> 281<li><a href="#providing-icu-data-at-runtime">Providing ICU data at runtime</a></li> 282</ul> 283</li> 284<li><a href="#embed-the-entire-icu-full-icu">Embed the entire ICU (<code>full-icu</code>)</a></li> 285</ul> 286</li> 287<li><a href="#detecting-internationalization-support">Detecting internationalization support</a></li> 288</ul> 289</li> 290</ul></details> 291 292 <div id="apicontent"> 293 <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> 294 295 296<p>Node.js has many features that make it easier to write internationalized 297programs. Some of them are:</p> 298<ul> 299<li>Locale-sensitive or Unicode-aware functions in the <a href="https://tc39.github.io/ecma262/">ECMAScript Language 300Specification</a>: 301<ul> 302<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize"><code>String.prototype.normalize()</code></a></li> 303<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase"><code>String.prototype.toLowerCase()</code></a></li> 304<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase"><code>String.prototype.toUpperCase()</code></a></li> 305</ul> 306</li> 307<li>All functionality described in the <a href="https://tc39.github.io/ecma402/">ECMAScript Internationalization API 308Specification</a> (aka ECMA-402): 309<ul> 310<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl"><code>Intl</code></a> object</li> 311<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 312<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString"><code>Date.prototype.toLocaleString()</code></a></li> 313</ul> 314</li> 315<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> 316<li><a href="buffer.html#buffertranscodesource-fromenc-toenc"><code>require('node:buffer').transcode()</code></a></li> 317<li>More accurate <a href="repl.html#repl">REPL</a> line editing</li> 318<li><a href="util.html#class-utiltextdecoder"><code>require('node:util').TextDecoder</code></a></li> 319<li><a href="https://github.com/tc39/proposal-regexp-unicode-property-escapes"><code>RegExp</code> Unicode Property Escapes</a></li> 320</ul> 321<p>Node.js and the underlying V8 engine use 322<a href="http://site.icu-project.org/">International Components for Unicode (ICU)</a> to implement these features 323in native C/C++ code. The full ICU data set is provided by Node.js by default. 324However, due to the size of the ICU data file, several 325options are provided for customizing the ICU data set either when 326building or running Node.js.</p> 327<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> 328<p>To control how ICU is used in Node.js, four <code>configure</code> options are available 329during compilation. Additional details on how to compile Node.js are documented 330in <a href="https://github.com/nodejs/node/blob/HEAD/BUILDING.md">BUILDING.md</a>.</p> 331<ul> 332<li><code>--with-intl=none</code>/<code>--without-intl</code></li> 333<li><code>--with-intl=system-icu</code></li> 334<li><code>--with-intl=small-icu</code></li> 335<li><code>--with-intl=full-icu</code> (default)</li> 336</ul> 337<p>An overview of available Node.js and JavaScript features for each <code>configure</code> 338option:</p> 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442<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> 443<p>The "(not locale-aware)" designation denotes that the function carries out its 444operation just like the non-<code>Locale</code> version of the function, if one 445exists. For example, under <code>none</code> mode, <code>Date.prototype.toLocaleString()</code>'s 446operation is identical to that of <code>Date.prototype.toString()</code>.</p> 447<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> 448<p>If this option is chosen, ICU is disabled and most internationalization 449features mentioned above will be <strong>unavailable</strong> in the resulting <code>node</code> binary.</p> 450<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> 451<p>Node.js can link against an ICU build already installed on the system. In fact, 452most Linux distributions already come with ICU installed, and this option would 453make it possible to reuse the same set of data used by other components in the 454OS.</p> 455<p>Functionalities that only require the ICU library itself, such as 456<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 457supported under <code>system-icu</code>. Features that require ICU locale data in 458addition, 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 459supported, depending on the completeness of the ICU data installed on the 460system.</p> 461<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> 462<p>This option makes the resulting binary link against the ICU library statically, 463and includes a subset of ICU data (typically only the English locale) within 464the <code>node</code> executable.</p> 465<p>Functionalities that only require the ICU library itself, such as 466<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 467supported under <code>small-icu</code>. Features that require ICU locale data in addition, 468such 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> 469<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>); 470<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> }); 471<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> }); 472 473<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(english.<span class="hljs-title function_">format</span>(january)); 474<span class="hljs-comment">// Prints "January"</span> 475<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(spanish.<span class="hljs-title function_">format</span>(january)); 476<span class="hljs-comment">// Prints either "M01" or "January" on small-icu, depending on the user’s default locale</span> 477<span class="hljs-comment">// Should print "enero"</span></code> <button class="copy-button">copy</button></pre> 478<p>This mode provides a balance between features and binary size.</p> 479<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> 480<p>If the <code>small-icu</code> option is used, one can still provide additional locale data 481at runtime so that the JS methods would work for all ICU locales. Assuming the 482data file is stored at <code>/some/directory</code>, it can be made available to ICU 483through either:</p> 484<ul> 485<li> 486<p>The <a href="cli.html#node_icu_datafile"><code>NODE_ICU_DATA</code></a> environment variable:</p> 487<pre><code class="language-bash"><span class="hljs-built_in">env</span> NODE_ICU_DATA=/some/directory node</code> <button class="copy-button">copy</button></pre> 488</li> 489<li> 490<p>The <a href="cli.html#--icu-data-dirfile"><code>--icu-data-dir</code></a> CLI parameter:</p> 491<pre><code class="language-bash">node --icu-data-dir=/some/directory</code> <button class="copy-button">copy</button></pre> 492</li> 493</ul> 494<p>(If both are specified, the <code>--icu-data-dir</code> CLI parameter takes precedence.)</p> 495<p>ICU is able to automatically find and load a variety of data formats, but the 496data must be appropriate for the ICU version, and the file correctly named. 497The most common name for the data file is <code>icudt6X[bl].dat</code>, where <code>6X</code> denotes 498the intended ICU version, and <code>b</code> or <code>l</code> indicates the system's endianness. 499Check <a href="http://userguide.icu-project.org/icudata">"ICU Data"</a> article in the ICU User Guide for other supported formats 500and more details on ICU data in general.</p> 501<p>The <a href="https://www.npmjs.com/package/full-icu">full-icu</a> npm module can greatly simplify ICU data installation by 502detecting the ICU version of the running <code>node</code> executable and downloading the 503appropriate data file. After installing the module through <code>npm i full-icu</code>, 504the data file will be available at <code>./node_modules/full-icu</code>. This path can be 505then passed either to <code>NODE_ICU_DATA</code> or <code>--icu-data-dir</code> as shown above to 506enable full <code>Intl</code> support.</p> 507<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> 508<p>This option makes the resulting binary link against ICU statically and include 509a full set of ICU data. A binary created this way has no further external 510dependencies and supports all locales, but might be rather large. This is 511the default behavior if no <code>--with-intl</code> flag is passed. The official binaries 512are also built in this mode.</p> 513</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> 514<p>To verify that ICU is enabled at all (<code>system-icu</code>, <code>small-icu</code>, or 515<code>full-icu</code>), simply checking the existence of <code>Intl</code> should suffice:</p> 516<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> 517<p>Alternatively, checking for <code>process.versions.icu</code>, a property defined only 518when ICU is enabled, works too:</p> 519<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> 520<p>To check for support for a non-English locale (i.e. <code>full-icu</code> or 521<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> 522<pre><code class="language-js"><span class="hljs-keyword">const</span> hasFullICU = (<span class="hljs-function">() =></span> { 523 <span class="hljs-keyword">try</span> { 524 <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>); 525 <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> }); 526 <span class="hljs-keyword">return</span> spanish.<span class="hljs-title function_">format</span>(january) === <span class="hljs-string">'enero'</span>; 527 } <span class="hljs-keyword">catch</span> (err) { 528 <span class="hljs-keyword">return</span> <span class="hljs-literal">false</span>; 529 } 530})();</code> <button class="copy-button">copy</button></pre> 531<p>For more verbose tests for <code>Intl</code> support, the following resources may be found 532to be helpful:</p> 533<ul> 534<li><a href="https://github.com/srl295/btest402">btest402</a>: Generally used to check whether Node.js with <code>Intl</code> support is 535built correctly.</li> 536<li><a href="https://github.com/tc39/test262/tree/HEAD/test/intl402">Test262</a>: ECMAScript's official conformance test suite includes a section 537dedicated to ECMA-402.</li> 538</ul></section> 539 <!-- API END --> 540 </div> 541 </div> 542 </div> 543</body> 544</html> 545