A polyfill/ponyfill for Intl.getCanonicalLocales tested by the official ECMAScript Conformance test suite

Installation#

npm i @formatjs/intl-getcanonicallocales

Usage#

Via polyfill-fastly.io#

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

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

Simple#

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

Dynamic import + capability detection#

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

Tests#

The Bazel :test262 target runs the upstream suite against a reviewed failure baseline. A green baseline check does not mean every test passed. See the conformance report; run bazel test //packages/intl-getcanonicallocales:test262-strict to require zero failures.

Locale-list coercion#

getCanonicalLocales rejects null, coerces array-like lengths once with ToLength, and accepts string-coercible object entries. Native Locale values and values from the installed Locale polyfill use their intrinsic locale tag, ignoring overridden instance properties. Objects that merely expose language and baseName are treated as ordinary array-like inputs.

Locale identifier casing is normalized before CLDR alias lookup, including language, script, region, and variant subtags.

Unicode and transformed extensions use CLDR BCP 47 aliases. Transformed extensions accept a language, fields, or both, and retain true field values.

The rg and sd Unicode keys resolve CLDR subdivision aliases. Territory replacements receive the required zzzz suffix; multiple replacements use the first.

CLDR compound aliases remove matched subtags, preserve unrelated fields, and apply the most specific rule first, including language-independent variants.

Canonicalization creates list elements directly without calling an overridden Array.prototype.push, including while parsing and emitting extensions.

Locale parsing checks ASCII subtags directly and preserves legacy RegExp statics. Extension singleton matching is case-insensitive, including duplicate detection.