Replace empty subtags within a Cldr.LanguageTag.t/0 with the most likely subtag.

Options

• language_tag is any language tag returned by Cldr.Locale.new/2

A subtag is called empty if it has a missing script or territory subtag, or it is a base language subtag with the value und. In the description below, a subscript on a subtag x indicates which tag it is from: x_s is in the source, x_m is in a match, and x_r is in the final result.

Lookup

Lookup each of the following in order, and stops on the first match:

• language_s-script_s-region_s
• language_s-region_s
• language_s-script_s
• language_s
• und-script_s

Returns

• If there is no match,either return

  • an error value, or
  • the match for und

• Otherwise there is a match = language_m-script_m-region_m

• Let x_r = x_s if x_s is not empty, and x_m otherwise.

• Return the language tag composed of language_r-script_r-region_r + variants + extensions .

Example

iex> Cldr.Locale.add_likely_subtags Cldr.LanguageTag.parse!("zh-SG")
%Cldr.LanguageTag{
  backend: nil,
  canonical_locale_name: nil,
  cldr_locale_name: nil,
  language_subtags: [],
  extensions: %{},
  gettext_locale_name: nil,
  language: "zh",
  locale: %{},
  private_use: [],
  rbnf_locale_name: nil,
  requested_locale_name: "zh-SG",
  script: "Hans",
  territory: :SG,
  transform: %{},
  language_variant: nil
}

Specs

alias_error(locale_name() | Cldr.LanguageTag.t(), String.t()) ::
  {Cldr.UnknownLocaleError, String.t()}

Returns an error tuple for an invalid locale alias.

Options

• locale_name is any locale name returned by Cldr.known_locale_names/1

Specs

aliases() :: map()

Return a map of the known aliases for Language, Script and Territory

Specs

aliases(locale_name(), atom()) :: map() | nil

Return a map of the aliases for a given alias key and type

Options

• type is one of [:language, :region, :script, :variant, :zone]

• key is the substitution key (a language, region, script, variant or zone)

Parses a locale name and returns a Cldr.LanguageTag struct that represents a locale.

Arguments

• language_tag is any language tag returned by Cldr.Locale.new/2 or any locale_name returned by Cldr.known_locale_names/1

• backend is any module that includes use Cldr and therefore is a Cldr backend module

Returns

• {:ok, language_tag} or

• {:eror, reason}

Method

1. The language tag is parsed in accordance with RFC5646

2. Any language, script or region aliases are replaced. This will replace any obsolete elements with current versions

3. If a territory or script is not specified, a default is provided using the CLDR information returned by Cldr.Locale.likely_subtags/1

4. A Cldr locale name is selected that is the nearest fit to the requested locale.

Example

iex> Cldr.Locale.canonical_language_tag("en", TestBackend.Cldr)
{
  :ok,
  %Cldr.LanguageTag{
    backend: TestBackend.Cldr,
    canonical_locale_name: "en-Latn-US",
    cldr_locale_name: "en",
    extensions: %{},
    gettext_locale_name: "en",
    language: "en",
    locale: %{},
    private_use: [],
    rbnf_locale_name: "en",
    requested_locale_name: "en",
    script: "Latn",
    territory: :US,
    transform: %{},
    language_variant: nil
  }
}

Specs

canonical_language_tag!(locale_name() | Cldr.LanguageTag.t(), Cldr.backend()) ::
  Cldr.LanguageTag.t() | none()

Parses a locale name and returns a Cldr.LanguageTag struct that represents a locale or raises on error.

Arguments

• language_tag is any language tag returned by Cldr.Locale.new/2 or any locale_name returned by Cldr.known_locale_names/1

• backend is any module that includes use Cldr and therefore is a Cldr backend module

See Cldr.Locale.canonical_language_tag/2 for more information.

Specs

gettext_locale_error(locale_name() | Cldr.LanguageTag.t()) ::
  {Cldr.UnknownLocaleError, String.t()}

