@spec add_likely_subtags(t()) :: {:ok, t()} | {:error, Exception.t()}

Add likely subtags to a language tag.

Implements the Add Likely Subtags algorithm from Unicode TR35. This fills in missing script and region subtags with the most likely values from the CLDR likely subtags data.

Arguments

• language_tag is a %Localize.LanguageTag{} struct.

Returns

• {:ok, maximized_tag} with all subtags filled in and canonical_locale_id updated, or

• {:error, reason} if no likely subtags data is found.

Examples

iex> {:ok, tag} = Localize.LanguageTag.parse("en")
iex> {:ok, max} = Localize.LanguageTag.add_likely_subtags(tag)
iex> max.canonical_locale_id
"en-Latn-US"

iex> {:ok, tag} = Localize.LanguageTag.parse("zh-TW")
iex> {:ok, max} = Localize.LanguageTag.add_likely_subtags(tag)
iex> max.canonical_locale_id
"zh-Hant-TW"

@spec add_likely_subtags!(t()) :: t() | no_return()

Add likely subtags to a language tag, raising on error.

Same as add_likely_subtags/1 but returns the struct directly or raises an exception.

@spec best_match(
  t() | String.t() | atom(),
  [t() | String.t() | atom()],
  non_neg_integer()
) ::
  {:ok, t() | String.t() | atom(), non_neg_integer()} | {:error, String.t()}

Find the best matching supported locale for a desired locale.

Implements the CLDR Language Matching algorithm. The desired locale is compared against each supported locale and the closest match (lowest distance score) is returned.

Arguments

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

• supported is a list of %Localize.LanguageTag{} structs or BCP 47 locale strings.

• distance is the maximum acceptable distance score. Matches with a score above this threshold are rejected. The default is 80.

Returns

• {:ok, matched_locale, score} where matched_locale is the best supported match and score is the numeric distance.

• {:error, reason} if no match is found within the threshold.

Fallback behaviour

When using the default threshold (80), the CLDR algorithm always returns a result when the supported list is non-empty — even if the best match is very distant. This matches the CLDR specification, which says the algorithm should always select a locale rather than fail. The first supported locale is returned as a last resort.

When an explicit threshold below the default is provided, no fallback occurs. If nothing matches within the threshold, an error is returned. This is useful for strict validation (e.g. resolving configuration values) where a distant match would be surprising.

Examples

iex> {:ok, match, _score} = Localize.LanguageTag.best_match("en-AU", ["en", "en-GB", "fr"])
iex> match
"en-GB"

iex> # Strict matching: threshold 0 rejects non-exact matches
iex> {:error, _} = Localize.LanguageTag.best_match("xyzzy", ["en", "fr"], 0)

@spec canonicalize(t()) :: {:ok, t()} | {:error, term()}

Canonicalize a parsed language tag.

Takes a %Localize.LanguageTag{} struct (typically returned by parse/1) and applies canonical syntax rules:

• Sorts variants alphabetically.

• Canonicalizes the -u- and -t- extension keys.

• Sorts extensions by their singleton letter.

• Computes and stores the canonical locale name string.

Arguments

• language_tag is a %Localize.LanguageTag{} struct.

Returns

• {:ok, canonicalized_tag} with the canonical_locale_id field populated, or

• {:error, reason} if extension validation fails.

Examples

iex> {:ok, tag} = Localize.LanguageTag.parse("en-US-u-nu-arab-ca-gregory")
iex> {:ok, canonical} = Localize.LanguageTag.canonicalize(tag)
iex> canonical.canonical_locale_id
"en-US-u-ca-gregory-nu-arab"

@spec canonicalize!(t()) :: t() | no_return()

Canonicalize a parsed language tag, raising on error.

Same as canonicalize/1 but returns the struct directly or raises an exception.

@spec match_distance(t() | String.t(), t() | String.t()) ::
  number() | {:error, String.t()}

