Resolves a locale to the name of a PostgreSQL ICU collation.
PostgreSQL's initdb imports the full set of ICU collations into
pg_catalog, naming each one after its BCP 47 locale identifier with
an -x-icu suffix — for example de-DE-x-icu, zh-Hant-TW-x-icu
and the root collation und-x-icu.
This module maps a Localize.LanguageTag.t/0 (or any locale
identifier accepted by Localize.validate_locale/1) onto the best
matching collation using the CLDR Language Matching
algorithm implemented by Localize.LanguageTag.best_match/3. The
requested locale is matched against the set of collation locales
PostgreSQL derives from ICU, bundled with this library, and the root
collation und-x-icu is the fallback of last resort.
Because CLDR collation tailorings are defined per language (and
script) rather than per territory, a match to a broader locale — for
example de-DE matching the de collation locale — selects an
identical collator.
The primary public API is collation_for/2 and collation_for!/2.
Summary
Functions
Returns the PostgreSQL ICU collation name for the given locale.
Returns the PostgreSQL ICU collation name for the given locale or raises.
Returns the list of locales for which a PostgreSQL ICU collation is known to exist.
Resolves the argument of Localize.Ecto.collate/2 to a collation
name.
Functions
@spec collation_for(Localize.locale() | String.t(), Keyword.t()) :: {:ok, String.t()} | {:error, Exception.t()}
Returns the PostgreSQL ICU collation name for the given locale.
Resolutions against the default collation locales are cached, so repeated calls for the same locale are inexpensive.
Arguments
localeis aLocalize.LanguageTag.t/0, or any locale identifier accepted byLocalize.validate_locale/1. The default isLocalize.get_locale/0.optionsis a keyword list of options.
Options
:availableis a list of BCP 47 locale strings (without the-x-icusuffix) to match against. The default is the list bundled with this library, generated from PostgreSQL'spg_collationcatalog.
Returns
{:ok, collation_name}wherecollation_nameis a string such as"de-x-icu", or{:error, exception}iflocaleis not a valid locale.
Examples
iex> Localize.Ecto.Collation.collation_for("de-DE")
{:ok, "de-x-icu"}
iex> Localize.Ecto.Collation.collation_for("zh-TW")
{:ok, "zh-Hant-x-icu"}
iex> Localize.Ecto.Collation.collation_for("xx")
{:error, %Localize.InvalidLocaleError{locale_id: "xx"}}@spec collation_for!(Localize.locale() | String.t(), Keyword.t()) :: String.t()
Returns the PostgreSQL ICU collation name for the given locale or raises.
Arguments
localeis aLocalize.LanguageTag.t/0, or any locale identifier accepted byLocalize.validate_locale/1. The default isLocalize.get_locale/0.optionsis a keyword list of options. Seecollation_for/2.
Returns
A collation name string such as
"de-x-icu", orraises if
localeis not a valid locale.
Examples
iex> Localize.Ecto.Collation.collation_for!("sv")
"sv-x-icu"
iex> Localize.Ecto.Collation.collation_for!(:"en-GB")
"en-GB-x-icu"@spec known_collations() :: [String.t()]
Returns the list of locales for which a PostgreSQL ICU collation is known to exist.
The list contains BCP 47 locale strings without the -x-icu suffix,
as recorded in the colllocale column of pg_collation.
Returns
- A list of locale strings.
Examples
iex> "de-DE" in Localize.Ecto.Collation.known_collations()
true
iex> "und" in Localize.Ecto.Collation.known_collations()
true@spec resolve!(Localize.locale() | String.t() | Keyword.t()) :: String.t()
Resolves the argument of Localize.Ecto.collate/2 to a collation
name.
This is the runtime companion of the Localize.Ecto.collate/1,2
macros and is not usually called directly.
Arguments
locale_or_optionsis a locale accepted bycollation_for!/2, or a keyword list.
Options
:collationis a collation name used verbatim, bypassing locale resolution — for example a collation created withLocalize.Ecto.Migration.create_collation/2under a custom name.Any other options are passed to
collation_for!/2.
Returns
A collation name string, or
raises if the locale is not valid.
Examples
iex> Localize.Ecto.Collation.resolve!("sv")
"sv-x-icu"
iex> Localize.Ecto.Collation.resolve!(collation: "german_phonebook")
"german_phonebook"