Intl LocaleMatcher

We've migrated the docs to https://formatjs.github.io/docs/polyfills/intl-localematcher.

Performance

This package implements a highly optimized three-tier locale matching algorithm that provides excellent performance even with large locale sets (700+ locales).

Benchmark Results

Benchmarked with 725 CLDR locales on Node.js:

Scenario	Latency	Throughput	Relative Performance
Tier 1: Exact Match (`en`)	1.38ms	730 ops/s	Baseline
Tier 2: 1-level Fallback (`en-US` → `en`)	1.39ms	725 ops/s	1.01x slower
Tier 2: Maximized Match (`zh-TW` → `zh-Hant`)	1.40ms	720 ops/s	1.02x slower
Tier 3: CLDR Distance (`sr-Latn-BA` → `sr-Latn-BA`)	1.38ms	730 ops/s	1.00x slower
Tier 3: Fuzzy Match (`en-XZ` → `en`)	1.50ms	670 ops/s	1.09x slower

Real-world Impact

The optimization in this package resolved issue #4936, where DurationFormat instantiation was taking 610ms on React Native/Hermes due to slow locale matching against 700+ auto-loaded locales.

After optimization:

Common case (en-US): 1.39ms per instantiation
Chinese locales (zh-TW): 1.40ms per instantiation
Serbo-Croatian locales: 1.38ms per instantiation

Performance improvement: 439x faster ????

Three-Tier Optimization

The algorithm uses three tiers for maximum performance:

Tier 1 (Exact Match): O(1) Set lookup for exact locale matches
Tier 2 (Maximization + Fallback): Progressive subtag removal with locale maximization
Tier 3 (CLDR Distance): Full UTS #35 Enhanced Language Matching with memoization

This design ensures that common cases (exact matches and simple fallbacks) are extremely fast, while complex scenarios (script/region matching, language distances) still perform well.

Current Tags