Compute the match distance between two locale tags.

Arguments

• desired is a %Localize.LanguageTag{} struct or locale string.

• supported is a %Localize.LanguageTag{} struct or locale string.

Returns

• A non-negative integer distance score. 0 is a perfect match. Scores below 10 indicate a good fit. Scores above 50 indicate a poor fit.

Examples

iex> Localize.LanguageTag.match_distance("en", "en")
0

iex> Localize.LanguageTag.match_distance("en-AU", "en-GB")
3

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

Create a fully resolved language tag from a locale string.

Parses the input, canonicalizes extensions, adds likely subtags to populate missing fields, then computes the minimized canonical locale name via remove likely subtags. The resulting struct has all fields populated but the canonical_locale_id is the shortest unambiguous form.

Arguments

• locale_id is any BCP 47 locale string.

Returns

• {:ok, language_tag} with all fields resolved, or

• {:error, reason} if parsing, canonicalization, or likely subtag resolution fails.

Examples

iex> {:ok, tag} = Localize.LanguageTag.new("zh-TW")
iex> tag.language
:zh
iex> tag.script
:Hant
iex> tag.territory
:TW
iex> tag.canonical_locale_id
"zh-Hant"

@spec new!(String.t()) :: t() | no_return()

Create a fully resolved language tag, raising on error.

Same as new/1 but returns the struct directly or raises an exception.

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

Parse a locale identifier into a t:Localize.LanguageTag struct.

Arguments

• locale_id is any BCP 47 string.

Returns

• {:ok, t:Localize.LanguageTag} or

• {:error, reason}

@spec parse!(String.t()) :: t() | none()

Parse a locale identifier into a Localize.LanguageTag struct and raises on error

Arguments

• locale_id is any BCP 47 string.

Returns

• t:Localize.LanguageTag or

• raises an exception

@spec remove_likely_subtags(t()) :: {:ok, t()} | {:error, Exception.t()}

Remove likely subtags from a language tag.

Implements the Remove Likely Subtags algorithm from Unicode TR35, using the "favor script" variant.

This removes script and/or region subtags that can be inferred from the remaining subtags using the likely subtags data, producing the shortest unambiguous locale identifier.

Arguments

• language_tag is a %Localize.LanguageTag{} struct.

Returns

• {:ok, minimized_tag} with redundant subtags removed and canonical_locale_id updated, or

• {:error, reason} if maximization fails.

Examples

iex> {:ok, tag} = Localize.LanguageTag.parse("en-Latn-US")
iex> {:ok, min} = Localize.LanguageTag.remove_likely_subtags(tag)
iex> min.canonical_locale_id
"en"

iex> {:ok, tag} = Localize.LanguageTag.parse("zh-Hant-TW")
iex> {:ok, min} = Localize.LanguageTag.remove_likely_subtags(tag)
iex> min.canonical_locale_id
"zh-Hant"

@spec remove_likely_subtags!(t()) :: t() | no_return()

Remove likely subtags from a language tag, raising on error.

Same as remove_likely_subtags/1 but returns the struct directly or raises an exception.

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

Produce the canonical locale identifier string from a Localize.LanguageTag struct.

The canonical form follows the Unicode CLDR specification at TR35 Locale ID Canonicalization:

• Language subtag is lowercase.

• Script subtag is title case.

• Region subtag is uppercase.

• All other subtags are lowercase.

• Variants are sorted alphabetically.

• Extensions are sorted alphabetically by their singleton.

• Within extensions, attributes are sorted alphabetically and fields are sorted by key.

• The keyword value "true" is removed from the canonical form.

If the canonical_locale_id has already been computed, it is returned directly.

Arguments

• language_tag is a %Localize.LanguageTag{} struct.

Returns

• A canonical string representation of the language tag.

Examples

iex> {:ok, tag} = Localize.LanguageTag.parse("en-US")
iex> Localize.LanguageTag.to_string(tag)
"en-US"