Intl.js Polyfill

Common errors

• ReferenceError: Intl is not defined

  cause The JavaScript runtime environment (e.g., an older browser, or specific Node.js versions) does not natively provide the ECMA-402 Intl API, and the `intl` polyfill has not been loaded or applied.
  fix For browsers, include the `intl.js` polyfill via a script tag (ideally through a polyfill service like `cdn.polyfill.io`). For Node.js, ensure `require('intl')` is executed and `global.Intl` is patched before any `Intl` API usage, following the recommended conditional polyfill pattern.

• TypeError: Intl.NumberFormat is not a constructor

  cause While a global `Intl` object might exist, the specific constructor (e.g., `NumberFormat` or `DateTimeFormat`) might be missing or not properly assigned, often due to an incomplete polyfill or a runtime with partial `Intl` support.
  fix Verify that `Intl.NumberFormat` and `Intl.DateTimeFormat` (or other required constructors) are explicitly assigned from the `intl` polyfill object (e.g., `Intl.NumberFormat = IntlPolyfill.NumberFormat;`) after `require('intl')`.

• Error: No locale data has been provided for this object.

  cause An `Intl` formatting object (like `NumberFormat` or `DateTimeFormat`) was instantiated for a locale whose data was not loaded or made available to the `intl` polyfill.
  fix When using the polyfill, ensure all necessary locale data is loaded. If using `polyfill.io`, explicitly list all required locales (e.g., `features=Intl.~locale.en,Intl.~locale.fr`). If bundling locally, verify that the CLDR data for your target locales is included in your build.

Warnings

• breaking Version 0.1.3 introduced a regression where some data arrays were accidentally sorted, causing incorrect behavior. This was fixed immediately in v0.1.4.
  Fix: Upgrade to v0.1.4 or higher immediately if using v0.1.3.
• gotcha The behavior of `toLocaleString()` was changed in v0.1.3. It no longer overrides native ECMA-402 implementations if they already exist in the environment.
  Fix: If you relied on the polyfill overriding native `toLocaleString()` for specific behaviors, you will need to explicitly apply the polyfill versions using `IntlPolyfill.__applyLocaleSensitivePrototypes()` after `require('intl')`.
• breaking As of v1.2.5, `locale-data/json/*.json` files were removed from the npm package. This change impacts builds or setups that directly accessed these files within the `node_modules/intl` directory.
  Fix: Adjust your build process to no longer rely on direct access to `locale-data/json/*.json` files within the `intl` package directory. The library's internal mechanisms for loading data remain intact.
• gotcha Node.js environments have varied `Intl` support: versions prior to 0.12 and >=v3.1 lack native `Intl` APIs entirely, requiring a full polyfill. Node.js 0.12 has built-in `Intl` but often only includes English locale data, necessitating partial polyfilling for other locales.
  Fix: Always use a conditional polyfilling strategy for Node.js, such as the one demonstrated in the quickstart, utilizing `intl-locales-supported` to detect and apply the polyfill only when needed.

Install

• npm install intl npm
• yarn add intl yarn
• pnpm add intl pnpm

Imports

• Intl (Polyfill Object)
  wrong:

  import Intl from 'intl';

  correct:

  const IntlPolyfill = require('intl');
  // ... then potentially global.Intl = IntlPolyfill;

  The `intl` package is primarily designed for CommonJS environments (Node.js) or loaded via a script tag in browsers. The `require()` call returns an object that represents the polyfill, which can then be used to patch the global `Intl` object or its constructors.
• Intl.NumberFormat, Intl.DateTimeFormat (for patching)
  wrong:

  import { NumberFormat, DateTimeFormat } from 'intl';

  correct:

  const IntlPolyfill = require('intl');
  Intl.NumberFormat = IntlPolyfill.NumberFormat;
  Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;

  When selectively patching the global `Intl` object in Node.js, these constructors are accessed as properties of the imported polyfill object, not as direct named exports from the module root.
• window.Intl (Browser via Polyfill Service)

  <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Intl.~locale.en,Intl.~locale.fr"></script>

  For browser environments, Intl.js is most commonly included via a polyfill service like cdn.polyfill.io. This method dynamically loads the polyfill and necessary locale data based on browser capabilities and requested features, modifying the global `window.Intl` object only when required.

Quickstart

This quickstart demonstrates how to conditionally polyfill the `Intl` API in a Node.js environment, checking for native support and applying the polyfill only when necessary, then showcases basic number and date formatting.

var areIntlLocalesSupported = require('intl-locales-supported');

var localesMyAppSupports = [
    'en-US',
    'fr-FR',
    'de-DE',
    'es-ES'
];

// This example demonstrates how to conditionally polyfill the Intl API
// in Node.js environments, ensuring that the necessary locale data is available.
// It checks if global.Intl exists and if it supports the required locales.
// If not, it loads and applies the intl polyfill.

if (global.Intl) {
    // Determine if the built-in `Intl` has the locale data we need.
    if (!areIntlLocalesSupported(localesMyAppSupports)) {
        // `Intl` exists, but it doesn't have the data we need, so load the
        // polyfill and patch the constructors we need with the polyfill's.
        var IntlPolyfill    = require('intl');
        Intl.NumberFormat   = IntlPolyfill.NumberFormat;
        Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;
        console.log('Patched built-in Intl with polyfill data for missing locales.');
    } else {
        console.log('Built-in Intl supports all required locales.');
    }
} else {
    // No `Intl` object globally, so use and load the polyfill entirely.
    global.Intl = require('intl');
    console.log('No native Intl, loaded full polyfill.');
}

// Example usage after polyfilling
const number = 123456.789;
console.log('Formatted number (en-US):', new Intl.NumberFormat('en-US').format(number));
console.log('Formatted number (fr-FR):', new Intl.NumberFormat('fr-FR').format(number));

const date = new Date();
console.log('Formatted date (en-US):', new Intl.DateTimeFormat('en-US').format(date));
console.log('Formatted date (de-DE):', new Intl.DateTimeFormat('de-DE', { dateStyle: 'full', timeStyle: 'short' }).format(date));