Localize.Locale.LocaleDisplay (Localize v0.5.0)

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.