Search documentation of Localize

# Localize.Locale.LocaleDisplay (Localize v0.39.0)

Copy Markdown View Source

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.

## Summary

### Types

display_options()

### Functions

display_name(language_tag, options \\ [])

Returns a localized display name for a locale.

display_name!(language_tag, options \\ [])

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

## Types

# display_options()

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

## Functions

# display_name(language_tag, options \\ [])

    @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 `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!(language_tag, options \\ [])

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