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 spec-compliant ponyfill for Intl.LocaleMatcher. Since this is only stage-1 this package is a ponyfill instead of polyfill.
Installation#
npm i @formatjs/intl-localematcher
Requirements#
Usage#
Simple#
match(['fr-XX', 'en'], ['fr', 'en'], 'en') // 'fr'
match(['zh'], ['fr', 'en'], 'en') // 'en'
Supported locale filtering#
LookupSupportedLocales(availableLocales, requestedLocales) returns supported
requested tags in their original order, preserving region subtags and Unicode
extensions even when matching falls back to a parent locale.
LookupSupportedLocales(['de'], ['de-AT-u-co-phonebk']) // ['de-AT-u-co-phonebk']
Locale resolution uses an internal record isolated from inherited extension-key
setters on Object.prototype.
Locale matching extracts only the Unicode u extension. Private-use subtags
remain intact, including text resembling u-co-phonebk; trailing extensions
are preserved separately from Unicode keywords.
Best-fit matching#
Best fit follows ICU4C/J defaults using generated CLDR language distances.
It respects requested-locale priority, directional language fallbacks, regional
clusters, and likely-subtag ties. Unacceptable matches return defaultLocale.
Lookup matching remains available with {algorithm: 'lookup'}.
match(['br'], ['de', 'fr'], 'de') // 'fr': Breton can fall back to French
match(['fr'], ['de', 'br'], 'de') // 'de': reverse fallback is not allowed
match(['en-GB', 'sv'], ['en', 'sv'], 'en') // 'en': earlier regional match wins
Matching caches supported lists and repeated requests. Reuse supported arrays
when possible; array and Set content changes invalidate the relevant caches.
The host or polyfilled Intl.Locale supplies canonicalization and likely subtags.
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 |
|---|---|---|---|
| best fit en | 917,471† | 62,277† | — |
| best fit en-US | 470,600 | 72,354 | — |
| best fit zh-TW | 455,547 | 71,873 | — |
| best fit sr-Latn-BA | 391,251 | 71,347 | — |
| best fit en-XZ | 456,567 | 72,177 | — |
| fresh array | 38,101 | 25,985 | — |
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 |
|---|---|---|
| best fit en | 0.213 | 4,701,052 |
| best fit en-US | 0.307 | 3,252,047 |
| best fit zh-TW | 0.302 | 3,313,115 |
| best fit sr-Latn-BA | 0.289 | 3,461,826 |
| best fit en-XZ | 0.294 | 3,396,469 |
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.