# Localize v0.5.0 - Table of Contents

Localization (parsing, formatting) of numbers, dates/time/calendar, units of measure, messages and lists. Includes localized collation.

## Pages

- [Localize](readme.md)
- [License](license.md)
- [Changelog](changelog.md)

- Guides
  - [Collation Guide](collation-1.md)
  - [Date and Time Formatting Guide](date_time_formatting-2.md)
  - [MessageFormat 2 Guide](message_formatting.md)
  - [Number Formatting Guide](number_formatting-3.md)
  - [Unit of Measure Formatting Guide](unit_formatting-4.md)

- Advanced
  - [Architecture](architecture.md)
  - [TR35 Conformance](conformance.md)
  - [Performance Guide](performance.md)

- Migration from ex_cldr
  - [Migrating from ex_cldr to Localize](migration.md)
  - [Performance Comparison: Localize vs ex_cldr](performance_comparison.md)

- Cheatsheets
  - [Collation Cheatsheet](collation-5.md)
  - [Date, Time & DateTime Formatting Cheatsheet](date_time_formatting-6.md)
  - [Number Formatting & Parsing Cheatsheet](number_formatting-7.md)
  - [Unit Formatting Cheatsheet](unit_formatting-8.md)

## Modules

- [Localize](Localize.md): Locale-aware formatting, validation, and data access built on the
Unicode CLDR repository.
- [Localize.DataLoader](Localize.DataLoader.md): A GenServer that serializes ETF data file loading to prevent
race conditions.
- [Localize.FormatCache](Localize.FormatCache.md): An ETS-backed cache for compiled format patterns.
- [Localize.Substitution](Localize.Substitution.md): Compiles substitution templates of the form `"{0} something {1}"`
into token lists for efficient parameter substitution at runtime.

- Protocols
  - [Localize.Chars](Localize.Chars.md): Protocol for locale-aware string formatting.

- Numbers
  - [Localize.Number](Localize.Number.md): Functions for formatting numbers in a locale-aware manner.
  - [Localize.Number.Format](Localize.Number.Format.md): Functions to manage the collection of number format patterns
defined in CLDR.
  - [Localize.Number.Format.Compiler](Localize.Number.Format.Compiler.md): Compiles number format patterns into metadata for fast runtime
interpretation.
  - [Localize.Number.Format.Meta](Localize.Number.Format.Meta.md): Describes the metadata that drives number formatting and
provides functions to update the struct.
  - [Localize.Number.Formatter.Ratio](Localize.Number.Formatter.Ratio.md): Formats numbers as rational fractions using CLDR rational format patterns.
  - [Localize.Number.Parser](Localize.Number.Parser.md): Functions for parsing numbers and currencies from strings
in a locale-aware manner.
  - [Localize.Number.PluralRule](Localize.Number.PluralRule.md): Defines plural rule modules for cardinal and ordinal number
categories according to the CLDR plural rules specification.
  - [Localize.Number.PluralRule.Cardinal](Localize.Number.PluralRule.Cardinal.md): Implements cardinal plural rules for numbers.
  - [Localize.Number.PluralRule.Ordinal](Localize.Number.PluralRule.Ordinal.md): Implements ordinal plural rules for numbers.
  - [Localize.Number.Rbnf](Localize.Number.Rbnf.md): Rules-Based Number Formatting (RBNF) for algorithmic number
systems and spellout forms.
  - [Localize.Number.Symbol](Localize.Number.Symbol.md): Functions to manage the number symbol definitions for a locale
and number system.
  - [Localize.Number.System](Localize.Number.System.md): Functions to manage number systems for a locale.
  - [Localize.Number.Transliterate](Localize.Number.Transliterate.md): Functions to transliterate digits between number systems.

- Dates and Times
  - [Localize.Date](Localize.Date.md): Provides localized formatting of `Date` structs and date-like maps.
  - [Localize.DateTime](Localize.DateTime.md): Provides localized formatting of `DateTime`, `NaiveDateTime`,
and datetime-like maps.
  - [Localize.DateTime.Relative](Localize.DateTime.Relative.md): Formats relative time strings such as "3 days ago", "tomorrow",
