@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: :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)"}

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

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"

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

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

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