@spec default_provider() :: module()

Returns the default locale data provider module.

Returns

• The module implementing Localize.Locale.Provider.

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

Returns the localized display name for a locale identifier.

Formats a locale identifier or language tag into a human-readable display name using the CLDR locale display name algorithm (e.g., "en-AU" → "English (Australia)").

Arguments

• locale is a locale identifier string, atom, or a Localize.LanguageTag.t/0.

• options is a keyword list of options.

Options

• :locale is the locale to use for formatting. The default is Localize.get_locale().

• :prefer is :standard or :short. The default is :standard.

Returns

• {:ok, name} where name is the localized display name.

• {:error, exception} if the locale cannot be resolved.

Examples

iex> Localize.Locale.display_name("en-AU")
{:ok, "English (Australia)"}

iex> Localize.Locale.display_name("zh-Hant")
{:ok, "Chinese (Traditional)"}

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

Same as display_name/2 but raises on error.

Examples

iex> Localize.Locale.display_name!("en-AU")
"English (Australia)"

@spec expand_locale_list([atom() | String.t()], atom() | String.t()) :: [atom()]

Expands a list of locale identifiers (atoms and wildcard strings) into a list of known CLDR locale ID atoms.

Each entry is either an atom matching a known CLDR locale (e.g. :en, :"fr-CA") or a string with a trailing * wildcard (e.g. "en-*") that expands to all matching locales.

Invalid entries log a warning and are skipped.

Arguments

• entries is a list of atoms and/or strings.

• context is an atom or string used in warning messages to identify where the entry came from (e.g. :supported_locales).

Returns

• A deduplicated list of locale ID atoms.

@spec get(Localize.Locale.Provider.locale(), list(), Keyword.t()) ::
  {:ok, term()} | {:error, term()}

Retrieves a value from locale data by following a list of access keys.

Delegates to the configured provider module to navigate the locale data map.

Arguments

• locale is a locale identifier atom or a Localize.LanguageTag.t/0.

• keys is a list of keys to traverse in the locale data map.

• options is a keyword list of options. The default is [].

Options

• :provider is the module implementing Localize.Locale.Provider to use. The default is default_provider/0.

• :fallback is a boolean. When true, if the requested key path is not found in the given locale, parent locales are searched according to the CLDR locale inheritance chain. The default is false.

Returns

• {:ok, value} if the key path resolves to a value.

• {:error, reason} if the key path cannot be resolved.

@spec gettext_locale_id(Localize.LanguageTag.t() | atom() | String.t(), module()) ::
  {:ok, String.t()} | {:error, Exception.t()}

Returns the best-matching Gettext locale for a given locale identifier.

Compares the given locale against the locales known to a Gettext backend using Localize.LanguageTag.best_match/3. This allows a CLDR locale like :"en-AU" to match a Gettext locale like "en" when no exact match exists.

Arguments

• locale is a locale identifier atom, string, or a Localize.LanguageTag.t/0.

• gettext_backend is a module that uses Gettext (e.g., MyApp.Gettext). It must respond to Gettext.known_locales/1.

Returns

• {:ok, gettext_locale} where gettext_locale is a string from the Gettext backend's known locales.

• {:error, exception} if no match is found among the backend's known locales.

Examples

iex> Localize.Locale.gettext_locale_id(:en, Localize.Gettext)
{:error,
 %Localize.UnknownLocaleError{
   locale_id: "en"
 }}

@spec load(Localize.Locale.Provider.locale(), Keyword.t()) ::
  {:ok, map()} | {:error, Exception.t()}

Loads locale data for the given locale.

Delegates to the configured provider module to find and retrieve locale data.

Arguments

• locale is a locale identifier atom or a Localize.LanguageTag.t/0.

• options is a keyword list of options. The default is [].

Options

• :provider is the module implementing Localize.Locale.Provider to use. The default is default_provider/0.

Returns

• {:ok, locale_data} where locale_data is a map of the locale's CLDR data.

• {:error, Localize.UnknownLocaleError.t()} if the locale is not recognized.

@spec load_and_store(Localize.Locale.Provider.locale(), Keyword.t()) ::
  :ok | {:error, Exception.t()}

Loads and stores locale data if it has not already been loaded.

This is a convenience function that checks whether the locale data is already available and, if not, delegates to the configured provider to load and store it. Subsequent calls for the same locale are no-ops.

Arguments

• locale is a locale identifier atom or a Localize.LanguageTag.t/0.

