# `Localize.Language`
[🔗](https://github.com/elixir-localize/localize/blob/v0.48.0/lib/localize/language.ex#L1)

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.

# `available_languages`

> This function is deprecated. Use languages_for/1 instead. This function will be removed by Localize 1.0 and no later than December 2026..

```elixir
@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`

```elixir
@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 `t: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!`

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

Same as `display_name/2` but raises on error.

### Options

* See `display_name/2` for the supported options.

### Examples

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

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

# `known_languages`

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

```elixir
@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`

```elixir
@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`

```elixir
@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

---

*Consult [api-reference.md](api-reference.md) for complete listing*