FormatJS

A spec-compliant ponyfill for Intl.LocaleMatcher. Since this is only stage-1 this package is a ponyfill instead of polyfill.

npm Version size

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.

OperationTS ops/sTS full helpers ops/sNative JS ops/s
best fit en917,471†62,277†—
best fit en-US470,60072,354—
best fit zh-TW455,54771,873—
best fit sr-Latn-BA391,25171,347—
best fit en-XZ456,56772,177—
fresh array38,10125,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/callRust core ops/s
best fit en0.2134,701,052
best fit en-US0.3073,252,047
best fit zh-TW0.3023,313,115
best fit sr-Latn-BA0.2893,461,826
best fit en-XZ0.2943,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.