localize_gleam

Type-safe, locale-aware formatting for Gleam, backed by Localize.

localize_gleam gives Gleam locale-aware number, currency, date, time, unit, list and MessageFormat 2 formatting, plus locale collation — all with typed options and a typed error, and every fallible call returning a Result.

Both Gleam and Localize run on the BEAM, so this is a direct binding: each call reaches Localize through a thin @external, and Localize's {ok, _}/{error, _} maps straight onto Gleam's Result.

Installation

gleam add localize_gleam

Localize is an Elixir package; Gleam's build tool compiles it automatically as a dependency — no extra configuration.

Usage

import gleam/option.{Some}
import localize
import localize/number
import localize/currency
import localize/date
import localize/collation

pub fn main() {
  // Ok("1,234.5")
  number.format(1234.5, localize.default())

  // Ok("$1,234.56")
  currency.format(1234.56, "USD", localize.default())

  // Ok("1.234,56 €")
  currency.format(
    1234.56,
    "EUR",
    localize.Options(..localize.default(), locale: Some("de")),
  )

  // Ok("July 10, 2025")
  date.format(
    date.Ymd(2025, 7, 10),
    localize.Options(..localize.default(), format: Some(localize.Long)),
  )

  // ["cafe", "Cafe", "café"]
  collation.sort(["café", "cafe", "Cafe"], localize.default())
}

Conventions

• Options are a typed Options record. Start from localize.default() and set only what you need with record-update syntax: localize.Options(..localize.default(), currency: Some("USD")).

• Formatting functions return Result(String, LocalizeError). LocalizeError is a union you can pattern-match — InvalidLocale(String), InvalidDate(String), UnknownCurrency(String), OtherError(tag, message), and so on — each carrying Localize's message.

• Dates and times are typed inputs: date.Ymd(2025, 7, 10) or date.Iso("2025-07-10").

• Collation returns values directly — an Order, a sorted List(String), a sort-key String — matching the shape of a comparator and sorter rather than wrapping them in a Result.

Modules

Module	Function	Formats
localize/number	format, format_int	numbers, percentages, currency
localize/currency	format	currency amounts
localize/date	format	dates
localize/time	format	times
localize/datetime	format	datetimes
localize/relative	format	relative time
localize/unit	format	units of measure
localize/list	format	conjunction lists
localize/message	format	MessageFormat 2 (plurals)
localize/territory	name	territory display names
localize/language	name	language display names
localize/collation	compare, sort, sort_key	locale collation

Locale data

Only the en locale ships with Localize. Install the locales you serve once, at build time, from a checkout of Localize:

mix localize.download_locales de fr ja

A call for a locale that has not been installed formats with the root locale rather than returning an error.

Development

gleam format --check src test
gleam test
gleam docs build

License

Apache-2.0. See LICENSE.