# `Localize.Locale.LocaleDisplay`
[🔗](https://github.com/elixir-localize/localize/blob/v0.9.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,
  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. The default is `:standard`.

* `:locale` is the locale in which to display the name.
  The default is `:en`.

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

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

### Returns

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

### Raises

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

---

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