{"id":16091,"library":"intl","title":"Intl.js Polyfill","description":"Intl.js is a robust polyfill for the ECMA-402 ECMAScript Internationalization API, designed to provide comprehensive localization methods, including `Intl.NumberFormat` and `Intl.DateTimeFormat`, across various JavaScript environments. Currently at version 1.2.5, this library addresses the absence of native `Intl` support or incomplete locale data in legacy browsers like older Safari, as well as specific Node.js versions prior to 0.12 or lacking full CLDR data. Its release cadence is event-driven, with major/minor updates coinciding with new editions of the Ecma-402 specification (e.g., v1.2.1 for Ecma-402 2016) and significant CLDR data updates (e.g., v1.1.0 for CLDR 28.0.0). Patch releases are frequent for bug fixes and minor improvements. A key advantage of Intl.js is its ability to seamlessly integrate with public polyfill services like `cdn.polyfill.io`, ensuring that the polyfill code and corresponding locale data are only loaded by browsers that genuinely require them, thereby optimizing application performance and bandwidth usage. For server-side Node.js applications, it offers explicit mechanisms to detect and patch the runtime with the necessary `Intl` constructors and locale information. This package is crucial for developers building internationally-aware applications targeting a wide range of client and server environments.","status":"active","version":"1.2.5","language":"javascript","source_language":"en","source_url":"https://github.com/andyearnshaw/Intl.js","tags":["javascript","intl","i18n","internationalization","ecma402","polyfill"],"install":[{"cmd":"npm install intl","lang":"bash","label":"npm"},{"cmd":"yarn add intl","lang":"bash","label":"yarn"},{"cmd":"pnpm add intl","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used in Node.js environments to determine if the built-in Intl API supports required locales before conditionally loading the polyfill.","package":"intl-locales-supported","optional":true}],"imports":[{"note":"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.","wrong":"import Intl from 'intl';","symbol":"Intl (Polyfill Object)","correct":"const IntlPolyfill = require('intl');\n// ... then potentially global.Intl = IntlPolyfill;"},{"note":"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.","wrong":"import { NumberFormat, DateTimeFormat } from 'intl';","symbol":"Intl.NumberFormat, Intl.DateTimeFormat (for patching)","correct":"const IntlPolyfill = require('intl');\nIntl.NumberFormat = IntlPolyfill.NumberFormat;\nIntl.DateTimeFormat = IntlPolyfill.DateTimeFormat;"},{"note":"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.","symbol":"window.Intl (Browser via Polyfill Service)","correct":"<script src=\"https://cdn.polyfill.io/v2/polyfill.min.js?features=Intl.~locale.en,Intl.~locale.fr\"></script>"}],"quickstart":{"code":"var areIntlLocalesSupported = require('intl-locales-supported');\n\nvar localesMyAppSupports = [\n    'en-US',\n    'fr-FR',\n    'de-DE',\n    'es-ES'\n];\n\n// This example demonstrates how to conditionally polyfill the Intl API\n// in Node.js environments, ensuring that the necessary locale data is available.\n// It checks if global.Intl exists and if it supports the required locales.\n// If not, it loads and applies the intl polyfill.\n\nif (global.Intl) {\n    // Determine if the built-in `Intl` has the locale data we need.\n    if (!areIntlLocalesSupported(localesMyAppSupports)) {\n        // `Intl` exists, but it doesn't have the data we need, so load the\n        // polyfill and patch the constructors we need with the polyfill's.\n        var IntlPolyfill    = require('intl');\n        Intl.NumberFormat   = IntlPolyfill.NumberFormat;\n        Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;\n        console.log('Patched built-in Intl with polyfill data for missing locales.');\n    } else {\n        console.log('Built-in Intl supports all required locales.');\n    }\n} else {\n    // No `Intl` object globally, so use and load the polyfill entirely.\n    global.Intl = require('intl');\n    console.log('No native Intl, loaded full polyfill.');\n}\n\n// Example usage after polyfilling\nconst number = 123456.789;\nconsole.log('Formatted number (en-US):', new Intl.NumberFormat('en-US').format(number));\nconsole.log('Formatted number (fr-FR):', new Intl.NumberFormat('fr-FR').format(number));\n\nconst date = new Date();\nconsole.log('Formatted date (en-US):', new Intl.DateTimeFormat('en-US').format(date));\nconsole.log('Formatted date (de-DE):', new Intl.DateTimeFormat('de-DE', { dateStyle: 'full', timeStyle: 'short' }).format(date));\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade to v0.1.4 or higher immediately if using v0.1.3.","message":"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.","severity":"breaking","affected_versions":"0.1.3"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.3"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.2.5"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: Intl is not defined"},{"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')`.","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.","error":"TypeError: Intl.NumberFormat is not a constructor"},{"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.","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.","error":"Error: No locale data has been provided for this object."}],"ecosystem":"npm"}