@spec all_locale_ids() :: [atom()]

Returns a list of all known CLDR locale name atoms.

Returns

• A list of locale name atoms.

Examples

iex> locales = Localize.all_locale_ids()
iex> :en in locales
true

@spec all_locale_ids(:basic | :moderate | :modern) :: [atom()]

Returns a list of all known CLDR locale ID atoms at or above the given coverage level.

CLDR assigns each locale a coverage level of :basic, :moderate, or :modern. A locale at the :modern level is also included when requesting :moderate or :basic. A locale at :moderate is also included when requesting :basic.

Arguments

• level is one of :basic, :moderate, or :modern.

Returns

• A sorted list of locale ID atoms.

Examples

iex> locales = Localize.all_locale_ids(:modern)
iex> :en in locales
true

iex> length(Localize.all_locale_ids(:basic)) >= length(Localize.all_locale_ids(:modern))
true

@spec available_locale_id?(atom() | String.t()) :: boolean()

Returns whether a locale name is available in the CLDR repository.

Arguments

• locale_name is a locale identifier atom or string.

Returns

• true if the locale is available in CLDR.

• false otherwise.

Examples

iex> Localize.available_locale_id?(:en)
true

iex> Localize.available_locale_id?(:zzzz)
false

@spec default_locale() :: Localize.LanguageTag.t()

Returns the application-wide default locale as a Localize.LanguageTag.t/0.

The default locale is resolved once on first access using the following precedence chain:

1. A value previously set via put_default_locale/1.

2. The LOCALIZE_DEFAULT_LOCALE environment variable.

3. The :default_locale key in the :localize application environment (e.g., config :localize, default_locale: :fr).

4. The LANG environment variable (e.g., "en_US.UTF-8"), with the charset suffix stripped.

5. :en as a final fallback.

The resolved locale is validated via validate_locale/1 and cached in :persistent_term so subsequent calls are free. If any source provides an invalid locale, a warning is logged and the next source in the chain is tried.

Returns

• A Localize.LanguageTag.t/0.

Examples

iex> %Localize.LanguageTag{} = Localize.default_locale()
iex> Localize.default_locale().cldr_locale_id
:en

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

Adds locale-specific ellipsis characters to a string or between two strings.

Uses the CLDR ellipsis patterns for the given locale.

Arguments

• string is either a single string or a list of two strings to join with an ellipsis between them.

• options is a keyword list of options.

Options

• :locale is a locale identifier atom, string, or a Localize.LanguageTag.t/0. The default is :en.

• :location determines where the ellipsis is placed. Valid values are :after (append), :before (prepend), and :between (medial, requires a two-element list). The default is :after for a single string and :between for a list.

• :format is either :sentence or :word. The :word format includes a space between the text and the ellipsis. The default is :sentence.

Returns

• {:ok, ellipsized_string} with locale-specific ellipsis applied.

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

Examples

iex> Localize.ellipsis("And so on")
{:ok, "And so on…"}

iex> Localize.ellipsis("And so on", location: :before)
{:ok, "…And so on"}

iex> Localize.ellipsis(["start", "end"])
{:ok, "start…end"}

iex> Localize.ellipsis("And so on", format: :word)
{:ok, "And so on …"}

@spec get_locale() :: Localize.LanguageTag.t()

Returns the locale for the current process as a Localize.LanguageTag.t/0.

If no locale has been set for the current process via put_locale/1, returns default_locale/0.

Returns

• A Localize.LanguageTag.t/0.

Examples

iex> %Localize.LanguageTag{} = Localize.get_locale()
iex> Localize.get_locale().cldr_locale_id
:en

@spec known_calendars() :: [atom(), ...]

Returns a list of all known CLDR calendar types as atoms.

The calendar types are internal CLDR values to identify localized month and day names, era names and other calendarical data.

The calendars defined in the localzie_calendars embed the appropriate CLDR calendar type to support localization.

Returns

• A list of calendar type atoms.

Examples

