Localize.Script (Localize v0.6.0)

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"}