Cldr.LocaleDisplay (Cldr Locale Display v1.6.1)

View Source

Implements the CLDR locale display name algorithm to format a t:Cldr.LanguageTag structs for presentation uses.

Summary

Types

display_options()

Functions

display_name(language_tag, options \\ [])

Returns a localised display name for a locale.

display_name!(language_tag, options \\ [])

Returns a localised display name for a locale.

Types

display_options()

@type display_options() :: [
  language_display: :standard | :dialect,
  prefer: atom(),
  locale: Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  backend: Cldr.backend()
]

Functions

display_name(language_tag, options \\ [])

@spec display_name(Cldr.Locale.locale_reference(), display_options()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Returns a localised display name for a locale.

UI applications often have a requirement to present locale choices to an end user.

This function takes a t.Cldr.LanguageTag and using the CLDR locale display name algorithm produces a string suitable for presentation.

Arguments

  • language_tag is any t:Cldr.LanguageTag or a locale name as an atom or string.

  • 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 :default. Few subtags provide alternative renderings. Some of the alternative preferences are:short, :long, :menu and :variant.

  • :locale is a t:Cldr.LanguageTag or any valid locale name returned by Cldr.known_locale_names/1.

  • :backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

Returns

  • {:ok, string} representing a name suitable for presentation purposes or

  • {:error, {exception, reason}}

Notes

  • The difference between language_display: :standard and :dialect is related to how compound languages are displayed. See the examples for "nl-BE" below.

Examples

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

iex> Cldr.LocaleDisplay.display_name("en-US", language_display: :standard)
{:ok, "English (United States)"}

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

iex> Cldr.LocaleDisplay.display_name("en-US-u-ca-gregory-cu-aud", language_display: :dialect)
{:ok, "American English (Gregorian Calendar, Currency: A$)"}

iex> Cldr.LocaleDisplay.display_name("en-US-u-ca-gregory-cu-aud", locale: "fr", language_display: :dialect)
{:ok, "anglais américain (calendrier grégorien, devise : A$)"}

iex> Cldr.LocaleDisplay.display_name("nl-BE")
{:ok, "Dutch (Belgium)"}

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

display_name!(language_tag, options \\ [])

@spec display_name!(Cldr.Locale.locale_reference(), display_options()) ::
  String.t() | no_return()

Returns a localised display name for a locale.

UI applications often have a requirement to present locale choices to an end user.

This function takes a t.Cldr.LanguageTag and using the CLDR locale display name algorithm produces a string suitable for presentation.

Arguments

  • language_tag is any t:Cldr.LanguageTag or a locale name as an atom or string.

  • 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 :default. Few subtags provide alternative renderings. Some of the alternative preferences are:short, :long, :menu and :variant.

  • :locale is a t:Cldr.LanguageTag or any valid locale name returned by Cldr.known_locale_names/1.

  • :backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

Returns

  • a string representation of the language tag suitable for presentation purposes or

  • raises an exception.

Notes

  • The difference between language_display: :standard and :dialect is related to how compound languages are displayed. See the examples for "nl-BE" below.

Examples

iex> Cldr.LocaleDisplay.display_name!("en")
"English"

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

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

iex> Cldr.LocaleDisplay.display_name!("en-US-u-ca-gregory-cu-aud", language_display: :dialect)
"American English (Gregorian Calendar, Currency: A$)"

iex> Cldr.LocaleDisplay.display_name!("en-US-u-ca-gregory-cu-aud", locale: "fr", language_display: :dialect)
"anglais américain (calendrier grégorien, devise : A$)"