iex> Localize.known_calendars()
[:gregorian, :buddhist, :chinese, :coptic, :dangi, :ethiopic,
 :ethiopic_amete_alem, :hebrew, :indian, :islamic, :islamic_civil,
 :islamic_rgsa, :islamic_tbla, :islamic_umalqura, :japanese, :persian, :roc]

@spec known_number_systems() :: [atom()]

Returns a list of all known CLDR number system atoms.

Returns

• A list of number system atoms.

Examples

iex> systems = Localize.known_number_systems()
iex> :latn in systems
true

@spec measurement_systems() :: [atom()]

Returns the list of canonical measurement system atoms.

The canonical names are derived from bcp47/measure.xml and mapped to the short forms :metric, :us, and :uk.

Returns

• A list of measurement system atoms.

Examples

iex> Localize.measurement_systems()
[:metric, :uk, :us]

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

Sets the application-wide default locale.

The locale is validated via validate_locale/1 and the resulting Localize.LanguageTag.t/0 is cached in :persistent_term. This value is used as the fallback when no process-level locale has been set via put_locale/1.

Arguments

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

Returns

• {:ok, language_tag} on success.

• {:error, exception} if the locale is not valid.

Examples

iex> {:ok, tag} = Localize.put_default_locale(:fr)
iex> tag.cldr_locale_id
:fr
iex> Localize.default_locale().cldr_locale_id
:fr
iex> {:ok, _} = Localize.put_default_locale(:en)

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

Sets the locale for the current process.

The locale is validated via validate_locale/1 and stored in the process dictionary as a Localize.LanguageTag.t/0. It is used as the default by all formatting functions in this process. It does not propagate to spawned processes — use with_locale/2 or explicitly pass the locale when spawning tasks.

Arguments

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

Returns

• {:ok, language_tag} on success. The previous locale (or nil) can be retrieved from the process dictionary before calling this function if needed.

• {:error, exception} if the locale is not valid.

Examples

iex> {:ok, _} = Localize.put_locale(:de)
iex> Localize.get_locale().cldr_locale_id
:de
iex> {:ok, _} = Localize.put_locale(:en)

@spec put_supported_locales([atom()]) :: :ok

Sets the list of supported locales in :persistent_term.

This function does not modify the application configuration. It directly updates the runtime cache that supported_locales/0 reads from.

Arguments

• locales is a list of locale ID atoms.

Returns

• :ok.

Examples

iex> original = Localize.supported_locales()
iex> Localize.put_supported_locales([:en, :fr, :de])
:ok
iex> Localize.put_supported_locales(original)
:ok

iex> original = Localize.supported_locales()
iex> Localize.put_supported_locales([:en, :fr, :de])
:ok
iex> Localize.supported_locales()
[:en, :fr, :de]
iex> Localize.put_supported_locales(original)
:ok

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

Wraps a string in locale-specific quotation marks.

Uses the CLDR delimiters data for the given locale to apply the appropriate opening and closing quotation marks.

Arguments

• string is the text to quote.

• options is a keyword list of options.

Options

• :locale is a locale identifier atom, string, or a Localize.LanguageTag.t/0. The default is :en.

• :style is either :default or :variant. The default style uses the primary quotation marks for the locale. The :variant style uses the alternate (nested) quotation marks.

Returns

• {:ok, quoted_string} where quoted_string has locale-specific quotation marks added.

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

Examples

iex> Localize.quote("Hello")
{:ok, "“Hello”"}

iex> Localize.quote("Hello", style: :variant)
{:ok, "‘Hello’"}

@spec supported_locales() :: [atom()]

Returns the list of supported locales configured via config :localize, supported_locales: [...] or Localize.all_locale_ids/0.

The returned list contains canonical CLDR locale ID atoms, resolved and validated at application startup.

Returns

• A list of locale ID atoms.

@spec to_string(term()) :: {:ok, String.t()} | {:error, Exception.t()}

Formats value as a localized string.

Delegates to Localize.Chars.to_string/1. Equivalent to calling Localize.to_string(value, []).

