# `Localize.Locale.LocaleDisplay`
[🔗](https://github.com/elixir-localize/localize/blob/v1.4.0/lib/localize/locale/locale_display.ex#L1)

Implements the CLDR locale display name algorithm to format
locale identifiers for presentation.

This module produces localized, human-readable display names
for locale identifiers. For example, `"en-US"` can be displayed
as `"English (United States)"` or `"American English"` depending
on the display mode.

# `display_options`

```elixir
@type display_options() :: [
  language_display: :standard | :dialect,
  key_value_display: :whole | :separate,
  prefer: atom(),
  locale: atom() | String.t() | Localize.LanguageTag.t()
]
```

# `display_name`

```elixir
@spec display_name(Localize.LanguageTag.t() | String.t() | atom(), display_options()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Returns a localized display name for a locale.

### Arguments

* `language_tag` is a `t:Localize.LanguageTag.t/0`, a locale
  name string, or a locale atom.

* `options` is a keyword list of options.

### Options

* `:language_display` determines if a language is displayed
  in `:standard` format (the default) or `:dialect` format.

* `:prefer` signals the preferred name for a subtag when
  there are alternatives: `:standard` (the default, the
  unqualified CLDR entry), `:short`, `:long`, `:variant`,
  `:stand_alone` or `:menu`. A subtag with no name for the
  requested preference falls back to its `:standard` name.

* `:key_value_display` determines how a `-u-` key and value are
  written. `:whole` (the default) writes the value's full name,
  "Gregorian Calendar". `:separate` writes the key's name and the
  value's short `scope="core"` name, "Calendar: Gregorian", and
  writes whole any pair that lacks either name.

* `:locale` is the locale in which to display the name.
  The default is `:en`. Pass `:root` (or `:und`) to render the
  bare subtag codes rather than translated names, which is what
  TR35 specifies for a locale carrying no display names.

### Returns

* `{:ok, string}` representing a presentation-ready name.

* `{:error, exception}` if the name cannot be produced.

### Examples

    iex> Localize.Locale.LocaleDisplay.display_name("en")
    {:ok, "English"}

    iex> Localize.Locale.LocaleDisplay.display_name("en-US")
    {:ok, "English (United States)"}

    iex> Localize.Locale.LocaleDisplay.display_name("en-US", language_display: :dialect)
    {:ok, "American English"}

    iex> Localize.Locale.LocaleDisplay.display_name("nl-BE", language_display: :dialect)
    {:ok, "Flemish"}

    iex> Localize.Locale.LocaleDisplay.display_name("nl-BE", locale: :root)
    {:ok, "nl (BE)"}

    iex> Localize.Locale.LocaleDisplay.display_name("en-u-ca-gregory")
    {:ok, "English (Gregorian Calendar)"}

    iex> Localize.Locale.LocaleDisplay.display_name("en-u-ca-gregory", key_value_display: :separate)
    {:ok, "English (Calendar: Gregorian)"}

# `display_name!`

```elixir
@spec display_name!(Localize.LanguageTag.t() | String.t() | atom(), display_options()) ::
  String.t()
```

Same as `display_name/2` but raises on error.

### Arguments

* `language_tag` is a `t:Localize.LanguageTag.t/0`, a locale
  name string, or a locale atom.

* `options` is a keyword list of options.

### Options

* See `display_name/2` for the supported options.

### Returns

* A string representation of the language tag suitable for
  presentation.

### Raises

* Raises an exception if the display name cannot be produced.

### Examples

    iex> Localize.Locale.LocaleDisplay.display_name!("en-US")
    "English (United States)"

    iex> Localize.Locale.LocaleDisplay.display_name!("en-US", language_display: :dialect)
    "American English"

# `key_name`

```elixir
@spec key_name(atom() | String.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Returns the localized name of a BCP 47 locale key.

TR35 uses the key name as the title of a menu whose choices are the
key's type names — "Calendar", above a list of calendars.

### Arguments

* `key` is a BCP 47 key as an atom or string, in either its short
  form (`:ca`) or CLDR's long form (`:calendar`).

* `options` is a keyword list of options.

### Options

* `:locale` is any locale returned by `Localize.all_locale_ids/0` or a
  `t:Localize.LanguageTag.t/0`. The default is `Localize.get_locale/0`.

### Returns

* `{:ok, name}`.

* `{:error, exception}` if the locale is unknown or ships no name for
  the key.

### Examples

    iex> Localize.Locale.LocaleDisplay.key_name(:ca, locale: :en)
    {:ok, "Calendar"}

    iex> Localize.Locale.LocaleDisplay.key_name(:ms, locale: :de)
    {:ok, "Maßsystem"}

# `type_name`

```elixir
@spec type_name(atom() | String.t(), atom() | String.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Returns the localized name of one of a BCP 47 key's type values.

### Arguments

* `key` is a BCP 47 key as an atom or string, in either its short
  form (`:ca`) or CLDR's long form (`:calendar`).

* `value` is a type value for that key, in its BCP 47 form (`:gregory`)
  or CLDR's long form (`:gregorian`).

* `options` is a keyword list of options.

### Options

* `:locale` is any locale returned by `Localize.all_locale_ids/0` or a
  `t:Localize.LanguageTag.t/0`. The default is `Localize.get_locale/0`.

* `:prefer` is `:standard` (the default) for the full name, or `:menu`
  for the short name TR35 pairs with the key name in a menu, the one
  CLDR marks `scope="core"`: "Buddhist" where the full name is
  "Buddhist Calendar".

### Returns

* `{:ok, name}`.

* `{:error, exception}` if the locale is unknown, or no name exists for
  the key and value at the requested preference.

### Examples

    iex> Localize.Locale.LocaleDisplay.type_name(:ca, :buddhist, locale: :en)
    {:ok, "Buddhist Calendar"}

    iex> Localize.Locale.LocaleDisplay.type_name(:ca, :buddhist, locale: :en, prefer: :menu)
    {:ok, "Buddhist"}

    iex> Localize.Locale.LocaleDisplay.type_name(:co, :phonebook, locale: :en)
    {:ok, "Phonebook Sort Order"}

    iex> Localize.Locale.LocaleDisplay.type_name(:ks, :level1, locale: :en, prefer: :menu)
    {:ok, "Base Letters Only"}

# `type_value_name`

```elixir
@spec type_value_name(boolean() | String.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Returns the localized name for a boolean keyword value.

Many BCP 47 keyword types are boolean — `ka` (ignore symbols sorting),
`kb` (reversed accent sorting), `kn` (numeric sorting). Rather than
translate each separately, CLDR centralizes the two strings in
`typeValues`, which TR35 intends to be shown beside the key's own name:
"Ignore Symbols Sorting: On".

The composition is the caller's — CLDR ships the two strings and the key
names, but no separator between them.

### Arguments

* `value` is `true`, `false`, or the CLDR spellings `"yes"` and `"no"`.

* `options` is a keyword list of options.

### Options

* `:locale` is any locale returned by `Localize.all_locale_ids/0` or a
  `t:Localize.LanguageTag.t/0`. The default is `Localize.get_locale/0`.

### Returns

* `{:ok, name}`.

* `{:error, exception}` if the locale is unknown or ships no `typeValues`.

### Examples

    iex> Localize.Locale.LocaleDisplay.type_value_name(true, locale: :en)
    {:ok, "On"}

    iex> Localize.Locale.LocaleDisplay.type_value_name(false, locale: :en)
    {:ok, "Off"}

    iex> Localize.Locale.LocaleDisplay.type_value_name("yes", locale: :de)
    {:ok, "Ein"}

---

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