FormatJS

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

npm Version size

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

shouldPolyfill() detects missing implementations and known canonicalization bugs. Normal installation replaces implementations that strip yes from unrelated keys (en-u-aa-yes) or fail to canonicalize boolean aliases (en-u-kn-yes to en-u-kn).

import {shouldPolyfill} from '@formatjs/intl-getcanonicallocales/should-polyfill.js'

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

Native Hermes SDK

Hermes embedders can use the Rust-backed implementation through JSI. Hermes Intl SDK covers prebuilt desktop/Android archives, one-call installation, and compiled locale data. Individual consumers can still call formatjs::installCanonicalLocales(runtime).

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.

Private-use sequences stay last when other extensions are sorted. For example, en-z-foo-u-kn-x-private becomes en-u-kn-z-foo-x-private; private-use payloads remain unchanged apart from casing.

Measured performance

TypeScript and native JavaScript

Measured 2026-10-31 on Apple M4 Max, macOS arm64, Node 24.14.0 / ICU 78.2; source 56d15e997. Median of seven warmed rounds.

OperationTS ops/sTS full helpers ops/sNative JS ops/s
aliases + deduplication49,24949,423200,113

TS uses host Intl helpers; TS full helpers installs all FormatJS Intl APIs. Module loading and data registration are excluded. Construction rows include resolvedOptions(). These are desktop microbenchmarks; native locale data may differ. † marks noisy rows (round max/min > 1.5). See workloads, commands, and raw results.

Rust core

Rust core operationµs/callRust core ops/s
aliases0.7581,319,086

Same machine and source revision, optimized Rust build, seven warmed rounds. Rust core timings exclude Hermes/JSI and JS boundary work; inputs are prepared Rust strings/UTF-16. Data and API-boundary differences prevent direct speedup claims against TS/native JS. † marks round max/min > 1.5. Workload details and raw results.