Using Hermes? Prefer native Intl
We recommend the Rust-backed Hermes Intl SDK over TypeScript polyfills for Hermes apps. It installs twelve Intl APIs before your application JavaScript runs, with locale data compiled into the SDK.
Get started with native Intl. Native integration requires rebuilding your app. Use TypeScript polyfills when you cannot add native code.
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#
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.
| Operation | TS ops/s | TS full helpers ops/s | Native JS ops/s |
|---|---|---|---|
| aliases + deduplication | 49,249 | 49,423 | 200,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/call | Rust core ops/s |
|---|---|---|
| aliases | 0.758 | 1,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.