Built-in locale-aware implementations exist for Integer, Float, Decimal, Date, Time, DateTime, NaiveDateTime, Range, BitString, List, Localize.Unit, Localize.Duration, Localize.LanguageTag, and Localize.Currency. Any other type falls through to Kernel.to_string/1, so atoms, charlists, booleans, and nil produce the same output they would from Kernel.to_string/1. Types with no String.Chars implementation either (tuples, plain maps, PIDs, references, anonymous functions) raise Protocol.UndefinedError.

See Localize.Chars for the full list and instructions on adding implementations for your own types.

Returns

• {:ok, formatted_string} on success.

• {:error, exception} on failure.

Examples

iex> Localize.to_string(1234.5, locale: :de)
{:ok, "1.234,5"}

iex> Localize.to_string(~D[2025-07-10], locale: :en)
{:ok, "Jul 10, 2025"}

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

Formats value as a localized string with the given options.

Delegates to Localize.Chars.to_string/2. See to_string/1 for the list of supported types and the Kernel.to_string/1 shadowing note.

Arguments

• value is any term that has a Localize.Chars implementation.

• options is a keyword list of options forwarded to the underlying formatter. Every implementation accepts at least :locale.

Returns

• {:ok, formatted_string} on success.

• {:error, exception} on failure.

Examples

iex> Localize.to_string(1234.5, locale: :en)
{:ok, "1,234.5"}

iex> {:ok, unit} = Localize.Unit.new(42, "kilometer")
iex> Localize.to_string(unit, format: :short, locale: :en)
{:ok, "42 km"}

@spec to_string!(term()) :: String.t()

Same as to_string/1 but returns the formatted string directly or raises on error.

Examples

iex> Localize.to_string!(1234.5, locale: :de)
"1.234,5"

@spec to_string!(term(), Keyword.t()) :: String.t()

Same as to_string/2 but returns the formatted string directly or raises on error.

Examples

iex> Localize.to_string!(~D[2025-07-10], locale: :de, format: :long)
"10. Juli 2025"

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

Validates a calendar name.

Checks the calendar against the list of known CLDR calendars. The string "gregory" is accepted as an alias for :gregorian.

Arguments

• calendar is a calendar name atom or string.

Returns

• {:ok, calendar_atom} where calendar_atom is the normalised calendar atom.

• {:error, exception} if the calendar is not known.

Examples

iex> Localize.validate_calendar(:gregorian)
{:ok, :gregorian}

iex> Localize.validate_calendar("persian")
{:ok, :persian}

iex> Localize.validate_calendar(:unknown)
{:error, %Localize.UnknownCalendarError{calendar: :unknown}}

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

Validates a locale identifier or language tag.

Ensures that the given locale can be resolved to a known CLDR locale. When given a binary locale identifier, it is parsed into a Localize.LanguageTag.t/0. When given an existing language tag whose :cldr_locale_id is not yet populated, a best-match resolution is attempted using Localize.LanguageTag.best_match/3.

POSIX-style locale names (e.g. "pt_BR", "zh_Hans") are accepted — underscores are normalized to hyphens before parsing.

Locale resolution

The :cldr_locale_id field on the returned language tag is derived by matching the parsed tag against a list of candidate locale IDs:

• If config :localize, supported_locales: [...] is configured, the candidate list is the resolved supported locales. This restricts matching to only the locales your application explicitly supports.

• If :supported_locales is not configured, the candidate list is all CLDR locale IDs.

Validated locale results are cached in an ETS table so repeated calls with the same identifier are fast (~1µs).

Arguments

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

Returns

• {:ok, language_tag} where language_tag is a Localize.LanguageTag.t/0 with a populated :cldr_locale_id.

• {:error, Localize.InvalidLocaleError.t()} if the locale identifier cannot be parsed into a valid language tag.

• {:error, Localize.UnknownLocaleError.t()} if the locale parses successfully but does not match any known CLDR locale (or any supported locale, when configured).

Examples

iex> {:ok, tag} = Localize.validate_locale("en")
iex> tag.cldr_locale_id
:en

iex> {:ok, tag} = Localize.validate_locale("pt_BR")
iex> tag.cldr_locale_id
:pt

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

Validates a measurement system type.

Accepts canonical names (:metric, :us, :uk) as well as aliases defined in CLDR (:imperial, :ussystem, :uksystem). Aliases are resolved to the canonical short name.