or "in 10 seconds".
  - [Localize.DateTime.Timezone](Localize.DateTime.Timezone.md): Provides timezone data access and timezone formatting for CLDR
date/time format symbols.
  - [Localize.Duration](Localize.Duration.md): Functions to create and format durations — the difference
between two dates, times, or datetimes expressed in calendar
units.
  - [Localize.Interval](Localize.Interval.md): Formats date and time intervals as localized strings.
  - [Localize.Time](Localize.Time.md): Provides localized formatting of `Time` structs and time-like maps.

- Locale
  - [Localize.Locale](Localize.Locale.md): Locale utility functions for resolution, validation, and
per-locale data access.
  - [Localize.Locale.Loader](Localize.Locale.Loader.md): A GenServer that serializes locale data loading to prevent
race conditions.
  - [Localize.Locale.LocaleDisplay](Localize.Locale.LocaleDisplay.md): Implements the CLDR locale display name algorithm to format
locale identifiers for presentation.
  - [Localize.Locale.Provider](Localize.Locale.Provider.md): Defines the behaviour for locale data providers.
  - [Localize.Locale.Provider.Cache](Localize.Locale.Provider.Cache.md): On-disk cache for downloaded locale data files.
  - [Localize.Locale.Provider.PersistentTerm](Localize.Locale.Provider.PersistentTerm.md): A locale data provider that stores locale data in `:persistent_term`.

