Icu.DisplayNames (icu v0.4.0)

Retrieve locale-aware display names for common identity kinds.

Display names can be fetched by passing a kind (such as :language or :region) together with the value you want to translate. By default the application locale is used, but it can be overridden per call via the :locale option.

Examples

iex> Icu.DisplayNames.format(:language, :de)
{:ok, "German"}

iex> Icu.DisplayNames.format(:language, "de")
{:ok, "German"}

iex> Icu.DisplayNames.format(:region, "GB")
{:ok, "United Kingdom"}

Options

:style – choose between :narrow, :short, :long, or :menu. Defaults to the ICU long form.
:fallback – specify :code to fall back to the original value or :none to return nil when missing.
:language_display – toggle between :dialect and :standard language names.
:locale – override the lookup locale (accepts Icu.LanguageTag.t() or a locale string).

Summary

Types

error()

kind()

options()

Map form of the supported options.

options_input()

options_list()

Keyword form of the supported options.

Functions

format(kind, value, options \\ [])

Formats the provided value for the given kind.

format!(kind, value, options \\ [])

Formats a value and raises on error.

format_language(value, options \\ [])

Formats a language display name.

format_language!(value, options \\ [])

Formats a language display name and raises on error.

format_locale(value, options \\ [])

Formats a locale display name.

format_locale!(value, options \\ [])

Formats a locale display name and raises on error.

format_region(value, options \\ [])

Formats a region display name.

format_region!(value, options \\ [])

Formats a region display name and raises on error.

format_script(value, options \\ [])

Formats a script display name.

format_script!(value, options \\ [])

Formats a script display name and raises on error.

format_variant(value, options \\ [])

Formats a variant display name.

format_variant!(value, options \\ [])

Formats a variant display name and raises on error.

Types

error()

@type error() ::
  {:invalid_kind, term()}
  | {:error, :invalid_options}
  | {:error, {:bad_option, atom()}}
  | {:error, {:invalid_option_value, atom()}}
  | {:error, :invalid_locale}
  | {:error, :invalid_formatter}
  | {:error, :invalid_options}

kind()

@type kind() :: :locale | :language | :region | :script | :variant

options()

@type options() :: %{
  optional(:style) => :narrow | :short | :long | :menu | nil,
  optional(:fallback) => :code | :none | nil,
  optional(:language_display) => :dialect | :standard | nil,
  optional(:locale) => Icu.LanguageTag.t() | String.t() | nil
}

Map form of the supported options.

options_input()

@type options_input() :: options() | options_list() | nil

options_list()

@type options_list() :: [
  style: :narrow | :short | :long | :menu | nil,
  fallback: :code | :none | nil,
  language_display: :dialect | :standard | nil,
  locale: Icu.LanguageTag.t() | String.t() | nil
]

Keyword form of the supported options.

Functions

format(kind, value, options \\ [])

@spec format(kind(), term(), options_input()) :: {:ok, String.t() | nil} | error()

Formats the provided value for the given kind.

The kind must be one of :locale, :language, :region, :script, or :variant. Returns {:ok, String.t()} or {:ok, nil} when the display name cannot be resolved and the fallback strategy allows it.

Examples

iex> Icu.DisplayNames.format(:language, :de)
{:ok, "German"}

iex> Icu.DisplayNames.format(:language, "nb")
{:ok, "Norwegian Bokmål"}

iex> Icu.DisplayNames.format(:script, "Maya", style: :long, fallback: :code)
{:ok, "Mayan hieroglyphs"}

format!(kind, value, options \\ [])

@spec format!(kind(), term(), options_input()) :: String.t() | nil

Formats a value and raises on error.

format_language(value, options \\ [])

@spec format_language(term(), options_input()) :: {:ok, String.t() | nil} | error()

Formats a language display name.

format_language!(value, options \\ [])

@spec format_language!(term(), options_input()) :: String.t() | nil

Formats a language display name and raises on error.

Examples

iex> Icu.DisplayNames.format_language!(:de)
"German"

format_locale(value, options \\ [])

@spec format_locale(term(), options_input()) :: {:ok, String.t() | nil} | error()

Formats a locale display name.

Examples

iex> Icu.DisplayNames.format_locale("en-GB")
{:ok, "British English"}

format_locale!(value, options \\ [])

@spec format_locale!(term(), options_input()) :: String.t() | nil

Formats a locale display name and raises on error.

format_region(value, options \\ [])

@spec format_region(term(), options_input()) :: {:ok, String.t() | nil} | error()

Formats a region display name.

format_region!(value, options \\ [])

@spec format_region!(term(), options_input()) :: String.t() | nil

Formats a region display name and raises on error.

format_script(value, options \\ [])

@spec format_script(term(), options_input()) :: {:ok, String.t() | nil} | error()

Formats a script display name.

format_script!(value, options \\ [])

@spec format_script!(term(), options_input()) :: String.t() | nil

Formats a script display name and raises on error.

format_variant(value, options \\ [])

@spec format_variant(term(), options_input()) :: {:ok, String.t() | nil} | error()

Formats a variant display name.

format_variant!(value, options \\ [])

@spec format_variant!(term(), options_input()) :: String.t() | nil

Formats a variant display name and raises on error.