Search documentation of Localize

# Localize.Script (Localize v0.39.0)

Copy Markdown View Source

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

Script display names are loaded on demand from the locale data provider. Each locale provides localized names for script codes in one or more styles.

## Styles

Script display names come in several styles:

- `:standard` — the default form, suitable for combining with a language name in a locale pattern (e.g., "Simplified").

- `:short` — a shorter form when available (e.g., "UCAS" instead of "Unified Canadian Aboriginal Syllabics"). Falls back to `:standard` when unavailable.

- `:stand_alone` — a stand-alone form when the script name differs from its combined form (e.g., "Simplified Han" instead of "Simplified"). Falls back to `:standard` when unavailable.

- `:variant` — an alternative variant name (e.g., "Perso-Arabic" instead of "Arabic"). Falls back to `:standard` when unavailable.

## Summary

### Functions

available_scripts(options \\ [])

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

display_name(script, options \\ [])

Returns the localized display name for a script code.

display_name!(script, options \\ [])

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

known_scripts(options \\ [])

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

## Functions

# available_scripts(options \\ [])

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

Returns a sorted list of script 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 script code atoms.

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

### Examples

    iex> {:ok, codes} = Localize.Script.available_scripts()
    iex> :Latn in codes
    true

# display_name(script, options \\ [])

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

Returns the localized display name for a script code.

### Arguments

- `script` is a script code atom or string (e.g., `:Latn`, `"Cyrl"`).

- `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`, `:stand_alone`, or `:variant`. The default is `:standard`. If the requested style is not available for a script, falls back to `:standard`.

- `:fallback` is a boolean. When `true` and the script 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 script name.

- `{:error, exception}` if the script code is not found in the locale.

### Examples

    iex> Localize.Script.display_name(:Latn)
    {:ok, "Latin"}

    iex> Localize.Script.display_name("Cyrl")
    {:ok, "Cyrillic"}

    iex> Localize.Script.display_name(:Hans, style: :stand_alone)
    {:ok, "Simplified Han"}

    iex> Localize.Script.display_name(:Arab, style: :variant)
    {:ok, "Perso-Arabic"}

# display_name!(script, options \\ [])

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

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

### Examples

    iex> Localize.Script.display_name!(:Latn)
    "Latin"

    iex> Localize.Script.display_name!(:Hans, style: :stand_alone)
    "Simplified Han"

# known_scripts(options \\ [])

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

Returns a map of all script 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, scripts_map}` where `scripts_map` is a map of `%{script_atom => %{standard: name, ...}}`.

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

### Examples

    iex> {:ok, scripts} = Localize.Script.known_scripts()
    iex> scripts[:Latn]
    %{standard: "Latin"}