Returns an error tuple for an invalid gettext locale.

Options

• locale_name is any locale name returned by Cldr.known_gettext_locale_names/1

Returns

• {:error, {Cldr.UnknownLocaleError, message}}

Examples

iex> Cldr.Locale.gettext_locale_error :invalid
{Cldr.UnknownLocaleError, "The gettext locale :invalid is not known."}

Returns the map of likely subtags.

Note that not all locales are guaranteed to have likely subtags.

Example

Cldr.Locale.likely_subtags
%{
  "bez" => %Cldr.LanguageTag{
    backend: TestBackend.Cldr,
    canonical_locale_name: nil,
    cldr_locale_name: nil,
    extensions: %{},
    language: "bez",
    locale: %{},
    private_use: [],
    rbnf_locale_name: nil,
    requested_locale_name: nil,
    script: "Latn",
    territory: :TZ,
    transform: %{},
    language_variant: nil
  },
  "fuf" => %Cldr.LanguageTag{
    canonical_locale_name: nil,
    cldr_locale_name: nil,
    extensions: %{},
    language: "fuf",
    locale: %{},
    private_use: [],
    rbnf_locale_name: nil,
    requested_locale_name: nil,
    script: "Latn",
    territory: :GN,
    transform: %{},
    language_variant: nil
  },
  ...

Specs

likely_subtags(locale_name()) :: Cldr.LanguageTag.t() | nil

Returns the likely substags, as a Cldr.LanguageTag, for a given locale name.

Options

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct

Examples

iex> Cldr.Locale.likely_subtags "en"
%Cldr.LanguageTag{
  backend: nil,
  canonical_locale_name: nil,
  cldr_locale_name: nil,
  extensions: %{},
  gettext_locale_name: nil,
  language: "en",
  locale: %{},
  private_use: [],
  rbnf_locale_name: nil,
  requested_locale_name: "en-Latn-US",
  script: "Latn",
  territory: :US,
  transform: %{},
  language_variant: nil
}

Specs

locale_error(locale_name() | Cldr.LanguageTag.t()) ::
  {Cldr.UnknownLocaleError, String.t()}

Returns an error tuple for an invalid locale.

Arguments

• locale_name is any locale name returned by Cldr.known_locale_names/1

Returns

• {:error, {Cldr.UnknownLocaleError, message}}

Examples

iex> Cldr.Locale.locale_error :invalid
{Cldr.UnknownLocaleError, "The locale :invalid is not known."}

Specs

locale_name_from(Cldr.LanguageTag.t()) :: locale_name()

Return a locale name from a Cldr.LanguageTag

Options

• locale_name is any Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

Example

iex> Cldr.Locale.locale_name_from Cldr.Locale.new!("en", TestBackend.Cldr)
"en-Latn-US"

Specs

locale_name_from(
  language(),
  script(),
  Cldr.territory() | territory(),
  variant()
) :: locale_name()

Return a locale name by combining language, script, territory and variant parameters

Arguments

• language, script, territory and variant are string representations, or nil, of the language subtags

Returns

• The locale name constructed from the non-nil arguments joined by a "-"

Example

iex> Cldr.Locale.locale_name_from("en", "Latn", "001", nil)
"en-Latn-001"

iex> Cldr.Locale.locale_name_from("en", "Latn", :"001", nil)
"en-Latn-001"

See Cldr.Config.locale_name_from_posix/1.

See Cldr.Config.locale_name_to_posix/1.

See Cldr.Locale.canonical_language_tag/2.

See Cldr.Locale.canonical_language_tag!/2.

Specs

normalize_locale_name(locale_name()) :: locale_name()

Normalize the casing of a locale name.

Options

• locale_name is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct

Returns

• The normalized locale name as a String.t

Method

Locale names are case insensitive but certain common casing is followed in practise:

• lower case for a language
• capital case for a script
• upper case for a region/territory

Note this function is intended to support only the CLDR locale names which have a format that is a subset of the full langauge tag specification.

For proper parsing of local names and language tags, see Cldr.Locale.canonical_language_tag/2

Examples

iex> Cldr.Locale.normalize_locale_name "zh_hant"
"zh-Hant"

iex> Cldr.Locale.normalize_locale_name "en_us"
"en-US"

iex> Cldr.Locale.normalize_locale_name "EN"
"en"

iex> Cldr.Locale.normalize_locale_name "ca_es_valencia"
"ca-ES-VALENCIA"

Specs

put_gettext_locale_name(Cldr.LanguageTag.t(), Cldr.backend()) ::
  Cldr.LanguageTag.t()

Substitute deprectated subtags with a Cldr.LanguageTag with their non-deprecated alternatives.

Arguments

• language_tag is any language tag returned by Cldr.Locale.new/2

Method

• Replace any deprecated subtags with their canonical values using the alias data. Use the first value in the replacement list, if it exists. Language tag replacements may have multiple parts, such as sh ➞ sr_Latn or mo ➞ ro_MD. In such a case, the original script and/or region/territory are retained if there is one. Thus sh_Arab_AQ ➞ sr_Arab_AQ, not sr_Latn_AQ.

• Remove the script code 'Zzzz' and the territory code 'ZZ' if they occur.

• Get the components of the cleaned-up source tag (languages, scripts, and regions/territories), plus any variants and extensions.

Example

iex> Cldr.Locale.substitute_aliases Cldr.LanguageTag.Parser.parse!("mo")
%Cldr.LanguageTag{
  backend: nil,
  canonical_locale_name: nil,
  cldr_locale_name: nil,
  extensions: %{},
  gettext_locale_name: nil,
  language: "ro",
  language_subtags: [],
  language_variant: nil,
  locale: %{}, private_use: [],
  rbnf_locale_name: nil,
  requested_locale_name: "mo",
  script: nil, transform: %{},
  territory: nil
}

Specs

territory_from_locale(Cldr.LanguageTag.t()) :: Cldr.territory()

Returns the effective territory for a locale.

Arguments

• language_tag is any language tag returned by Cldr.Locale.new/2 or any locale_name returned by Cldr.known_locale_names/1

Returns

• The territory to be used for localization purposes

Examples

iex> {:ok, locale} = Cldr.validate_locale("en-US", MyApp.Cldr)
iex> Cldr.Locale.territory_from_locale locale
:US

iex> {:ok, locale} = Cldr.validate_locale("en-US-u-rg-cazzzz", MyApp.Cldr)
iex> Cldr.Locale.territory_from_locale locale
:CA

iex> {:ok, locale} = Cldr.validate_locale("en-US-u-rg-xxxxx", MyApp.Cldr)
iex> Cldr.Locale.territory_from_locale locale
:US

Notes

A locale can reflect the desired territory to be used when determining region-specific defaults for items such as:

• default currency,
• default calendar and week data,
• default time cycle, and
• default measurement system and unit preferences

Territory information is stored in the locale in up to three different places:

1. The :territory extracted from the locale name or defined by default for a given language. This is the typical use case when locale names such as en-US or es-AR are used.

2. In some cases it might be desired to override the territory derived from the locale name. For example, the default territory for the language "en" is "US" but it may be desired to apply the defaults for the territory "AU" instead, without otherwise changing the localization intent. In this case the U extension is used to define a regional override

3. Similarly, the [regional subdivision identifier] (https://unicode.org/reports/tr35/#UnicodeSubdivisionIdentifier) can be used to influence localization decisions. This identifier is not currently used in ex_cldr and dependent libraries however it is correctly parsed to support future use.

Specs

territory_from_locale(locale_name(), Cldr.backend()) ::
  Cldr.territory() | {:error, {module(), String.t()}}