• options is a keyword list of options. The default is [].

Options

• :provider is the module implementing Localize.Locale.Provider to use. The default is default_provider/0.

Returns

• :ok if the locale data is already loaded or was successfully loaded and stored.

• {:error, Localize.UnknownLocaleError.t()} if the locale data could not be loaded.

@spec loaded?(Localize.Locale.Provider.locale(), Keyword.t()) :: boolean()

Returns whether locale data has been loaded and is available.

Delegates to the configured provider module to check availability.

Arguments

• locale is a locale identifier atom or a Localize.LanguageTag.t/0.

• options is a keyword list of options. The default is [].

Options

• :provider is the module implementing Localize.Locale.Provider to use. The default is default_provider/0.

Returns

• true if the locale data has been loaded and stored.

• false otherwise.

@spec locale_id_from(language(), script(), territory(), [String.t()]) :: String.t()

Build a locale identifier string from its component parts.

Assembles a BCP 47 locale identifier from language, script, territory, and variant subtags, omitting nil components.

Arguments

• language is a language subtag (string or atom).

• script is an optional script subtag (string, atom, or nil).

• territory is an optional territory subtag (string, atom, or nil).

• variants is a list of variant subtag strings.

Returns

• A BCP 47 locale identifier string.

Examples

iex> Localize.Locale.locale_id_from(:en, nil, :US, [])
"en-US"

iex> Localize.Locale.locale_id_from(:zh, :Hant, :TW, [])
"zh-Hant-TW"

iex> Localize.Locale.locale_id_from(:en, nil, nil, [])
"en"

@spec locale_id_from_posix(String.t()) :: String.t()

Convert a POSIX locale identifier to a BCP 47 locale identifier by replacing underscores with hyphens.

Arguments

• locale_id is a string locale identifier, potentially in POSIX format using underscores.

Returns

• A string with underscores replaced by hyphens.

Examples

iex> Localize.Locale.locale_id_from_posix("en_US")
"en-US"

iex> Localize.Locale.locale_id_from_posix("zh_Hant_TW")
"zh-Hant-TW"

iex> Localize.Locale.locale_id_from_posix("en")
"en"

@spec parent(Localize.LanguageTag.t() | String.t()) ::
  {:ok, Localize.LanguageTag.t()} | {:error, Exception.t()}

Return the parent locale of the given language tag.

Implements the CLDR locale ID inheritance algorithm (bundle inheritance) from Unicode TR35. The parent locale is determined by first checking the CLDR parentLocales supplemental data for an explicit override, then falling back to progressive subtag removal.

Extensions (-u- and -t-) are transferred from the child to the parent so that calendar, numbering system, and other preferences are preserved across the inheritance chain.

Arguments

• locale is a %Localize.LanguageTag{} struct or a BCP 47 locale identifier string.

Returns

• {:ok, parent_tag} where parent_tag is a %Localize.LanguageTag{} struct representing the parent locale.

• {:error, Localize.NoParentError.exception(locale: locale)} if the locale is the root locale (und) which has no parent.

Examples

iex> {:ok, parent} = Localize.Locale.parent("en-AU")
iex> parent.language
:en
iex> parent.territory
:"001"

iex> {:ok, parent} = Localize.Locale.parent("en")
iex> parent.language
:und

@spec store(locale_id(), map(), Keyword.t()) :: :ok | {:error, term()}

Stores locale data in the provider's backing store.

Delegates to the configured provider module to persist locale data.

Arguments

• locale_id is a locale identifier atom.

• locale_data is a map of locale data to store.

• options is a keyword list of options. The default is [].

Options

• :provider is the module implementing Localize.Locale.Provider to use. The default is default_provider/0.

Returns

• :ok on success.

• {:error, reason} on failure.

@spec to_locale_id(Localize.LanguageTag.t() | atom() | String.t()) :: atom()

Coerces a locale identifier to an atom.

Accepts a Localize.LanguageTag.t/0, an atom, or a binary string and returns the corresponding locale identifier atom.

When given a Localize.LanguageTag with a populated :cldr_locale_id, that value is returned directly. When the :cldr_locale_id is nil, the tag is serialised to a string and converted to an atom.

Arguments

• locale is a Localize.LanguageTag.t/0, an atom, or a binary string.

Returns

• A locale identifier atom.

Examples

iex> Localize.Locale.to_locale_id(:en)
:en

iex> Localize.Locale.to_locale_id("en")
:en