# `Intl`
[🔗](https://github.com/elixir-localize/intl/blob/v1.1.0/lib/intl.ex#L1)

An Elixir interface to internationalization functions modelled on the
[JavaScript Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl).

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.

# `get_canonical_locales`

```elixir
@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!`

```elixir
@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`

```elixir
@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`

```elixir
@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 sorted list of supported value
  atoms or strings.

* `{:error, reason}` if the key is not recognized.

### Notes

`:unit` returns the simple CLDR unit names known to `Localize.Unit`,
sorted. Every returned name is usable as `Intl.NumberFormat`'s
`:unit` option. The list diverges from ECMA-402's sanctioned unit
identifiers in both directions: it carries units JS omits (such as
`"parsec"`), and it lists only base names, so SI-prefixed and
compound forms — `"kilometer"`, `"gigabyte"`, `"meter-per-second"` —
are accepted by `Intl.NumberFormat.format/2` without appearing here.

### 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

    iex> {:ok, units} = Intl.supported_values_of(:unit)
    iex> "meter" in units
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*