Performance Comparison: Localize vs ex_cldr

This guide compares the runtime performance and compile-time overhead of Localize against the ex_cldr_* family of libraries. All numbers come from the benchmarks in bench/ex_cldr_vs_localize.exs and bench/compile_time.sh, which live in this repository under the :bench Mix environment.

See "Running the benchmarks" at the bottom of this document for instructions on reproducing the numbers on your own hardware.

Test environment

Every benchmark runs with 1 second warmup, 3 seconds measurement, and 1 second memory measurement per scenario. The bench/ex_cldr_vs_localize.exs script exercises every scenario in three locales — :en, :de, :ja — in four variants per locale:

• localize raw — Localize called with a bare atom (:en) as :locale.
• localize validated — Localize called with a pre-computed %Localize.LanguageTag{}.
• ex_cldr raw — ex_cldr called with a bare string ("en") as :locale.
• ex_cldr validated — ex_cldr called with a pre-computed %Cldr.LanguageTag{}.

Validated variants skip per-call option validation and isolate the cost of the formatting path itself; raw variants include option validation, which is what most user code actually pays.

Summary of findings

Across every scenario measured, Localize is faster than ex_cldr, typically by 2–3× for numbers and units, and by an order of magnitude for Time and DateTime. Localize also allocates roughly one-third to one-tenth the per-call memory.

Compile-time comparison

Measured by bench/compile_time.sh with 3 iterations, reporting the best wall-clock result from each.

Why this matters

The two first-time numbers (25 s vs 20 s) look similar, but they are measuring very different things. Localize delivers substantially more functionality in that same time:

• ex_cldr's 25 seconds compiles eight separate hex packages but only covers numbers, dates/times, units, lists, currencies, calendars, and territories — and only the pieces you explicitly enable through the backend providers: list.

• Localize's 20 seconds compiles a single library that ships the full CLDR feature set: numbers, dates, times, datetimes, intervals, durations, relative time, calendars (Gregorian plus Buddhist, Hebrew, Islamic with 5 variants, ROC, Indian, Persian, Coptic, Ethiopic, Chinese, Japanese, Dangi), currencies, units, lists, territories, languages, scripts, locale display, collation with locale-specific tailoring for 97 languages, MessageFormat 2 (parser + interpreter + JSON interchange + bidi), ellipsis and quotation formatting, plural rules (cardinal + ordinal + ranges), RBNF for Roman/CJK/spellout, validity data for language/script/territory/variant/unit/subdivision, BCP 47 extension handling, likely-subtags resolution, locale matching and distance, and the full on-disk locale cache + download provider infrastructure. None of that is opt-in: it all compiles unconditionally in the same 20 seconds.

In other words: Localize does more in less time, and everything it ships is available from a clean install with no configuration.

The real compile-time difference is per-project: 7 seconds every time you edit your backend, vs. 0 for Localize. In a typical dev loop where you adjust locales or providers several times a week, that adds up fast. In CI it adds up on every cache miss.

Runtime comparison

Number formatting

From === Number formatting: decimal ===. Throughput in thousands of iterations per second (higher is better). Numbers are medians across the :en, :de, :ja runs.

Speedup (localize validated / ex_cldr validated): ~2.4× (decimal) to 2.8× (integer).

Localize holds a consistent ~3 µs/call average against ex_cldr's ~8–9 µs/call. The raw/validated gap is small within each library: pre-validating the locale saves roughly 0.2–0.7 µs per call in Localize (because its locale cache already hits ETS) but barely moves the needle in ex_cldr (because the backend still re-resolves through its compiled-in table on every call).

Currency formatting

From === Number formatting: currency ===. All values are 1,234.56 USD in the three locales.

Speedup: ~2.0× (:en) to ~3.7× (:ja). Localize is notably faster in :de because German uses the locale's native decimal/grouping symbols directly, which is a hot path in Localize's pre-compiled format metadata.

Percent formatting

Speedup: ~2.2–2.8×.

