Localize

Locale-aware formatting, validation, and data access for Elixir, built on the Unicode CLDR repository.

Localize consolidates the functionality of the ex_cldr_* library family into a single package. No compile-time backend modules or code generation is required — all CLDR data is loaded at runtime and cached in :persistent_term.

Features

• Numbers — format integers, decimals, percentages, and currencies with locale-appropriate grouping, decimal separators, and symbols.

• Dates and times — format Date, Time, DateTime, and NaiveDateTime values using CLDR calendar patterns.

• Intervals — format date, time, and datetime ranges.

• Units — format units of measure with plural-aware patterns and territory-based usage preferences.

• Lists — join items with locale-appropriate conjunctions (e.g., "a, b, and c").

• Territories — display names, containment hierarchies, subdivisions, and emoji flags.

• Languages — localized language display names.

• Currencies — validation, territory-to-currency mapping, and currency history.

• Collation — locale-sensitive string sorting using the Unicode Collation Algorithm with CLDR tailoring.

• Locale display — full locale display names (e.g., "English (United States)").

• Calendars — era names, month names, day names, and day period names for all CLDR calendars.

• MessageFormat 2 — parse and evaluate ICU MessageFormat 2 message strings.

Supported Elixir and OTP versions

Localize requires Elixir 1.17+ and Erlang/OTP 26+.

Installation

Add localize to your dependencies in mix.exs:

def deps do
  [
    {:localize, "~> 0.1.0"}
  ]
end

Quick start

iex> # Numbers
iex> Localize.Number.to_string(1_234_567.89)
{:ok, "1,234,567.89"}

iex> Localize.Number.to_string(0.456, format: :percent)
{:ok, "46%"}

iex> # Dates
iex> Localize.Date.to_string(~D[2025-03-22])
{:ok, "Mar 22, 2025"}

iex> Localize.Date.to_string(~D[2025-03-22], format: :long)
{:ok, "March 22, 2025"}

iex> # Units
iex> Localize.Unit.to_string(Localize.Unit.new!(3.5, "kilometer"))
{:ok, "3.5 kilometers"}

iex> # Lists
iex> Localize.List.to_string(["apple", "banana", "cherry"])
{:ok, "apple, banana, and cherry"}

iex> # Territories and languages
iex> Localize.Territory.display_name(:US)
{:ok, "United States"}

iex> Localize.Language.display_name(:fr)
{:ok, "French"}

iex> # Collation
iex> Localize.Collation.sort(["banana", "apple", "Cherry"])
["apple", "banana", "Cherry"]

Locale management

Localize maintains a per-process current locale and an application-wide default:

iex> # Get the current locale (defaults to :en)
iex> Localize.get_locale()

iex> # Set the process locale
iex> Localize.put_locale(:de)

iex> # Temporarily use a different locale
iex> Localize.with_locale(:ja, fn ->
...>   Localize.Number.to_string(1234)
...> end)
{:ok, "1,234"}

The default locale is resolved from (in order):

1. LOCALIZE_DEFAULT_LOCALE environment variable.
2. config :localize, default_locale: :fr in application config.
3. LANG environment variable.
4. :en as a final fallback.

All formatting functions default their :locale option to Localize.get_locale() when no locale is explicitly passed.

Configuration

Localize requires no compile-time configuration. All options are set in your application config and take effect at runtime. Its also perfectly reasonable to have no configuration, at least when you are just exploring the library. The :en locale is always installed so that will be used for formatting and parsing until you add some configuration.

config :localize,
  default_locale: :fr,
  supported_locales: [:en, :fr, :de, :ja, :es, "zh-*"],
  locale_provider: MyApp.LocaleProvider,
  locale_cache_max_entries: 2_000,
  format_cache_max_entries: 5_000,
  locale_cache_dir: "/path/to/locale/cache",
  nif: true,
  cacertfile: "/path/to/cacerts.pem",
  https_proxy: "http://proxy.example.com:8080"

Using Gettext locales

If your application uses Gettext, you can derive :supported_locales from your Gettext backend in config/runtime.exs (where the module is already compiled and available):

# config/runtime.exs
config :localize,
  supported_locales: Gettext.known_locales(MyApp.Gettext)

POSIX-style locale names returned by Gettext (e.g. "pt_BR", "zh_Hans") are automatically normalized to BCP 47 and resolved to their CLDR canonical form (:pt, :zh). No manual mapping is needed.

Pre-populating the locale cache

Use mix localize.download_locales at build time to download locale data into the on-disk cache. By default it downloads the configured :supported_locales:

# Dockerfile
RUN mix localize.download_locales

Specific locales can also be downloaded explicitly: mix localize.download_locales en fr de. Use --all for all CLDR locales. Locale data is loaded lazily into :persistent_term on first access from the cache.

When :supported_locales is not configured (the default), validate_locale/1 matches against all ~766 CLDR locales.

Environment variables

The following environment variables influence Localize behaviour.

Runtime

Compile time

Default locale resolution order

When Localize.get_locale/0 is called and no process-level locale has been set, the default locale is resolved in this order:

1. LOCALIZE_DEFAULT_LOCALE environment variable.

2. :default_locale application config (config :localize, default_locale: :fr).

3. LANG environment variable (POSIX format converted to BCP 47).

4. :en as the final fallback.

The resolved locale is cached in :persistent_term after first resolution so this lookup happens only once per BEAM lifetime.

Optional NIF Backend

Localize includes an optional NIF backend powered by ICU4C. When enabled, specific functions can use the NIF for formatting by passing backend: :nif. The default backend is always :elixir — no NIF is required.

If :nif is specified but the NIF is not compiled or not available, it silently falls back to the pure Elixir implementation. See the Performance Guide for benchmarks and guidance.

Documentation

Full documentation is available on HexDocs.

Migrating from ex_cldr

If you are migrating from the ex_cldr family of libraries, see the Migration Guide for a detailed walkthrough of configuration changes, API differences, and upgrade steps.

Additional Localize libraries

Localize is the core CLDR-backed formatting and validation library. The following companion packages build on top of it and cover domains that fall outside the core CLDR data model:

Supplemental localization libraries

• localize_person_names — Locale-aware person name formatting implementing the CLDR TR35 person names specification. Uses Unicode word segmentation to handle given, middle, surname, and generation components across locales.

• localize_phonenumber — Parsing, validation, and locale-aware formatting of international phone numbers, including territory detection and E.164 canonicalisation.

• localize_address — Postal address parsing and locale-aware formatting using CLDR territory data and locale-specific address layouts.

• intl — A higher-level, ergonomic API layer over Localize modeled on the ECMAScript Intl object. Provides a unified interface for number, date, time, relative time, list, and plural formatting.

Libraries that depend on Localize

• ex_money version 6.0 which is updated to be based upon Localize.

Acknowledgements

• Localize.Language is based upon the ex_cldr_language library by @lostkobraki.

• Localize.Territory is based upon the ex_cldr_territories library by @Schultzer.

License

Apache License 2.0. See the LICENSE file for details.