Skip to main content

​
Internationalization Support

Node.js has many features that make it easier to write internationalized programs. Some of them are:
  • Locale-sensitive or Unicode-aware functions in the ECMAScript Language Specification:
    • String.prototype.normalize()
    • String.prototype.toLowerCase()
    • String.prototype.toUpperCase()
  • All functionality described in the ECMAScript Internationalization API Specification (ECMA-402):
    • Intl object
    • Locale-sensitive methods like String.prototype.localeCompare() and Date.prototype.toLocaleString()
  • The WHATWG URL parser’s internationalized domain names (IDNs) support
  • require('node:buffer').transcode()
  • More accurate REPL line editing
  • require('node:util').TextDecoder
  • RegExp Unicode Property Escapes
Node.js and the underlying V8 engine use International Components for Unicode (ICU) to implement these features in native C/C++ code. The full ICU data set is provided by Node.js by default.

​
Options for Building Node.js

To control how ICU is used in Node.js, four configure options are available during compilation:
  • --with-intl=none/--without-intl
  • --with-intl=system-icu
  • --with-intl=small-icu
  • --with-intl=full-icu (default)

​
Feature Availability

Featurenonesystem-icusmall-icufull-icu
String.prototype.normalize()none (no-op)fullfullfull
Intl objectnonepartial/fullpartial (English-only)full
String.prototype.localeCompare()partialfullfullfull
WHATWG URL Parser (IDN support)nonefullfullfull
require('node:buffer').transcode()nonefullfullfull
REPLpartialfullfullfull
require('node:util').TextDecoderpartialpartial/fullpartial (Unicode-only)full
RegExp Unicode Property Escapesnonefullfullfull

​
Disable All Internationalization Features (none)

If this option is chosen, ICU is disabled and most internationalization features mentioned above will be unavailable in the resulting node binary.

​
Build with Pre-installed ICU (system-icu)

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. Functionalities that only require the ICU library itself are fully supported. Features that require ICU locale data may be fully or partially supported, depending on the completeness of the ICU data installed on the system.

​
Embed Limited ICU Data (small-icu)

This option makes the resulting binary link against the ICU library statically, and includes a subset of ICU data (typically only the English locale) within the node executable. Functionalities that only require the ICU library itself are fully supported. Features that require ICU locale data generally only work with the English locale: 
const january = new Date(9e8);
const english = new Intl.DateTimeFormat('en', { month: 'long' });
const spanish = new Intl.DateTimeFormat('es', { month: 'long' });

console.log(english.format(january));
// Prints "January"
console.log(spanish.format(january));
// Prints either "M01" or "January" on small-icu
// Should print "enero"
This mode provides a balance between features and binary size.

​
Providing ICU Data at Runtime

If the small-icu option is used, one can still provide additional locale data at runtime so that the JS methods would work for all ICU locales. The data file can be made available to ICU through:
  • The --with-icu-default-data-dir configure option: 
    ./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu
  • The NODE_ICU_DATA environment variable: 
    env NODE_ICU_DATA=/runtime/directory/with/dat/file node
  • The --icu-data-dir CLI parameter: 
    node --icu-data-dir=/runtime/directory/with/dat/file
When more than one of them is specified, the --icu-data-dir CLI parameter has the highest precedence, then the NODE_ICU_DATA environment variable, then the --with-icu-default-data-dir configure option. The most common name for the data file is icudtX[bl].dat, where X denotes the intended ICU version, and b or l indicates the system’s endianness. The name of the data file corresponding to the current Node.js version can be computed with: 
`icudt${process.versions.icu.split('.')[0]}${os.endianness()[0].toLowerCase()}.dat`;

​
Embed the Entire ICU (full-icu)

This option makes the resulting binary link against ICU statically and include a full set of ICU data. A binary created this way has no further external dependencies and supports all locales, but might be rather large. This is the default behavior if no --with-intl flag is passed. The official binaries are also built in this mode.

​
Detecting Internationalization Support

