Search documentation of Localize

# Localize.Language (Localize v0.39.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 \\ [])

Returns a sorted list of language codes available in a locale.

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 \\ [])

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

## Functions

# available_languages(options \\ [])

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

Returns a sorted list of language codes available 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.available_languages()
    iex> "en" in codes
    true

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

# 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("ja")
    {:ok, "Japanese"}

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

### Examples

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

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

# known_languages(options \\ [])

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

Returns a map of all 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.known_languages()
    iex> languages["de"]
    %{standard: "German"}

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