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.