LogoفارسیFA

Internationalization Support in Node.js with ICU

Node.js provides extensive features for writing internationalized applications. These include locale-sensitive functions in ECMAScript, the Intl object, Unicode-aware string methods, internationalized domain name (IDN) support in the WHATWG URL parser, and utilities like TextDecoder, buffer.transcode(), and RegExp Unicode property escapes. These capabilities are powered by the V8 engine and the ICU (International Components for Unicode) library. Depending on how Node.js is built, ICU data can be embedded fully, partially, or disabled entirely.

ICU / Intl / ECMA-402String.prototype.normalize / localeCompare / toLocaleStringsmall-icu / system-icu / full-icuNODE_ICU_DATA / --icu-data-dirTextDecoder / RegExp Unicode Property Escapes

~2 min read • Updated Dec 29, 2025

1. Internationalization Features in Node.js


  • Unicode-aware functions like String.prototype.normalize(), toLowerCase(), and toUpperCase().
  • The Intl object and locale-sensitive methods such as localeCompare() and Date.prototype.toLocaleString().
  • IDN support in the WHATWG URL parser.
  • Utilities like buffer.transcode() and util.TextDecoder.
  • Support for RegExp Unicode Property Escapes.

2. Build Options for ICU


Four main options control ICU usage when compiling Node.js:


  • none: Disables ICU; most internationalization features are unavailable.
  • system-icu: Links against ICU installed on the system. Support depends on available locale data.
  • small-icu: Embeds limited ICU data (usually English-only) in the binary.
  • full-icu: Embeds the full ICU dataset. Default in official Node.js binaries.

3. Feature Comparison


Featurenonesystem-icusmall-icufull-icu
normalize()disabledfullfullfull
Intldisabledpartial/fullpartial (English-only)full
localeCompare()not locale-awarefullfullfull
Date.toLocaleString()not locale-awarepartial/fullpartial (English-only)full
TextDecoderbasicpartial/fullUnicode-onlyfull
RegExp Unicodedisabledfullfullfull

4. Providing ICU Data at Runtime


With small-icu, additional ICU data can be loaded at runtime:


  • Using the --icu-data-dir CLI option.
  • Setting the NODE_ICU_DATA environment variable.
  • Configuring --with-icu-default-data-dir at build time.

The full-icu npm module simplifies installation by downloading the correct ICU dataset for the running Node.js version.


5. Detecting ICU Support


  • typeof Intl === 'object': Checks if Intl is available.
  • typeof process.versions.icu === 'string': Confirms ICU is enabled.
  • Testing Intl.DateTimeFormat with non-English locales verifies full ICU support.

6. Example


const january = new Date(9e8);
const spanish = new Intl.DateTimeFormat('es', { month: 'long' });
console.log(spanish.format(january)); // "enero" with full-icu

Conclusion


Internationalization support in Node.js, powered by ICU, enables developers to build multilingual and locale-sensitive applications. Depending on project needs, developers can choose between none, system-icu, small-icu, or full-icu. Full-icu provides the richest feature set, while small-icu balances binary size with basic functionality.


Written & researched by Dr. Shahin Siami

Next Article