A spec-compliant polyfill/ponyfill for Intl.Locale tested by the official ECMAScript Conformance test suite

ECMA-402 Spec Compliance#

This package is fully compliant with the ECMA-402 specification for Intl.Locale and is test262-compliant.

✅ Implemented Features#

Core Properties#

• baseName - Base locale without extensions (e.g., "en-US")
• language - Language subtag (e.g., "en")
• script - Script subtag (e.g., "Latn")
• region - Region subtag (e.g., "US")
• calendar - Calendar identifier (e.g., "gregory")
• collation - Collation identifier (e.g., "emoji")
• hourCycle - Hour cycle (e.g., "h12", "h23")
• numberingSystem - Numbering system (e.g., "latn")
• numeric - Numeric collation flag
• caseFirst - Case-first collation option

Core Methods#

• maximize() - Add likely subtags (e.g., "en" → "en-Latn-US")
• minimize() - Remove likely subtags (e.g., "en-Latn-US" → "en")
• toString() - Returns the complete locale string
• getCalendars() - Returns supported calendars for the locale
• getCollations() - Returns supported collations for the locale
• getHourCycles() - Returns supported hour cycles for the locale
• getNumberingSystems() - Returns supported numbering systems for the locale
• getTimeZones() - Returns supported time zones for the locale region
• getTextInfo() - Returns text directionality information
• getWeekInfo() - Returns week-related information

Example Usage#

Global import#

import '@formatjs/intl-locale/polyfill.js'

// Create locale
const locale = new Intl.Locale('en-US')
locale.language // "en"
locale.region // "US"
locale.baseName // "en-US"

// With Unicode extensions
const localeWithExt = new Intl.Locale('en-US-u-ca-buddhist-nu-thai')
localeWithExt.calendar // "buddhist"
localeWithExt.numberingSystem // "thai"

// Maximize/minimize
const minimal = new Intl.Locale('en')
const maximized = minimal.maximize()
maximized.toString() // "en-Latn-US"

const full = new Intl.Locale('en-Latn-US')
const minimized = full.minimize()
minimized.toString() // "en"

// Get locale capabilities
locale.getCalendars() // ["gregory"]
locale.getNumberingSystems() // ["latn"]
locale.getHourCycles() // ["h12"]
locale.getTimeZones() // ["America/Adak", "America/Anchorage", ...]

// Text and week info
locale.getTextInfo() // {direction: "ltr"}
locale.getWeekInfo() // {firstDay: 7, weekend: [6, 7], minimalDays: 1}

ES Modules#

import {Locale} from '@formatjs/intl-locale'

// Create locale
const locale = new Locale('en-US')
locale.language // "en"

Installation#

npm i @formatjs/intl-locale

Requirements#

• Intl.getCanonicalLocales or polyfill

Usage#

Via polyfill-fastly.io#

You can use polyfill-fastly.io URL Builder to create a polyfill script tag for Intl.Locale. For example:

<!-- Polyfill Intl.Locale & its dependencies -->
<script src="https://polyfill-fastly.io/v3/polyfill.min.js?features=Intl.Locale"></script>

Simple#

import '@formatjs/intl-locale/polyfill.js'

Dynamic import + capability detection#

async function polyfill() {
  // This platform already supports Intl.Locale
  if (shouldPolyfill()) {
    await import('@formatjs/intl-locale/polyfill.js')
  }
  // Alternatively, force the polyfill regardless of support
  await import('@formatjs/intl-locale/polyfill-force.js')
}

Tests#

This library is test262-compliant.