To verify that ICU is enabled at all (system-icu, small-icu, or full-icu), simply checking the existence of Intl should suffice: 
const hasICU = typeof Intl === 'object';
Alternatively, checking for process.versions.icu, a property defined only when ICU is enabled, works too: 
const hasICU = typeof process.versions.icu === 'string';
To check for support for a non-English locale (i.e. full-icu or system-icu), Intl.DateTimeFormat can be a good distinguishing factor: 
const hasFullICU = (() => {
  try {
    const january = new Date(9e8);
    const spanish = new Intl.DateTimeFormat('es', { month: 'long' });
    return spanish.format(january) === 'enero';
  } catch (err) {
    return false;
  }
})();

​
Using Intl API

​
Date and Time Formatting

const date = new Date();

// Format date in different locales
console.log(new Intl.DateTimeFormat('en-US').format(date));
console.log(new Intl.DateTimeFormat('de-DE').format(date));
console.log(new Intl.DateTimeFormat('ja-JP').format(date));

// Custom formatting
const options = {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
};
console.log(new Intl.DateTimeFormat('en-US', options).format(date));

​
Number Formatting

const number = 123456.789;

// Format numbers in different locales
console.log(new Intl.NumberFormat('en-US').format(number));
console.log(new Intl.NumberFormat('de-DE').format(number));
console.log(new Intl.NumberFormat('ja-JP').format(number));

// Currency formatting
console.log(new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).format(number));

console.log(new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR'
}).format(number));

​
Collation (String Comparison)

const items = ['ä', 'a', 'z', 'ö'];

// Sort with locale-aware comparison
console.log(items.sort((a, b) => 
  new Intl.Collator('de').compare(a, b)
));
// Output: ['a', 'ä', 'ö', 'z']

// Case-insensitive sorting
const words = ['apple', 'Banana', 'cherry'];
console.log(words.sort((a, b) => 
  new Intl.Collator('en', { sensitivity: 'base' }).compare(a, b)
));

​
Plural Rules

const pr = new Intl.PluralRules('en-US');

console.log(pr.select(0));  // 'other'
console.log(pr.select(1));  // 'one'
console.log(pr.select(2));  // 'other'

// Use with message formatting
function formatMessage(count) {
  const pluralRules = new Intl.PluralRules('en-US');
  const messages = {
    one: 'You have 1 message',
    other: `You have ${count} messages`
  };
  return messages[pluralRules.select(count)];
}

console.log(formatMessage(0));  // "You have 0 messages"
console.log(formatMessage(1));  // "You have 1 message"
console.log(formatMessage(5));  // "You have 5 messages"

​
List Formatting

const list = ['apple', 'banana', 'orange'];

const formatter = new Intl.ListFormat('en', {
  style: 'long',
  type: 'conjunction'
});

console.log(formatter.format(list));
// Output: "apple, banana, and orange"

const formatterOr = new Intl.ListFormat('en', {
  style: 'long',
  type: 'disjunction'
});

console.log(formatterOr.format(list));
// Output: "apple, banana, or orange"

​
Relative Time Formatting

const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });

console.log(rtf.format(-1, 'day'));    // "yesterday"
console.log(rtf.format(0, 'day'));     // "today"
console.log(rtf.format(1, 'day'));     // "tomorrow"
console.log(rtf.format(-2, 'week'));   // "2 weeks ago"
console.log(rtf.format(3, 'month'));   // "in 3 months"

​
String Normalization

const str1 = '\u0041\u006d\u00e9\u006c\u0069\u0065';  // Amélie
const str2 = '\u0041\u006d\u0065\u0301\u006c\u0069\u0065';  // Amélie (with combining accent)

console.log(str1 === str2);  // false
console.log(str1.normalize() === str2.normalize());  // true

// Different normalization forms
console.log(str2.normalize('NFC'));   // Canonical composition
console.log(str2.normalize('NFD'));   // Canonical decomposition
console.log(str2.normalize('NFKC'));  // Compatibility composition
console.log(str2.normalize('NFKD'));  // Compatibility decomposition

​
Best Practices

  1. Always use Intl APIs for locale-sensitive operations instead of custom implementations
  2. Test with multiple locales to ensure your application works correctly in different languages
  3. Use appropriate ICU build based on your deployment requirements
  4. Cache formatters when possible as creating new Intl objects can be expensive
  5. Handle missing locale data gracefully when using small-icu
// Good: Cache the formatter
const currencyFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

function formatPrice(price) {
  return currencyFormatter.format(price);
}

// Use the cached formatter multiple times
console.log(formatPrice(19.99));
console.log(formatPrice(29.99));