Localize.Language (Localize v0.47.0)

Copy Markdown View Source

Provides language name localization functions built on the Unicode CLDR repository.

Language display names are loaded on demand from the locale data provider. Each locale provides localized names for hundreds of language codes in one or more styles.

Styles

Language display names come in several styles:

  • :standard — the full display name (default).

  • :short — a shorter form when available (e.g., "Azeri" instead of "Azerbaijani"). Falls back to :standard when unavailable.

  • :long — a longer form when available (e.g., "Mandarin Chinese" instead of "Chinese"). Falls back to :standard when unavailable.

  • :menu — a menu-friendly form with the language family first (e.g., "Chinese, Mandarin" instead of "Mandarin Chinese"). Falls back to :standard when unavailable.

  • :variant — an alternative variant name (e.g., "Pushto" instead of "Pashto"). Falls back to :standard when unavailable.

Summary

Functions

available_languages(options \\ []) deprecated

Returns the list of language codes for which a locale has display names.

display_name(language, options \\ [])

Returns the localized display name for a language code.

display_name!(language, options \\ [])

Same as display_name/2 but raises on error.

known_languages(options \\ []) deprecated

Returns a map of language codes to their localized names in a locale.

language_names_for(options \\ [])

Returns a map of language codes to their localized names in a locale.

languages_for(options \\ [])

Returns a sorted list of language codes that have localized names in a locale.

Functions

available_languages(options \\ [])

This function is deprecated. Use languages_for/1 instead. This function will be removed by Localize 1.0 and no later than December 2026.. 
@spec available_languages(Keyword.t()) ::
  {:ok, [String.t()]} | {:error, Exception.t()}

Returns the list of language codes for which a locale has display names.

Deprecated — use languages_for/1 instead.

display_name(language, options \\ [])

@spec display_name(String.t() | Localize.LanguageTag.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}

Returns the localized display name for a language code.

Arguments

  • language is a language code string (e.g., "de", "en-GB") or a Localize.LanguageTag.t/0.

  • options is a keyword list of options.

Options

  • :locale is a locale identifier. The default is Localize.get_locale().

  • :style is one of :standard, :short, :long, :menu, or :variant. The default is :standard. If the requested style is not available for a language, falls back to :standard.

  • :fallback is a boolean. When true and the language is not found in the specified locale, falls back to the default locale. The default is false.

Returns

  • {:ok, name} where name is the localized language name.

  • {:error, exception} if the language code is not found in the locale.

Examples

iex> Localize.Language.display_name("de")
{:ok, "German"}

iex> Localize.Language.display_name("en-GB", style: :short)
{:ok, "UK English"}

iex> Localize.Language.display_name("en", locale: :de)
{:ok, "Englisch"}

iex> Localize.Language.display_name("pt-BR")
{:ok, "Brazilian Portuguese"}

iex> Localize.Language.display_name("ar-SA")
{:ok, "Arabic"}

iex> Localize.Language.display_name("ja")
{:ok, "Japanese"}

A bare language keeps its own name; an explicit region resolves to the region-specific name where CLDR defines one (per TR35 the display lookup canonicalizes but does not add likely subtags):

iex> Localize.Language.display_name("en")
{:ok, "English"}

iex> Localize.Language.display_name("en-US")
{:ok, "American English"}

display_name!(language, options \\ [])

@spec display_name!(String.t() | Localize.LanguageTag.t(), Keyword.t()) :: String.t()

Same as display_name/2 but raises on error.

Options

Examples

iex> Localize.Language.display_name!("de")
"German"

iex> Localize.Language.display_name!("en-GB", style: :short)
"UK English"

known_languages(options \\ [])

This function is deprecated. Use language_names_for/1 instead. This function will be removed by Localize 1.0 and no later than December 2026.. 
@spec known_languages(Keyword.t()) ::
  {:ok, %{required(String.t()) => map()}} | {:error, Exception.t()}

Returns a map of language codes to their localized names in a locale.

Deprecated — use language_names_for/1 instead.

language_names_for(options \\ [])

@spec language_names_for(Keyword.t()) ::
  {:ok, %{required(String.t()) => map()}} | {:error, Exception.t()}

Returns a map of language codes to their localized names in a locale.

Arguments

  • options is a keyword list of options.

Options

  • :locale is a locale identifier. The default is Localize.get_locale().

Returns

  • {:ok, languages_map} where languages_map is a map of %{language_code => %{standard: name, ...}}.

  • {:error, exception} if the locale data cannot be loaded.

Examples

iex> {:ok, languages} = Localize.Language.language_names_for()
iex> languages["de"]
%{standard: "German"}

iex> {:ok, languages} = Localize.Language.language_names_for(locale: :de)
iex> languages["en"]
%{standard: "Englisch"}

languages_for(options \\ [])

@spec languages_for(Keyword.t()) :: {:ok, [String.t()]} | {:error, Exception.t()}

Returns a sorted list of language codes that have localized names in a locale.

Arguments

  • options is a keyword list of options.

Options

  • :locale is a locale identifier. The default is Localize.get_locale().

Returns

  • {:ok, codes} where codes is a sorted list of language code strings.

  • {:error, exception} if the locale data cannot be loaded.

Examples

iex> {:ok, codes} = Localize.Language.languages_for()
iex> "en" in codes
true

iex> {:ok, codes} = Localize.Language.languages_for(locale: :de)
iex> "en" in codes
true