- Language Tag
  - [Localize.LanguageTag](Localize.LanguageTag.md): Represents a language tag as defined in [rfc5646](https://tools.ietf.org/html/rfc5646)
with extensions "u" and "t" as defined in [BCP 47](https://tools.ietf.org/html/bcp47).
  - [Localize.LanguageTag.Parser](Localize.LanguageTag.Parser.md): Parses a CLDR language tag (also referred to as locale string).
  - [Localize.LanguageTag.Sigil](Localize.LanguageTag.Sigil.md): Implements a `sigil_l/2` macro for
constructing `t:Localize.LanguageTag` structs.
  - [Localize.LanguageTag.T](Localize.LanguageTag.T.md): Defines the struct for the BCP 47 `t`
extension.
  - [Localize.LanguageTag.U](Localize.LanguageTag.U.md): Defines the struct for the BCP 47 `u`
extension.
  - [Localize.Rfc5646.Parser](Localize.Rfc5646.Parser.md): Implements parsing for [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646) language
tags with [BCP47](https://tools.ietf.org/search/bcp47) extensions.

- Calendars
  - [Localize.Calendar](Localize.Calendar.md): Calendar localization functions for retrieving locale-specific
names for eras, months, days, quarters, and day periods.

- Currencies
  - [Localize.Currency](Localize.Currency.md): Defines a currency structure and functions to manage currency
codes, validate currencies, and retrieve currency metadata.

- Languages
  - [Localize.Language](Localize.Language.md): Provides language name localization functions built on the
Unicode CLDR repository.

- Territories
  - [Localize.Territory](Localize.Territory.md): Provides territory and subdivision localization functions
built on the Unicode CLDR repository.

- Scripts
  - [Localize.Script](Localize.Script.md): Provides script name localization functions built on the
Unicode CLDR repository.

- Units of Measure
  - [Localize.Unit](Localize.Unit.md): Represents and formats CLDR units of measure.
  - [Localize.Unit.BaseUnit](Localize.Unit.BaseUnit.md): Converts parsed unit ASTs into their CLDR base unit equivalents.
  - [Localize.Unit.Canonical](Localize.Unit.Canonical.md): Canonicalises CLDR unit identifier ASTs and names.
  - [Localize.Unit.Conversion](Localize.Unit.Conversion.md): Converts numeric values between CLDR units of measure.
  - [Localize.Unit.Conversion.Beaufort](Localize.Unit.Conversion.Beaufort.md): Nonlinear conversion between the Beaufort wind force scale and
meters per second.
  - [Localize.Unit.CustomRegistry](Localize.Unit.CustomRegistry.md): Runtime registry for user-defined units backed by `:persistent_term`.
  - [Localize.Unit.Data](Localize.Unit.Data.md): Compile-time extraction of CLDR unit data from a pre-built ETF file.
  - [Localize.Unit.Math](Localize.Unit.Math.md): Arithmetic operations on `Localize.Unit` structs.
  - [Localize.Unit.Operators](Localize.Unit.Operators.md): Overloaded arithmetic operators for `Localize.Unit.t()` values.
  - [Localize.Unit.Parser](Localize.Unit.Parser.md): Parses CLDR Unit of Measure identifier strings into structured ASTs.
  - [Localize.Unit.Preference](Localize.Unit.Preference.md): Returns the preferred units for a given unit, territory, and usage.

- Messages
  - [Localize.Message](Localize.Message.md): Implements [ICU MessageFormat 2](https://unicode.org/reports/tr35/tr35-messageFormat.html)
with functions to parse and interpolate messages.
  - [Localize.Message.Function](Localize.Message.Function.md): Behaviour for custom MF2 formatting functions.
  - [Localize.Message.Interpreter](Localize.Message.Interpreter.md): Interprets a MessageFormat 2 AST and produces formatted output.
  - [Localize.Message.JSON](Localize.Message.JSON.md): Converts between MF2 ASTs and the JSON interchange data model
defined in [TR35 §8](https://www.unicode.org/reports/tr35/tr35-messageFormat.html).
  - [Localize.Message.Parser](Localize.Message.Parser.md): Implements a parser for
[ICU MessageFormat 2](https://unicode.org/reports/tr35/tr35-messageFormat.html).
  - [Localize.Message.Print](Localize.Message.Print.md): Converts a MessageFormat 2 AST back to its canonical string form.
  - [Localize.Message.Sigil](Localize.Message.Sigil.md): Implements sigil `~M` to canonicalize an ICU message.

- Gettext
  - [Localize.Gettext](Localize.Gettext.md): Gettext backend for the Localize library.
  - [Localize.Gettext.Interpolation](Localize.Gettext.Interpolation.md): Gettext interpolation module for ICU MessageFormat 2 (MF2) messages.

- Lists
  - [Localize.List](Localize.List.md): Formats lists into locale-aware strings using CLDR list
formatting patterns.
  - [Localize.List.Pattern](Localize.List.Pattern.md): Defines the structure for list formatting patterns.

- Collation
  - [Localize.Collation](Localize.Collation.md): Implements the Unicode Collation Algorithm (UCA) as extended by CLDR.
  - [Localize.Collation.Element](Localize.Collation.Element.md): A Collation Element (CE) with primary, secondary, and tertiary weights.
  - [Localize.Collation.FastLatin](Localize.Collation.FastLatin.md): Fast lookup table for Basic Latin and Latin Extended-A codepoints.
  - [Localize.Collation.Han](Localize.Collation.Han.md): Han character ordering using radical-stroke indexes.
  - [Localize.Collation.ImplicitWeights](Localize.Collation.ImplicitWeights.md): Computes implicit collation elements for codepoints not in the DUCET/CLDR allkeys table.
  - [Localize.Collation.Insensitive](Localize.Collation.Insensitive.md): Case-insensitive string comparator for use with `Enum.sort/2`.
  - [Localize.Collation.Nif](Localize.Collation.Nif.md): Collation NIF interface providing high-performance Unicode collation via ICU4C.
  - [Localize.Collation.Normalizer](Localize.Collation.Normalizer.md): Unicode NFD normalization for collation.
Delegates to Erlang's `:unicode` module.
  - [Localize.Collation.Numeric](Localize.Collation.Numeric.md): Numeric collation support (kn=true / numeric=true).
  - [Localize.Collation.Options](Localize.Collation.Options.md): Collation options corresponding to BCP47 -u- extension keys.
  - [Localize.Collation.Reorder](Localize.Collation.Reorder.md): Script reordering for collation (kr= / reorder option).
  - [Localize.Collation.Sensitive](Localize.Collation.Sensitive.md): Case-sensitive string comparator for use with `Enum.sort/2`.
  - [Localize.Collation.SortKey](Localize.Collation.SortKey.md): Constructs binary sort keys from processed collation elements.
  - [Localize.Collation.Table](Localize.Collation.Table.md): Persistent-term-backed collation element table.
  - [Localize.Collation.Table.Parser](Localize.Collation.Table.Parser.md): Parses the FractionalUCA.txt file into a map of codepoint sequences to collation elements.
  - [Localize.Collation.Tailoring](Localize.Collation.Tailoring.md): CLDR locale-specific collation tailoring.
  - [Localize.Collation.Tailoring.LocaleDefaults](Localize.Collation.Tailoring.LocaleDefaults.md): Preset collation option defaults for common locales.
  - [Localize.Collation.Variable](Localize.Collation.Variable.md): Variable weight handling for the collation algorithm.

- Utilities
  - [Localize.Utils](Localize.Utils.md): Utility functions and namespace for Localize utility submodules.
  - [Localize.Utils.Decimal](Localize.Utils.Decimal.md): Compatibility layer for `Decimal` library operations.
  - [Localize.Utils.Digits](Localize.Utils.Digits.md): Abstract representation of number (integer, float, Decimal) in tuple form
and functions for transformations on number parts.
  - [Localize.Utils.Enum](Localize.Utils.Enum.md): Enumerable utility functions not provided in the standard library.
  - [Localize.Utils.Helpers](Localize.Utils.Helpers.md): General purpose helper functions for Localize.
  - [Localize.Utils.Http](Localize.Utils.Http.md): Supports securely downloading HTTPS content.
  - [Localize.Utils.Json](Localize.Utils.Json.md): JSON decoding utilities wrapping the OTP `:json` module.
  - [Localize.Utils.Map](Localize.Utils.Map.md): Functions for transforming maps, keys and values.
  - [Localize.Utils.Math](Localize.Utils.Math.md): Mathematical helper functions for number formatting and
Localize subsystems.
  - [Localize.Utils.String](Localize.Utils.String.md): String manipulation functions not provided in the standard library.

- NIF
  - [Localize.Nif](Localize.Nif.md): Optional NIF interface to ICU4C for high-performance locale operations.

- Exceptions
  - [Localize.BindError](Localize.BindError.md): Exception raised when interpreting a message and one or more
variable bindings are missing.
  - [Localize.CurrencyNoDisplayNameError](Localize.CurrencyNoDisplayNameError.md): Exception raised when a currency has no display name
available for the requested locale.
  - [Localize.DateTimeFormatError](Localize.DateTimeFormatError.md): Exception raised when a date, time, or datetime format
pattern cannot be processed.
  - [Localize.DateTimeIntervalFormatError](Localize.DateTimeIntervalFormatError.md): Exception raised when an interval format cannot be resolved.
  - [Localize.DateTimeInvalidInputError](Localize.DateTimeInvalidInputError.md): Exception raised when a date, time, or datetime value does not
have the required keys for formatting.
  - [Localize.DateTimeUnresolvedFormatError](Localize.DateTimeUnresolvedFormatError.md): Exception raised when a date, time, or datetime format
skeleton cannot be resolved to a pattern for the given locale.
  - [Localize.FormatError](Localize.FormatError.md): Exception raised when a value cannot be formatted by the requested
message format function due to an incompatible type or missing
configuration.
  - [Localize.InvalidLocaleError](Localize.InvalidLocaleError.md): Exception raised when a locale identifier cannot be parsed
into a valid language tag.
  - [Localize.InvalidSubtagError](Localize.InvalidSubtagError.md): Exception raised when an extension key or value is not valid
for a BCP 47 language tag.
  - [Localize.InvalidValueError](Localize.InvalidValueError.md): Exception raised when a value does not meet the expected type
or constraints for an operation.
  - [Localize.ItemNotFoundError](Localize.ItemNotFoundError.md): Exception raised when a key path cannot be resolved in
locale data.
  - [Localize.LikelySubtagsError](Localize.LikelySubtagsError.md): Exception raised when likely subtags data cannot be found
for a given locale identifier.
  - [Localize.LocaleCacheWriteError](Localize.LocaleCacheWriteError.md): Exception raised when a locale file cannot be written to the
locale cache directory.
  - [Localize.LocaleDisplayError](Localize.LocaleDisplayError.md): Exception raised when locale display name data is not
available for a requested locale.
  - [Localize.LocaleDownloadError](Localize.LocaleDownloadError.md): Exception raised when a locale file cannot be downloaded from
its remote URL.
  - [Localize.LocaleIsStaleError](Localize.LocaleIsStaleError.md): Exception raised when a cached locale file's version does not
match the current `Localize.version/0`.
  - [Localize.LocaleMatchError](Localize.LocaleMatchError.md): Exception raised when no matching locale can be found
within the specified distance threshold.
  - [Localize.LocaleNotFoundInCacheError](Localize.LocaleNotFoundInCacheError.md): Exception raised when a locale file is not found in the locale
cache directory.
  - [Localize.NoParentError](Localize.NoParentError.md): Exception raised when a parent locale is requested for the
root locale (`und`) which has no parent.
  - [Localize.NoParentTerritoryError](Localize.NoParentTerritoryError.md): Exception raised when a territory has no parent container
in the CLDR territory containment data.
  - [Localize.ParseError](Localize.ParseError.md): Exception raised when a language tag or unit identifier cannot be parsed.
  - [Localize.UnitConversionError](Localize.UnitConversionError.md): Exception raised when a unit conversion cannot be performed.
  - [Localize.UnitNoValueError](Localize.UnitNoValueError.md): Exception raised when a unit operation requires a numeric value
but the unit struct has `nil` as its value.
  - [Localize.UnitPreferenceError](Localize.UnitPreferenceError.md): Exception raised when a unit preference cannot be determined
for a given unit, region, or usage combination.
  - [Localize.UnknownCalendarError](Localize.UnknownCalendarError.md): Exception raised when a calendar name is not a known
CLDR calendar type.
  - [Localize.UnknownCurrencyError](Localize.UnknownCurrencyError.md): Exception raised when a currency code is not a known
ISO 4217 or registered custom currency.
  - [Localize.UnknownLanguageError](Localize.UnknownLanguageError.md): Exception raised when a language code cannot be found in
the locale display name data.
  - [Localize.UnknownLocaleError](Localize.UnknownLocaleError.md): Exception raised when a locale identifier does not correspond
to any known CLDR locale.
  - [Localize.UnknownMeasurementSystemError](Localize.UnknownMeasurementSystemError.md): Exception raised when a measurement system type is not a
known CLDR measurement system.
  - [Localize.UnknownNumberSystemError](Localize.UnknownNumberSystemError.md): Exception raised when a number system name is not a known
CLDR number system.
  - [Localize.UnknownPluralRulesError](Localize.UnknownPluralRulesError.md): Exception raised when no plural rules are available for
a given locale.
  - [Localize.UnknownScriptError](Localize.UnknownScriptError.md): Exception raised when a script code is not a known
ISO 15924 or CLDR script subtag.
  - [Localize.UnknownStyleError](Localize.UnknownStyleError.md): Exception raised when a display name style is not one of
the known styles (`:short`, `:standard`, `:variant`).
  - [Localize.UnknownSubdivisionError](Localize.UnknownSubdivisionError.md): Exception raised when a territory subdivision code is
not a known ISO 3166-2 subdivision.
  - [Localize.UnknownTerritoryError](Localize.UnknownTerritoryError.md): Exception raised when a territory code is not a known
ISO 3166 territory or CLDR region code.
  - [Localize.UnknownTimezoneError](Localize.UnknownTimezoneError.md): Exception raised when a timezone identifier cannot be resolved
to a known IANA timezone.
  - [Localize.UnknownUnitError](Localize.UnknownUnitError.md): Exception raised when a unit identifier cannot be resolved
to a known CLDR unit.

## Mix Tasks

- [mix localize.download_locales](Mix.Tasks.Localize.DownloadLocales.md): Downloads locale ETF files from the Localize CDN and stores
them in the configured locale cache directory.