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

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.

# `available_scripts`

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

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

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

Deprecated — use `scripts_for/1` instead.

# `display_name`

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

```elixir
@spec display_name!(atom() | String.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.Script.display_name!(:Latn)
    "Latin"

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

# `known_scripts`

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

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

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

Deprecated — use `script_names_for/1` instead.

# `script_names_for`

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

Returns a map of 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.script_names_for()
    iex> scripts[:Latn]
    %{standard: "Latin"}

# `scripts_for`

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

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

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

### Examples

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

---

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