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.20.1"> 7 <title>Internationalization support | Node.js v18.20.1 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.20.1 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.20.1</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-v21.x/api/intl.html">21.x</a></li> 235<li><a href="https://nodejs.org/docs/latest-v20.x/api/intl.html">20.x <b>LTS</b></a></li> 236<li><a href="https://nodejs.org/docs/latest-v19.x/api/intl.html">19.x</a></li> 237<li><a href="https://nodejs.org/docs/latest-v18.x/api/intl.html">18.x <b>LTS</b></a></li> 238<li><a href="https://nodejs.org/docs/latest-v17.x/api/intl.html">17.x</a></li> 239<li><a href="https://nodejs.org/docs/latest-v16.x/api/intl.html">16.x</a></li> 240<li><a href="https://nodejs.org/docs/latest-v15.x/api/intl.html">15.x</a></li> 241<li><a href="https://nodejs.org/docs/latest-v14.x/api/intl.html">14.x</a></li> 242<li><a href="https://nodejs.org/docs/latest-v13.x/api/intl.html">13.x</a></li> 243<li><a href="https://nodejs.org/docs/latest-v12.x/api/intl.html">12.x</a></li> 244<li><a href="https://nodejs.org/docs/latest-v11.x/api/intl.html">11.x</a></li> 245<li><a href="https://nodejs.org/docs/latest-v10.x/api/intl.html">10.x</a></li> 246<li><a href="https://nodejs.org/docs/latest-v9.x/api/intl.html">9.x</a></li> 247<li><a href="https://nodejs.org/docs/latest-v8.x/api/intl.html">8.x</a></li></ol></div> 248 </li> 249 250 <li class="picker-header"> 251 <a href="#"> 252 <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 253 Options 254 </a> 255 256 <div class="picker"> 257 <ul> 258 <li> 259 <a href="all.html">View on single page</a> 260 </li> 261 <li> 262 <a href="intl.json">View as JSON</a> 263 </li> 264 <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/intl.md">Edit on GitHub</a></li> 265 </ul> 266 </div> 267 </li> 268 </ul> 269 </div> 270 <hr> 271 </header> 272 273 <details id="toc" open><summary>Table of contents</summary><ul> 274<li><a href="#internationalization-support">Internationalization support</a> 275<ul> 276<li><a href="#options-for-building-nodejs">Options for building Node.js</a> 277<ul> 278<li><a href="#disable-all-internationalization-features-none">Disable all internationalization features (<code>none</code>)</a></li> 279<li><a href="#build-with-a-pre-installed-icu-system-icu">Build with a pre-installed ICU (<code>system-icu</code>)</a></li> 280<li><a href="#embed-a-limited-set-of-icu-data-small-icu">Embed a limited set of ICU data (<code>small-icu</code>)</a> 281<ul> 282<li><a href="#providing-icu-data-at-runtime">Providing ICU data at runtime</a></li> 283</ul> 284</li> 285<li><a href="#embed-the-entire-icu-full-icu">Embed the entire ICU (<code>full-icu</code>)</a></li> 286</ul> 287</li> 288<li><a href="#detecting-internationalization-support">Detecting internationalization support</a></li> 289</ul> 290</li> 291</ul></details> 292 293 <div id="apicontent"> 294 <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> 295 296 297<p>Node.js has many features that make it easier to write internationalized 298programs. Some of them are:</p> 299<ul> 300<li>Locale-sensitive or Unicode-aware functions in the <a href="https://tc39.github.io/ecma262/">ECMAScript Language 301Specification</a>: 302<ul> 303<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize"><code>String.prototype.normalize()</code></a></li> 304<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase"><code>String.prototype.toLowerCase()</code></a></li> 305<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase"><code>String.prototype.toUpperCase()</code></a></li> 306</ul> 307</li> 308<li>All functionality described in the <a href="https://tc39.github.io/ecma402/">ECMAScript Internationalization API 309Specification</a> (aka ECMA-402): 310<ul> 311<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl"><code>Intl</code></a> object</li> 312<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 313<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString"><code>Date.prototype.toLocaleString()</code></a></li> 314</ul> 315</li> 316<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> 317<li><a href="buffer.html#buffertranscodesource-fromenc-toenc"><code>require('node:buffer').transcode()</code></a></li> 318<li>More accurate <a href="repl.html#repl">REPL</a> line editing</li> 319<li><a href="util.html#class-utiltextdecoder"><code>require('node:util').TextDecoder</code></a></li> 320<li><a href="https://github.com/tc39/proposal-regexp-unicode-property-escapes"><code>RegExp</code> Unicode Property Escapes</a></li> 321</ul> 322<p>Node.js and the underlying V8 engine use 323<a href="http://site.icu-project.org/">International Components for Unicode (ICU)</a> to implement these features 324in native C/C++ code. The full ICU data set is provided by Node.js by default. 325However, due to the size of the ICU data file, several 326options are provided for customizing the ICU data set either when 327building or running Node.js.</p> 328<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> 329<p>To control how ICU is used in Node.js, four <code>configure</code> options are available 330during compilation. Additional details on how to compile Node.js are documented 331in <a href="https://github.com/nodejs/node/blob/HEAD/BUILDING.md">BUILDING.md</a>.</p> 332<ul> 333<li><code>--with-intl=none</code>/<code>--without-intl</code></li> 334<li><code>--with-intl=system-icu</code></li> 335<li><code>--with-intl=small-icu</code></li> 336<li><code>--with-intl=full-icu</code> (default)</li> 337</ul> 338<p>An overview of available Node.js and JavaScript features for each <code>configure</code> 339option:</p> 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 443<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> 444<p>The "(not locale-aware)" designation denotes that the function carries out its 445operation just like the non-<code>Locale</code> version of the function, if one 446exists. For example, under <code>none</code> mode, <code>Date.prototype.toLocaleString()</code>'s 447operation is identical to that of <code>Date.prototype.toString()</code>.</p> 448<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> 449<p>If this option is chosen, ICU is disabled and most internationalization 450features mentioned above will be <strong>unavailable</strong> in the resulting <code>node</code> binary.</p> 451<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> 452<p>Node.js can link against an ICU build already installed on the system. In fact, 453most Linux distributions already come with ICU installed, and this option would 454make it possible to reuse the same set of data used by other components in the 455OS.</p> 456<p>Functionalities that only require the ICU library itself, such as 457<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 458supported under <code>system-icu</code>. Features that require ICU locale data in 459addition, 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 460supported, depending on the completeness of the ICU data installed on the 461system.</p> 462<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> 463<p>This option makes the resulting binary link against the ICU library statically, 464and includes a subset of ICU data (typically only the English locale) within 465the <code>node</code> executable.</p> 466<p>Functionalities that only require the ICU library itself, such as 467<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 468supported under <code>small-icu</code>. Features that require ICU locale data in addition, 469such 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> 470<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>); 471<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> }); 472<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> }); 473 474<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(english.<span class="hljs-title function_">format</span>(january)); 475<span class="hljs-comment">// Prints "January"</span> 476<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(spanish.<span class="hljs-title function_">format</span>(january)); 477<span class="hljs-comment">// Prints either "M01" or "January" on small-icu, depending on the user’s default locale</span> 478<span class="hljs-comment">// Should print "enero"</span></code> <button class="copy-button">copy</button></pre> 479<p>This mode provides a balance between features and binary size.</p> 480<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> 481<p>If the <code>small-icu</code> option is used, one can still provide additional locale data 482at runtime so that the JS methods would work for all ICU locales. Assuming the 483data file is stored at <code>/some/directory</code>, it can be made available to ICU 484through either:</p> 485<ul> 486<li> 487<p>The <a href="cli.html#node_icu_datafile"><code>NODE_ICU_DATA</code></a> environment variable:</p> 488<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> 489</li> 490<li> 491<p>The <a href="cli.html#--icu-data-dirfile"><code>--icu-data-dir</code></a> CLI parameter:</p> 492<pre><code class="language-bash">node --icu-data-dir=/some/directory</code> <button class="copy-button">copy</button></pre> 493</li> 494</ul> 495<p>(If both are specified, the <code>--icu-data-dir</code> CLI parameter takes precedence.)</p> 496<p>ICU is able to automatically find and load a variety of data formats, but the 497data must be appropriate for the ICU version, and the file correctly named. 498The most common name for the data file is <code>icudt6X[bl].dat</code>, where <code>6X</code> denotes 499the intended ICU version, and <code>b</code> or <code>l</code> indicates the system's endianness. 500Check <a href="http://userguide.icu-project.org/icudata">"ICU Data"</a> article in the ICU User Guide for other supported formats 501and more details on ICU data in general.</p> 502<p>The <a href="https://www.npmjs.com/package/full-icu">full-icu</a> npm module can greatly simplify ICU data installation by 503detecting the ICU version of the running <code>node</code> executable and downloading the 504appropriate data file. After installing the module through <code>npm i full-icu</code>, 505the data file will be available at <code>./node_modules/full-icu</code>. This path can be 506then passed either to <code>NODE_ICU_DATA</code> or <code>--icu-data-dir</code> as shown above to 507enable full <code>Intl</code> support.</p> 508<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> 509<p>This option makes the resulting binary link against ICU statically and include 510a full set of ICU data. A binary created this way has no further external 511dependencies and supports all locales, but might be rather large. This is 512the default behavior if no <code>--with-intl</code> flag is passed. The official binaries 513are also built in this mode.</p> 514</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> 515<p>To verify that ICU is enabled at all (<code>system-icu</code>, <code>small-icu</code>, or 516<code>full-icu</code>), simply checking the existence of <code>Intl</code> should suffice:</p> 517<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> 518<p>Alternatively, checking for <code>process.versions.icu</code>, a property defined only 519when ICU is enabled, works too:</p> 520<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> 521<p>To check for support for a non-English locale (i.e. <code>full-icu</code> or 522<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> 523<pre><code class="language-js"><span class="hljs-keyword">const</span> hasFullICU = (<span class="hljs-function">() =></span> { 524 <span class="hljs-keyword">try</span> { 525 <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>); 526 <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> }); 527 <span class="hljs-keyword">return</span> spanish.<span class="hljs-title function_">format</span>(january) === <span class="hljs-string">'enero'</span>; 528 } <span class="hljs-keyword">catch</span> (err) { 529 <span class="hljs-keyword">return</span> <span class="hljs-literal">false</span>; 530 } 531})();</code> <button class="copy-button">copy</button></pre> 532<p>For more verbose tests for <code>Intl</code> support, the following resources may be found 533to be helpful:</p> 534<ul> 535<li><a href="https://github.com/srl295/btest402">btest402</a>: Generally used to check whether Node.js with <code>Intl</code> support is 536built correctly.</li> 537<li><a href="https://github.com/tc39/test262/tree/HEAD/test/intl402">Test262</a>: ECMAScript's official conformance test suite includes a section 538dedicated to ECMA-402.</li> 539</ul></section> 540 <!-- API END --> 541 </div> 542 </div> 543 </div> 544</body> 545</html> 546