-spec available_index([locale()]) -> available_index().

Builds the canonical→original index for an available-locale set, for reuse across many negotiate_with_index/2 calls.

Maps canonicalize(A) to the original A for each A in Available, first occurrence winning (so the earliest entry's original catalog casing is the one returned by a later match). This is the per-Available work negotiate/2 otherwise repeats on every call; build it once when negotiating multiple preference lists against the same set. Total.

1> Ix = erli18n_negotiate:available_index([<<"pt_BR">>, <<"fr">>]).
2> erli18n_negotiate:negotiate_with_index([<<"pt-BR">>], Ix).
{ok,<<"pt_BR">>}

-spec best_match([locale()] | [{locale(), qvalue()}], [locale()], locale()) -> locale().

The bare RFC 4647 Lookup primitive: like negotiate/3 but returns the matched (or Default) locale directly, never wrapped. Always succeeds (falls to Default). Total.

1> erli18n_negotiate:best_match([<<"en-US">>], [<<"en">>], <<"x">>).
<<"en">>

-spec canonicalize(binary()) -> binary().

Canonicalizes ONE BCP-47 / POSIX locale tag to erli18n catalog-key shape.

Underscore-joined, RFC 5646 §2.1.1 positional casing (language lowercase, script Titlecase, region UPPERCASE), with a charset/modifier suffix stripped and a bounded legacy-language alias applied to the language subtag. Hyphen and underscore are equivalent on input.

Total and idempotent: any binary input returns a binary and re-running produces the same result. A binary over ?MAX_TAG_BYTES, an empty binary, or a tag with more than ?MAX_SUBTAGS subtags is returned UNCHANGED (fail-soft). A non-binary argument is a programmer error and raises function_clause (the contract is binary-in/binary-out).

1> erli18n_negotiate:canonicalize(<<"PT_br">>).
<<"pt_BR">>
2> erli18n_negotiate:canonicalize(<<"zh-hant-tw">>).
<<"zh_Hant_TW">>
3> erli18n_negotiate:canonicalize(<<"ca_ES@valencia">>).
<<"ca_ES">>
4> erli18n_negotiate:canonicalize(<<"iw">>).
<<"he">>

See fallback_chain/2 (uses this) and the module doc for the alias table and the documented non-goals (zh_Hans ⇄ zh_CN Likely Subtags).

-spec fallback_chain(locale(), locale() | undefined) -> [locale(), ...].

Builds the ordered, deduplicated RFC 4647 Lookup fallback chain for a locale, ending in Default (canonicalized) unless Default =:= undefined.

Locale is canonicalized first, then the trailing subtag is dropped repeatedly to a fixpoint (zh_Hant_TW → zh_Hant → zh); Default is appended last. The result is order-preserving deduplicated and capped at ?MAX_CHAIN. The head is the most specific candidate. Total; the returned list is always non-empty (at minimum [canonicalize(Locale)]).

1> erli18n_negotiate:fallback_chain(<<"pt-BR">>, <<"en">>).
[<<"pt_BR">>,<<"pt">>,<<"en">>]
2> erli18n_negotiate:fallback_chain(<<"zh_Hant_TW">>, <<"en">>).
[<<"zh_Hant_TW">>,<<"zh_Hant">>,<<"zh">>,<<"en">>]
3> erli18n_negotiate:fallback_chain(<<"en">>, undefined).
[<<"en">>]

The facade walks this list with one catalog read per candidate, returning on the first hit; this is what makes a pt_BR user fall back to a loaded pt catalog. See canonicalize/1.

-spec negotiate([locale()] | [{locale(), qvalue()}], [locale()]) -> {ok, locale()} | error.

Picks the best supported locale for a preference list, or error.

Preferred is an ordered preference list (priority = position): either [locale()] or the [{locale(), qvalue()}] output of parse_accept_language/1 (the Q is ignored — order already encodes priority, and q=0 ranges were already dropped). Available is the list of catalog locales (e.g. erli18n:loaded_catalogs/0 locales).

Each Preferred entry is canonicalized and resolved through its fallback_chain/2 (no default) against a canonical→original index of Available; the FIRST hit wins. * ranges are skipped. The returned locale is the ORIGINAL Available casing. Total.

1> erli18n_negotiate:negotiate([<<"pt-BR">>], [<<"pt">>, <<"en">>]).
{ok,<<"pt">>}
2> erli18n_negotiate:negotiate([<<"zh_Hant">>], [<<"en">>]).
error

See negotiate/3 (default instead of error) and best_match/3.

-spec negotiate([locale()] | [{locale(), qvalue()}], [locale()], locale()) -> {ok, locale()}.

Like negotiate/2, but returns {ok, Default} instead of error when nothing matches. Default is the caller's chosen floor (the RFC 4647 Lookup default) and is NOT validated against Available. Total.

1> erli18n_negotiate:negotiate([<<"zh_Hant">>], [<<"en">>], <<"en">>).
{ok,<<"en">>}

-spec negotiate_with_index([locale()] | [{locale(), qvalue()}], available_index()) ->
                              {ok, locale()} | error.

Like negotiate/2, but against a PREBUILT available_index/1 instead of a raw Available list — so the canonical index is built once and reused across many preference lists (e.g. one per request source).

negotiate(Preferred, Available) is exactly negotiate_with_index(Preferred, available_index(Available)); this arity lets a caller hoist the available_index/1 out of a per-candidate loop. Semantics are otherwise identical: each Preferred entry is canonicalized and resolved through its fallback_chain/2 against the index, first hit winning, returning the original Available casing. Total.

1> Ix = erli18n_negotiate:available_index([<<"pt">>, <<"en">>]).
2> erli18n_negotiate:negotiate_with_index([<<"pt-BR">>], Ix).
{ok,<<"pt">>}
3> erli18n_negotiate:negotiate_with_index([<<"zh_Hant">>], Ix).
error

See negotiate/2 (raw-list form) and available_index/1.

-spec override_chain(locale(), [locale()], locale() | undefined) -> [locale(), ...].

Builds an explicit-override fallback chain for {explicit, Map} mode: the canonicalized Overrides list prefixed with canonicalize(Locale) and floored with Default. Order-preserving deduplicated and bounded by the SAME ?MAX_CHAIN cap as fallback_chain/2. Total.

Exposed so the facade's explicit-map mode reuses one bounding/dedup implementation instead of re-deriving the cap.

1> erli18n_negotiate:override_chain(<<"de-AT">>, [<<"de">>], <<"en">>).
[<<"de_AT">>,<<"de">>,<<"en">>]

-spec parse_accept_language(binary()) -> [{language_range(), qvalue()}].

Parses an HTTP Accept-Language header into [{Range, Q}].

Range is the ASCII-lowercased, hyphen-separated language range as on the wire (NOT canonicalized; may be <<"*">>); Q is an integer in milli-units (0..1000). An absent q parameter means 1000; a well-formed q=0 entry is DROPPED. The list is sorted by descending Q, ties broken by ascending header position (stable).

Total and fail-soft: any malformed element is skipped, never crashing. Returns [] on an empty header, a header over ?MAX_HEADER_BYTES, or one with more than ?MAX_RAW_ELEMS comma elements. A non-binary argument raises function_clause. At most ?MAX_RANGES ranges are returned.

The output shape matches cowlib's cow_http_hd:parse_accept_language/1, so a Cowboy app may feed either source into negotiate/2. Unlike cowlib, this parser never raises on hostile input.

1> erli18n_negotiate:parse_accept_language(<<"da, en-gb;q=0.8, en;q=0.7">>).
[{<<"da">>,1000},{<<"en-gb">>,800},{<<"en">>,700}]
2> erli18n_negotiate:parse_accept_language(<<"fr;q=0, de">>).
[{<<"de">>,1000}]

See best_match/3 and negotiate/2,3.