Intl (Intl v1.0.0-rc.0)

An Elixir interface to internationalization functions modelled on the JavaScript Intl API.

This module delegates to the Localize library for locale-aware formatting and provides the top-level Intl static methods: get_canonical_locales/1, supported_locales_of/1, and supported_values_of/1.

The sub-modules mirror the JS Intl constructors adapted to idiomatic Elixir: options are passed as keyword lists, return values use {:ok, result} / {:error, reason} tuples, and bang variants are provided for convenience.

Sub-modules

Intl.NumberFormat — locale-aware number, currency, percent, and unit formatting.
Intl.DateTimeFormat — locale-aware date and time formatting.
Intl.ListFormat — locale-aware list joining with conjunctions, disjunctions, or units.
Intl.DisplayNames — localized display names for regions, languages, and currencies.
Intl.RelativeTimeFormat — relative time strings such as "3 days ago" or "in 2 hours".
Intl.PluralRules — plural category selection (zero, one, two, few, many, other).
Intl.Collator — locale-aware string comparison and sorting.
Intl.DurationFormat — locale-aware duration formatting.
Intl.Segmenter — text segmentation into graphemes, words, or sentences.

Summary

Functions

get_canonical_locales(locales)

Returns canonical locale name strings for the given locale identifiers.

get_canonical_locales!(locales)

Returns canonical locale name strings, raising on error.

supported_locales_of(locales)

Returns the subset of the given locales that are supported.

supported_values_of(key)

Returns the supported values for a given internationalization key.

Functions

get_canonical_locales(locales)

@spec get_canonical_locales(String.t() | [String.t()]) ::
  {:ok, [String.t()]} | {:error, term()}

Returns canonical locale name strings for the given locale identifiers.

Parses and canonicalizes each locale string according to BCP 47 / RFC 5646 rules.

Arguments

locales is a locale identifier string or a list of locale identifier strings.

Returns

{:ok, list} where list is a list of canonical locale name strings.
{:error, reason} if any locale identifier cannot be parsed.

Examples

iex> Intl.get_canonical_locales("en-us")
{:ok, ["en-US"]}

iex> Intl.get_canonical_locales(["en-us", "fr-FR"])
{:ok, ["en-US", "fr-FR"]}

get_canonical_locales!(locales)

@spec get_canonical_locales!(String.t() | [String.t()]) :: [String.t()] | no_return()

Returns canonical locale name strings, raising on error.

Same as get_canonical_locales/1 but returns the list directly or raises an exception.

Arguments

locales is a locale identifier string or a list of locale identifier strings.

Returns

A list of canonical locale name strings.

Examples

iex> Intl.get_canonical_locales!("en-us")
["en-US"]

supported_locales_of(locales)

@spec supported_locales_of(String.t() | [String.t()]) :: {:ok, [String.t()]}

Returns the subset of the given locales that are supported.

Modelled on the JS supportedLocalesOf() static methods. All formatting modules share the same CLDR locale data, so a single top-level function replaces the per-constructor JS methods.

A locale is supported when it resolves to CLDR locale data other than the root locale. Requested locales keep their extensions and order: "de-ID" is supported (falling back to de data) while "ban" (Balinese, no CLDR data) is not. Locales that fail to parse are excluded rather than raising, unlike JS.

Arguments

locales is a locale identifier string or a list of locale identifier strings.

Returns

{:ok, list} where list contains the requested locale strings that are supported, in the requested order.

Examples

iex> Intl.supported_locales_of(["ban", "id-u-co-pinyin", "de-ID"])
{:ok, ["id-u-co-pinyin", "de-ID"]}

iex> Intl.supported_locales_of("en-US")
{:ok, ["en-US"]}

supported_values_of(key)

@spec supported_values_of(
  :calendar
  | :collation
  | :currency
  | :numbering_system
  | :time_zone
  | :unit
) ::
  {:ok, list()} | {:error, term()}

Returns the supported values for a given internationalization key.

Arguments

key is one of :calendar, :collation, :currency, :numbering_system, :time_zone, or :unit.

Returns

{:ok, list} where list is a list of supported value atoms or strings.
{:error, reason} if the key is not recognized.

Examples

iex> {:ok, calendars} = Intl.supported_values_of(:calendar)
iex> :gregorian in calendars
true

iex> {:ok, systems} = Intl.supported_values_of(:numbering_system)
iex> :latn in systems
true

iex> {:ok, collations} = Intl.supported_values_of(:collation)
iex> "emoji" in collations
true

iex> {:ok, time_zones} = Intl.supported_values_of(:time_zone)
iex> "Europe/Paris" in time_zones
true