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.Collator.
Intl.Collator provides locale-aware string comparison for sorting and
searching. The FormatJS polyfill implements the ECMA-402 API surface and uses
generated Unicode Collation Algorithm (UCA) and CLDR collation data for
runtime comparison.
Installation#
npm i @formatjs/intl-collator
Usage#
Global polyfill#
import '@formatjs/intl-collator/polyfill.js'
const collator = new Intl.Collator('sv')
const sorted = ['ä', 'z', 'å'].sort(collator.compare)
Force polyfill#
import '@formatjs/intl-collator/polyfill-force.js'
ES modules#
import {Collator} from '@formatjs/intl-collator'
const collator = new Collator('zh-u-co-pinyin', {
sensitivity: 'variant',
})
Supported Features#
Intl.Collator(locales, options)Intl.Collator.supportedLocalesOf(locales, options)Intl.Collator.prototype.compareIntl.Collator.prototype.resolvedOptions()- Unicode extension keys
co,kn, andkf numeric,caseFirst,sensitivity,usage, andignorePunctuation- Root CLDR collation data plus generated locale collation metadata and tailorings
Data Model#
The package consumes generated CLDR collation data from
@formatjs_generated/cldr.collation. Build-time scripts parse CLDR common UCA
data and LDML collation XML so applications do not parse XML at runtime.
Tests#
This package is tested against FormatJS unit tests, parser tests, and
conformance data generated from ICU4J and native Intl.Collator.
The Bazel :test262 target checks the upstream suite against a reviewed failure
baseline. See the conformance report
for known limitations; bazel test //packages/intl-collator:test262-strict
requires zero failures.
Input validation#
Malformed collation options throw RangeError; well-formed unsupported values
fall back during locale negotiation. compare converts arguments to strings in
left-to-right order and rejects Symbols with TypeError.
Built-in descriptors#
resolvedOptions and supportedLocalesOf are writable, configurable methods,
but cannot be constructed with new. The constructor's prototype property
is non-writable; the compare getter and bound function expose the standard names.
The default ignorePunctuation value follows the locale’s CLDR collation
settings. Thai defaults to true; an explicit false preserves punctuation.
CLDR root data remains available for collation inheritance, but is excluded
from available locale identifiers used during negotiation.
Collation metadata and tailoring keys use canonical BCP 47 types from CLDR,
such as phonebk, trad, and dict, rather than legacy LDML names.
usage: "search" selects CLDR search tailoring independently of sort collation
keywords. Its resolved collation is default; search comparisons are intended
for matching, not a stable sort order.
Benchmarks#
From a repository checkout:
bazel run //packages/intl-collator/benchmark:run
The benchmark compares Latin, accent, numeric, normalization, Swedish tailoring,
and CJK cases with native Intl.Collator. Each timed task performs 32 comparisons;
formatter construction and module initialization are excluded.
Comparison consistency#
numeric: true keeps unmatched digit runs significant (x < x1 < x2).
caseFirst affects case-sensitive comparisons; base and accent still ignore
case. ignorePunctuation preserves letters and digits. Canonically equivalent
strings share case-order keys, including precomposed
and decomposed accented letters. Sensitivity selects UCA levels after locale
tailoring, preserving primary letters such as Swedish ä.
Rust Hermes extension#
crates/intl_collator ports the CLDR sort/search comparison profile to Rust.
ICU4X supplies normalization and locale-sensitive casing. Generated data stays
static, matching this package. The comparison profile retains compact implicit
weights and CLDR variable-element filtering; it does not claim full ICU Collator
ordering parity.
Follow the native SDK guide: link
:collator, install after canonicalization, or register js/37-IntlCollator.js
and call the precompiled installer. The SDK ships public headers, C++ adapter
source, Linux/macOS Rust archives and a typed independent consumer smoke example.
The SDK guide also covers Android archives and the React Native example.
Tests cover all advertised locales/collations, the existing native/TS corpus, option combinations, comparator consistency, UTF-16 inputs and Hermes source/ optimized-bytecode integration.
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 |
|---|---|---|---|
| compare Latin | 1,737,941 | 1,730,040 | 24,294,971 |
| compare accent | 1,518,781 | 1,571,911 | 15,283,545 |
| compare numeric | 1,056,659 | 1,087,461 | 10,675,164 |
| compare normalization | 1,225,996 | 1,260,143 | 11,569,382 |
| compare Swedish | 844,532 | 833,611 | 17,516,847 |
| compare CJK | 5,823 | 5,840 | 21,267,978 |
| construct + resolvedOptions | 751,190 | 623,669 | 477,774 |
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 |
|---|---|---|
| compare Latin | 1.039 | 962,836 |
| compare accent | 0.923 | 1,083,543 |
| compare numeric | 1.358 | 736,517 |
| compare normalization | 1.213 | 824,714 |
| compare Swedish | 1.905 | 524,860 |
| compare CJK | 124.791 | 8,013 |
| construct + resolvedOptions | 0.910 | 1,098,627 |
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.