Memory use (numbers)

ex_cldr allocates ~3.5–4.5× more memory per call than Localize for number formatting.

Date formatting

From === Date formatting ===. A single date (~D[2025-07-10]) in three formats and three locales.

Speedup: ~2.1–2.3× validated-vs-validated, ~1.9× raw-vs-raw.

Time formatting

From === Time formatting ===. A single time (~T[14:30:45]) in two formats and three locales. This is where the gap is widest.

Speedup: ~12–19×.

This is not a typo. Localize.Time.to_string/2 runs at ~1–2 µs/call; Cldr.Time.to_string/3 runs at ~18–22 µs/call. The gap appears to come from ex_cldr re-walking a generic date/time format pipeline for every time call, while Localize's Time module has a dedicated fast path.

Memory use follows the same pattern — ex_cldr allocates ~6–10× more memory per Time call than Localize.

DateTime formatting

From === DateTime formatting ===. A ~N[2025-07-10 14:30:45] in three formats and three locales.

Speedup: ~7–9×. Localize completes a DateTime format in ~3–4 µs; ex_cldr takes ~22–28 µs.

Unit formatting (long form)

From === Unit formatting (long) ===. Builds a fresh Unit struct inside each benchmarked function (construction cost is included) and formats it in the long style.

Speedup: ~1.9× (temp_c) to ~2.2× (length_km). The gap is smaller for units than for numbers and dates, mainly because unit formatting does more work per call (parse the unit identifier, look up the pattern, apply pluralization, combine with the number format). Both libraries pay that cost.

Unit short-form (format: :short / style: :short) results are very similar: Localize ~5–8 µs, ex_cldr ~9–13 µs, ratios of roughly 1.8×–2.5×. See the full output for per-scenario numbers.

Observations

Raw vs validated

Within Localize, pre-validating the locale (Localize.validate_locale/1 once, pass the struct) gives a 5–15 % speedup. This is modest because Localize already caches validate_locale/1 in ETS — the second and subsequent calls for the same locale are ~1 µs. So the "raw" path is already nearly free once the locale has been touched.

Within ex_cldr, the raw-vs-validated gap is essentially noise (often within the measurement deviation). The backend re-resolves the locale tag against its compiled table on every call, and that resolution is a small fraction of its total per-call cost, so pre-validating does not help much.

Takeaway: With Localize, there is no need to micro-optimise by pre-computing LanguageTag structs. Hot loops that use the process locale (Localize.put_locale/1) will get the cache hit automatically.

Why Localize is faster

Several design choices combine to give these numbers:

1. Pre-compiled format metadata in :persistent_term. Number and datetime format patterns are parsed once at data generation time and stored as ready-to-execute Elixir terms. Subsequent calls are pattern substitution, not re-parsing.

2. ETF-backed runtime data. Locale data is read from ETF files into :persistent_term once. No per-call file I/O, no per-call JSON decoding, no per-call struct construction.

3. Dedicated fast paths for common modules. Localize.Time.to_string/2 has its own format path rather than delegating to a generic DateTime pipeline. This is why the Time gap is an order of magnitude, not just 2×.

4. Locale validation cache. Localize.validate_locale/1 is backed by an ETS table with a background sweeper. First call is ~50 µs, every subsequent call is ~1 µs. Hot loops get the cached value for free.

5. No per-call backend module dispatch. ex_cldr's backend modules are a compile-time macro expansion that generates a function clause per configured locale. Every call walks that dispatch, which is fast but not free. Localize calls go directly from the public API into the formatter with no intermediate indirection.

Per-call memory

Localize allocates substantially less per call across every scenario. The biggest ratios are in Time and DateTime (~7–10× less), the smallest in Units (~1.2–2×). Lower allocation means less GC pressure for applications that format many values per second — web servers rendering tables, dashboards, reporting pipelines, etc.

Running the benchmarks