Arguments

• system is a measurement system atom or string.

Returns

• {:ok, canonical_atom} where canonical_atom is the canonical measurement system atom.

• {:error, exception} if the measurement system is not known.

Examples

iex> Localize.validate_measurement_system(:metric)
{:ok, :metric}

iex> Localize.validate_measurement_system("us")
{:ok, :us}

iex> Localize.validate_measurement_system(:imperial)
{:ok, :uk}

iex> Localize.validate_measurement_system(:ussystem)
{:ok, :us}

iex> Localize.validate_measurement_system(:klingon)
{:error, %Localize.UnknownMeasurementSystemError{measurement_system: :klingon}}

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

Validates a number system name.

Checks the number system against the list of known CLDR number systems.

Arguments

• number_system is a number system name atom or string.

Returns

• {:ok, number_system_atom} where number_system_atom is the normalised number system atom.

• {:error, exception} if the number system is not known.

Examples

iex> Localize.validate_number_system(:latn)
{:ok, :latn}

iex> Localize.validate_number_system("arab")
{:ok, :arab}

iex> Localize.validate_number_system(:unknown)
{:error, %Localize.UnknownNumberSystemError{number_system: :unknown}}

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

Validates a script code.

Normalises the script code (capitalised form, e.g., "Latn") and checks it against the CLDR validity data.

Arguments

• script is a script code atom or string.

Returns

• {:ok, script_atom} where script_atom is the normalised script atom.

• {:error, exception} if the script is not known.

Examples

iex> Localize.validate_script(:Latn)
{:ok, :Latn}

iex> Localize.validate_script("latn")
{:ok, :Latn}

iex> Localize.validate_script(:Xyzq)
{:error, %Localize.UnknownScriptError{script: :Xyzq}}

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

Validates a territory code.

Normalises the territory code and checks it against the CLDR validity data. Integer codes are zero-padded (e.g., 1 becomes "001"). String codes are uppercased.

Arguments

• territory is a territory code atom, string, or integer.

Returns

• {:ok, territory_atom} where territory_atom is the normalised territory atom.

• {:error, exception} if the territory is not known.

Examples

iex> Localize.validate_territory(:US)
{:ok, :US}

iex> Localize.validate_territory("us")
{:ok, :US}

iex> Localize.validate_territory(:ZZZZ)
{:error, %Localize.UnknownTerritoryError{territory: :ZZZZ}}

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

Validates a territory subdivision code.

Normalises the subdivision code (lowercased) and checks it against the CLDR validity data.

Arguments

• subdivision is a subdivision code atom or string.

Returns

• {:ok, subdivision_atom} where subdivision_atom is the normalised subdivision atom.

• {:error, exception} if the subdivision is not known.

Examples

iex> Localize.validate_territory_subdivision(:usca)
{:ok, :usca}

iex> Localize.validate_territory_subdivision("gbeng")
{:ok, :gbeng}

iex> Localize.validate_territory_subdivision(:zzzzz)
{:error, %Localize.UnknownSubdivisionError{subdivision: :zzzzz}}

@spec version() :: Version.t()

Returns the CLDR version this build of Localize targets.

The version is a Version.t/0 whose major and minor components come from priv/localize/version (the CLDR release version) and whose patch component comes from priv/localize/localize_patch_version (Localize's per-release patch counter).

The value is read once on first access and cached in :persistent_term.

Returns

• A Version.t/0 representing the CLDR version.

Examples

iex> %Version{} = Localize.version()

@spec with_locale(Localize.LanguageTag.t() | atom() | String.t(), (-> result)) ::
  result
when result: any()

Executes a function with a temporary process locale.

Sets the process locale to locale, executes fun, then restores the previous locale regardless of whether fun raises or throws.

Arguments

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

• fun is a zero-arity function to execute.

Returns

• The return value of fun.

• Raises if the locale is not valid.

Examples

iex> Localize.with_locale(:ja, fn -> Localize.get_locale().cldr_locale_id end)
:ja

iex> Localize.get_locale().cldr_locale_id
:en