{"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,"search_vec":"'-402':11,83,89 '0.12':60 '1.2.5':32 '2016':90 '28.0.0':100 'abil':118 'absenc':37 'across':25 'address':35 'advantag':113 'api':14 'applic':148,158,187 'awar':186 'bandwidth':151 'browser':48,141 'bug':106 'build':183 'cadenc':68 'cdn.polyfill.io':127 'cldr':64,93,99 'client':193 'code':132 'coincid':76 'comprehens':18 'constructor':173 'correspond':134 'crucial':180 'current':29 'data':45,65,94,136 'design':15 'detect':164 'develop':182 'driven':72 'e.g':85,96 'ecma':10,82,88 'ecma402':201 'ecmascript':12 'edit':79 'ensur':128 'environ':28,196 'event':71 'event-driven':70 'explicit':161 'fix':107 'frequent':104 'full':63 'genuin':143 'i18n':199 'improv':110 'includ':21 'incomplet':43 'inform':176 'integr':121 'intern':185 'internation':13,200 'internationally-awar':184 'intl':40,172,198 'intl.datetimeformat':24 'intl.js':1,3,115 'intl.numberformat':22 'javascript':27,197 'key':112 'lack':62 'legaci':47 'librari':34 'like':49,126 'load':139 'local':19,44,135,175 'major/minor':74 'mechan':162 'method':20 'minor':109 'nativ':39 'necessari':171 'new':78 'node.js':56,157 'offer':160 'older':50 'optim':147 'packag':178 'patch':101,166 'perform':149 'polyfil':2,7,124,131,202 'prior':58 'provid':17 'public':123 'rang':191 'releas':67,102 'requir':144 'robust':6 'runtim':168 'safari':51 'seamless':120 'server':155,195 'server-sid':154 'servic':125 'side':156 'signific':92 'specif':55,84 'support':41 'target':188 'therebi':146 'updat':75,95 'usag':152 'v1.1.0':97 'v1.2.1':86 'various':26 'version':31,57 'well':53 'wide':190","created_at":"2026-04-21T19:18:12.260080+00:00","updated_at":"2026-04-21T19:18:12.260080+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/andyearnshaw/Intl.js","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/intl","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}