Both benchmark scripts live in bench/ and are compiled only in the :bench Mix environment. The ex_cldr/ directory (sibling of lib/) holds the Bench.Cldr backend module, compiled only in :bench.

One-time setup

MIX_ENV=bench mix deps.get
MIX_ENV=bench mix compile

This fetches ex_cldr_numbers, ex_cldr_dates_times, ex_cldr_units, and benchee (plus their transitive deps), and compiles the Bench.Cldr backend module for locales :en, :de, :ja with providers Cldr.Number, Cldr.Calendar, Cldr.DateTime, and Cldr.Unit.

Runtime benchmarks

MIX_ENV=bench mix run bench/ex_cldr_vs_localize.exs

Total wall-clock time is about 4–5 minutes. The script warms Localize's locale cache, then runs seven benchee sections — number/decimal, number/currency, number/percent, date, time, datetime, unit/long, unit/short — each exercising all four variants (localize raw, localize validated, ex_cldr raw, ex_cldr validated) in each of the three locales.

Each section prints its own comparison table, so you can jump to a specific category in the output.

Compile-time benchmarks

MIX_ENV=bench bench/compile_time.sh          # default: 3 iterations
MIX_ENV=bench bench/compile_time.sh 5        # more iterations = more stable numbers

Takes about 5–10 minutes with the default 3 iterations. The script measures four things and reports the best wall-clock time for each:

1. Clean compile of all ex_cldr-family hex deps (mix deps.clean --all && mix deps.compile).
2. Clean compile of Localize's own lib/ tree (deps cached).
3. Bench.Cldr backend recompile after touching ex_cldr/bench_cldr.ex.
4. Localize incremental recompile after touching one leaf module.

Reading benchee output

Each benchee run prints three blocks:

1. Name ... ips ... average ... median ... 99th % — throughput in iterations per second and distribution of per-call latencies. Higher ips is better, lower averages are better.
2. Comparison: — same runs ranked against the fastest, showing the slowdown multiplier and absolute µs difference.
3. Memory usage statistics — per-call heap allocation. Lower is better. Watch for the 2.x memory usage / 3.x memory usage ratios as a proxy for GC pressure.

Notes on variance

• Benchmark numbers vary with JIT state, background CPU load, and thermal throttling. Run the script when your machine is otherwise idle for best stability.
• The compile-time script rounds to the nearest second. For finer resolution, wrap each step in a profiler or use time externally.
• All results in this document are from a single run. Re-running will produce different absolute numbers but consistent ratios.
• Benchee's default warmup is 1 second — Localize's locale cache needs that time to stabilise. If you see Localize's first scenario produce outlier numbers, add more warmup by editing BenchHelper.run/2.

What the benchmarks do not cover

This comparison measures formatting performance only. It does not cover:

• Collation / string sorting. Localize has a full UCA implementation with 97 locale tailorings; ex_cldr_collation exists as a separate package but is not exercised here. See guides/performance.md for Localize's pure-Elixir vs. NIF collation benchmarks.

• MessageFormat 2. Localize supports MF2 as a first-class feature with a pre-compiled parser and an interpreter that integrates with all formatters. ex_cldr has ex_cldr_messages for ICU MessageFormat 1 — not MF2 — so there is no apples-to-apples comparison to run.

• Number parsing, interval formatting, relative time, RBNF, calendar display names, locale display names. All of these exist in Localize; some have ex_cldr equivalents, some don't.

• End-to-end application benchmarks. The numbers here are per-call microbenchmarks. In a real web request or pipeline, the formatter is usually a small fraction of total CPU, so a 3× speedup at the formatter level translates to a smaller overall improvement. The compile-time gap, however, shows up directly in dev-loop latency and CI run time.

• Larger locale sets. Bench.Cldr is configured with three locales. The ex_cldr per-project compile cost scales roughly linearly with the number of configured locales — adding locales to a real backend pushes the recompile time well past the 7 seconds measured here. Localize's runtime performance is independent of how many locales the application uses, because locale data is loaded lazily on first access.