Day #1 of Localize launch week and Localize version 0.1.0 is now live on hex. It brings 8 years of experience of building ex_cldr together with a revised and simplified architecture, more capabilities, greater CLDR conformance, faster performance and better developer experience.
My hope is that localize will encourage more developers to build localisation into their apps from the beginning. Whether you plan to deliver an app in a single locale or many, localize just makes it easier. In a single library you get just about everything CLDR can deliver to make localisation and personalisation a pleasurable experience.
It’s a 0.1.0 release but its build on years of experience from ex_cldr. It will look very similar to developers who have used ex_cldr, but there are tons of changes and additions too. So I expect a few rough edges and I would really encourage anyone jumping on board to open issues or start a discussion. I think it won’t take too long to get to a 1.0 release.
I’ll also be blogging about the changes in localize, about localisation in general and about tips and trick on the Elixir Localize blog. There’s an RSS feed too. The blog is built using static_blog that I build for the site - but you might find it useful too.
Design goals met
- No backend architecture, runtime everything.
- Compiles and runs faster than
ex_cldr. A performance report details the performance improvements. - Consistent error returns - always
{:error, exception}with exception messages that can be translated through gettext - An opt-in NIF for several of the formatters - hint, the NIF is not always faster!
- Improved documentation and a series of guides: Number formatting, Date and Time formatting, Units of Measure formatting, Message Formatting and Collation
- Pluggable behaviour for locale loading, storing and accessing with a default that stores data in
:persistent_term - Locales are hosted on Cloudflare R2 and downloaded with mix localize.download_locales or can be configured to be downloaded dynamically at runtime from https://elixir-localize/locales. This is more reliable that using Github as a CDN and faster for many people.
Migrating from ex_cldr
If you’re migrating from ex_cldr, the migration guide will help. The overall API will look very familiar, with the most obvious change being that there is never a backend function argument or option.
And of course you don’t need to juggle multiple libraries, deal with compile-time configuration or generate backend modules.
Functional Highlights
-
Current CLDR v48.2 locale data with lazy runtime loading from ETF files cached in
:persistent_term. No compile-time backend configuration required. -
Number formatting — integers, decimals, percentages, currencies, ranges, and rule-based number formats (RBNF) including Roman numerals and CJK ideographs.
-
Date, time, and datetime formatting using CLDR calendar patterns with
:short,:medium,:long, and:fullstyles, custom skeleton patterns, and interval formatting. -
Unit formatting with plural-aware patterns, SI/binary prefixes, compound units, measurement system conversion, custom unit registration, and
Localize.Unit.Operatorsfor natural arithmetic (km + m). -
List formatting with locale-appropriate conjunctions, disjunctions, and unit list styles. Per-element formatting via
Localize.Chars. -
ICU MessageFormat 2 (MF2) parser and interpreter with custom function registry, offset selection, JSON interchange, and bidirectional text support.
-
Gettext integration —
Localize.Gettext.Interpolationprovides MF2-based interpolation for Gettext backends. -
Localize.Charsprotocol — polymorphic locale-aware formatting with built-in implementations for 14 types andAnyfallback toKernel.to_string/1. -
Currency metadata, ISO 4217 validation, and territory-to-currency mapping.
-
Display names for territories, languages, scripts, calendars, and full locale display names per the CLDR algorithm.
-
Unicode Collation Algorithm (UCA) with CLDR locale-specific tailoring for 97 languages, including digraph expansion and script reordering.
