Specs

aliases() :: map()

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

Specs

aliases(locale_name() | String.t(), atom()) ::
  String.t() | [String.t()] | Cldr.LanguageTag.t() | 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)

Specs

canonical_language_tag(
  locale_name() | Cldr.LanguageTag.t() | String.t(),
  Cldr.backend(),
  Keyword.t()
) :: {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}

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

• options is a keyword list of options

Options

• :add_likely_subtags is a boolean thatdetermines if subtags that are likely to be applicable to this language tag are added to the language tag. The default is true.

Returns

• {:ok, language_tag} or

• {:error, 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, script or language variant is not specified, then a default is provided using the CLDR information returned by Cldr.Locale.likely_subtags/1 if the option :add_likely_subtags is true (the default).

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",
    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_variants: []
  }
}

Specs

canonical_language_tag!(
  locale_name() | Cldr.LanguageTag.t(),
  Cldr.backend(),
  Keyword.t()
) ::
  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/3 for more information.

Returns a list of territory top-level domains that are considered to be generic top level domains.

See https://developers.google.com/search/docs/advanced/crawling/managing-multi-regional-sites for an explanation of why some valid territory suffixxes are considered as TLDs.

Example

iex> Cldr.Locale.consider_as_tlds
[:AD, :AS, :BZ, :CC, :CD, :CO, :DJ, :FM, :IO, :LA, :ME, :MS, :NU, :SC, :SR, :SU, :TV, :TK, :WS]

Specs

fallback_locale_names(Cldr.LanguageTag.t()) ::
  {:ok, [locale_name(), ...]} | {:error, {module(), binary()}}

Returns the list of fallback locale names, starting with the the provided locale.

Fallbacks are a list of locate names which can be used to resolve translation or other localization data if such localised data does not exist for this specific locale. After locale-specific fallbacks are determined, the the default locale and its fallbacks are added to the chain.

Arguments

• locale is any LanguageTag.t

Returns

• {:ok, list_of_locale_names} or

• {:error, {exception, reason}}

Examples

In these examples the default locale is :"en-001".

iex> Cldr.Locale.fallback_locale_names(Cldr.Locale.new!("fr-CA", MyApp.Cldr))
{:ok, [:"fr-CA", :fr, :"en-001", :en]}

# Fallbacks are typically formed by progressively
# stripping variant, territory and script from the
# given locale name. But not always - there are
# certain fallbacks that take a different path.

iex> Cldr.Locale.fallback_locale_names(Cldr.Locale.new!("nb", MyApp.Cldr))
{:ok, [:nb, :no, :"en-001", :en]}

Specs

fallback_locale_names(locale_reference(), Cldr.backend()) ::
  {:ok, [locale_name(), ...]} | {:error, {module(), binary()}}

Returns the list of fallback locale names, starting the the provided locale name.

Fallbacks are a list of locate names which can be used to resolve translation or other localization data if such localised data does not exist for this specific locale. After locale-specific fallbacks are determined, the the default locale and its fallbacks are added to the chain.

Arguments

• locale_name is 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. The default is Cldr.default_locale/0.

Returns

• {:ok, list_of_locale_names} or

• {:error, {exception, reason}}

Examples

In these examples the default locale is :"en-001".

iex> Cldr.Locale.fallback_locale_names(:"fr-CA")
{:ok, [:"fr-CA", :fr, :"en-001", :en]}

# Fallbacks are typically formed by progressively
# stripping variant, territory and script from the
# given locale name. But not always - there are
# certain fallbacks that take a different path.

iex> Cldr.Locale.fallback_locale_names(:nb)
{:ok, [:nb, :no, :"en-001", :en]}

Returns the list of fallback locale names, starting with the the provided locale.

Fallbacks are a list of locate names which can be used to resolve translation or other localization data if such localised data does not exist for this specific locale. After locale-specific fallbacks are determined, the the default locale and its fallbacks are added to the chain.

Arguments

• locale is any LanguageTag.t

Returns

• list_of_locale_names or

• raises an exception

Examples

In these examples the default locale is :"en-001".

iex> Cldr.Locale.fallback_locale_names!(Cldr.Locale.new!("fr-CA", MyApp.Cldr))
[:"fr-CA", :fr, :"en-001", :en]

# Fallbacks are typically formed by progressively
# stripping variant, territory and script from the
# given locale name. But not always - there are
# certain fallbacks that take a different path.

iex> Cldr.Locale.fallback_locale_names!(Cldr.Locale.new!("nb", MyApp.Cldr))
[:nb, :no, :"en-001", :en]

Specs

fallback_locales(Cldr.LanguageTag.t()) ::
  {:ok, [Cldr.LanguageTag.t(), ...]} | {:error, {module(), binary()}}

Returns the list of fallback locales, starting the the provided locale.

Fallbacks are a list of locate names which can be used to resolve translation or other localization data if such localised data does not exist for this specific locale. After locale-specific fallbacks are determined, the the default locale and its fallbacks are added to the chain.

Arguments

• locale is any LanguageTag.t

Returns

• {:ok, list_of_locales} or

• {:error, {exception, reason}}

Examples

In these examples the default locale is :"en-001".

Cldr.Locale.fallback_locales(Cldr.Locale.new!("fr-CA", MyApp.Cldr))
=> {:ok,
 [#Cldr.LanguageTag<fr-CA [validated]>, #Cldr.LanguageTag<fr [validated]>,
  #Cldr.LanguageTag<en [validated]>]}

# Fallbacks are typically formed by progressively
# stripping variant, territory and script from the
# given locale name. But not always - there are
# certain fallbacks that take a different path.

Cldr.Locale.fallback_locales(Cldr.Locale.new!("nb", MyApp.Cldr))
=> {:ok,
 [#Cldr.LanguageTag<nb [validated]>, #Cldr.LanguageTag<no [validated]>,
  #Cldr.LanguageTag<en [validated]>]}

Specs

fallback_locales(locale_reference(), Cldr.backend()) ::
  {:ok, [Cldr.LanguageTag.t(), ...]} | {:error, {module(), binary()}}

Returns the list of fallback locales, starting the the provided locale.

Fallbacks are a list of locate names which can be used to resolve translation or other localization data if such localised data does not exist for this specific locale. After locale-specific fallbacks are determined, the the default locale and its fallbacks are added to the chain.

Arguments

• locale_name is 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. The default is Cldr.default_locale/0.

Returns

• {:ok, list_of_locales} or

• {:error, {exception, reason}}

Examples

In these examples the default locale is :"en-001".

Cldr.Locale.fallback_locales(:"fr-CA")
=> {:ok,
     [#Cldr.LanguageTag<fr-CA [validated]>, #Cldr.LanguageTag<fr [validated]>,
      #Cldr.LanguageTag<en [validated]>]}

# Fallbacks are typically formed by progressively
# stripping variant, territory and script from the
# given locale name. But not always - there are
# certain fallbacks that take a different path.

Cldr.Locale.fallback_locales(:nb)
=> {:ok,
     [#Cldr.LanguageTag<nb [validated]>, #Cldr.LanguageTag<no [validated]>,
      #Cldr.LanguageTag<en [validated]>]}

Execute a function for a locale returning the first match on language, script, territory, and variant combination.

A match is determined when the fun/1 returns a truthy value.

Arguments

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

• fun/1 is single-arity function that takes a string locale name. The locale name is a built from the language, script, territory and variant combinations of language_tag.

Returns

• The first truthy value returned by fun/1 or nil if no match is made.

Mapping of language data to known scripts and territories

Returns a map of a territory code to its most-spoken language.

Example

  Cldr.Locale.languages_for_territories()
  => %{
    AQ: "und",
    PE: "es",
    SR: "nl",
    NU: "en",
    ...
  }

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_variants: []
  },
  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_variants: []
  },
  ...

Specs

likely_subtags(locale_name() | String.t()) :: 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_variants: []
}

Specs

locale_for_territory(territory_code(), Cldr.backend()) ::
  {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}

Returns the "best fit" locale for a given territory.

Using the population percentage data from CLDR, the language most commonly spoken in the given territory is used to form a locale name which is then validated against the given backend.

First a territory-specific locale is validated and if that fails, the base language only is validate.

For example, if the territory is AU then then the language most spoken is "en". First, the locale "en-AU" is validated and if that fails, "en" is validated.

Arguments

• territory is any ISO 3166 Alpha-2 territory code that can be validated by Cldr.validate_territory/1

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

Returns

• {:ok, language_tag} or

• {:error, {exception, reason}}

Examples

iex> Cldr.Locale.locale_for_territory(:AU, TestBackend.Cldr) Cldr.validate_locale(:"en-AU", TestBackend.Cldr)

iex> Cldr.Locale.locale_for_territory(:US, TestBackend.Cldr) Cldr.validate_locale(:"en-US", TestBackend.Cldr)

iex> Cldr.Locale.locale_for_territory(:ZZ) {:error, {Cldr.UnknownTerritoryError, "The territory :ZZ is unknown"}}

Specs

locale_from_host(String.t(), Cldr.backend(), Keyword.t()) ::
  {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}

Returns a "best fit" locale for a host name.

Arguments

• host is any valid host name

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

• options is a keyword list of options. The default is [tlds: Cldr.Locale.consider_as_tlds()].

Options

• :tlds is a list of territory codes as upper-cased atoms that are to be considered as top-level domains. The default list is consider_as_tlds/0.

Returns

• {:ok, langauge_tag} or

• {:error, {exception, reason}}

Notes

Certain top-level domains have become associated with content underlated to the territory for who the domain is registered. Therefore Google (and perhaps others) do not associate these TLDs as belonging to the territory but rather are considered generic top-level domain names.

Examples

iex> Cldr.Locale.locale_from_host "a.b.com.au", TestBackend.Cldr
Cldr.validate_locale(:"en-AU", TestBackend.Cldr)

iex> Cldr.Locale.locale_from_host "a.b.com.tv", TestBackend.Cldr
{:error,
 {Cldr.UnknownLocaleError, "No locale was identified for territory \"tv\""}}

iex> Cldr.Locale.locale_from_host "a.b.com", TestBackend.Cldr
{:error,
 {Cldr.UnknownLocaleError, "No locale was identified for territory \"com\""}}

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"

Specs

locale_name_from(
  language(),
  script(),
  territory_reference(),
  variants(),
  boolean()
) :: String.t()

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

Arguments

• language is a string representing a valid language code

• script is an atom that is a valid script code.

• territory is an atom that is a valid territory code.

• variants is a list of language variants as lower case string or []

Returns

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

Example

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

iex> Cldr.Locale.locale_name_from("en", :Latn, :"001", [])
"en-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

parent(Cldr.LanguageTag.t()) ::
  {:ok, Cldr.LanguageTag.t()} | {:error, {module(), binary()}}

Returns the parent for a given locale.

The function implements locale inheritance in accordance with CLDR's inheritance rules.

Only locales that are configured are returned. That is, there may be a different parent locale in CLDR but unless those locales are configured they are not candidates to be parents in this context. The contract is to return either a known locale or an error.

Inheritance

• Inheritance starts by looking for a parent locale via Cldr.Config.parent_locales/0.

• If not found, strip in turn the variant, script and territory while checking to see if a base locale for the given language exists.

• If no parent language exists then move to the default locale and its inheritance chain.

Specs

parent(locale_name(), Cldr.backend()) ::
  {:ok, Cldr.LanguageTag.t()} | {:error, {module(), binary()}}

Returns mappings between a locale and its parent.

The mappings exist only where normal inheritance rules are not applied.

Returns a list of all the parent locales for a given locale.

Examples

  Cldr.Locale.parents "fr-ca"
  => {:ok, [#Cldr.LanguageTag<fr [validated]>, #Cldr.LanguageTag<en [validated]>]}

Specs

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

Specs

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

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

Arguments

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

• options is a keyword list of options

Options

• :add_likely is a boolean indicating whether to add likely subtags. The default is true.

Notes

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.put_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_variants: []
}

Substitute deprecated 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_variants: [],
  locale: %{},
  private_use: [],
  rbnf_locale_name: nil,
  requested_locale_name: "mo",
  script: nil,
  territory: nil,
  transform: %{}
}

Specs

territory_from_host(String.t()) ::
  {:ok, territory_code()} | {:error, {module(), String.t()}}

Returns the last segment of a host that might be a territory.

Arguments

• host is any valid host name

Returns

• {:ok, territory} or

• {:error, {exception, reason}}

Examples

iex> Cldr.Locale.territory_from_host("a.b.com.au")
{:ok, :AU}

iex> Cldr.Locale.territory_from_host("a.b.com")
{:error,
 {Cldr.UnknownLocaleError, "No locale was identified for territory \"com\""}}

Specs

territory_from_locale(Cldr.LanguageTag.t() | locale_name() | String.t()) ::
  territory_code()

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. If the parameter is a locale_name then a default backend must be configured in config.exs or an exception will be raised.

Returns

• The territory to be used for localization purposes.

Examples

iex> Cldr.Locale.territory_from_locale "en-US"
:US

iex> Cldr.Locale.territory_from_locale "en-US-u-rg-cazzzz"
:CA

iex> Cldr.Locale.territory_from_locale "en-US-u-rg-xxxxx"
{:error, {Cldr.LanguageTag.ParseError, "The value \"xxxxx\" is not valid for the key \"rg\""}}

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 desirable 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_reference() | String.t(), Cldr.backend()) ::
  territory_code() | {:error, {module(), String.t()}}

Returns the effective territory for a locale.

Arguments

• locale_name is 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

• The territory to be used for localization purposes or {:error, {exception, reason}}.

Examples

iex> Cldr.Locale.territory_from_locale "en-US", TestBackend.Cldr
:US

iex> Cldr.Locale.territory_from_locale "en-US-u-rg-cazzzz", TestBackend.Cldr
:CA

iex> Cldr.Locale.territory_from_locale "en-US-u-rg-xxxxx", TestBackend.Cldr
{:error, {Cldr.LanguageTag.ParseError, "The value \"xxxxx\" is not valid for the key \"rg\""}}

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 desirable 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

timezone_from_locale(Cldr.LanguageTag.t() | locale_name() | String.t()) ::
  String.t() | {:error, {module(), String.t()}}

Returns the effective time zone 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. If the parameter is a locale_name then a default backend must be configured in config.exs or an exception will be raised.

Returns

• The time zone ID as a String.t or {:error, {exception, reason}}

Examples

iex> Cldr.Locale.timezone_from_locale "en-US-u-tz-ausyd"
"Australia/Sydney"

iex> Cldr.Locale.timezone_from_locale "en-AU"
{:error,
 {Cldr.AmbiguousTimezoneError,
  "Cannot determine the timezone since the territory :AU has 24 timezone IDs"}}

Specs

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

Returns the effective time zone for a locale.

Arguments

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

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

Returns

• The time zone ID as a String.t or {:error, {exception, reason}}

Examples

iex> Cldr.Locale.timezone_from_locale "en-US-u-tz-ausyd", TestBackend.Cldr
"Australia/Sydney"

iex> Cldr.Locale.timezone_from_locale :"en-AU", TestBackend.Cldr
{:error,
 {Cldr.AmbiguousTimezoneError,
  "Cannot determine the timezone since the territory :AU has 24 timezone IDs"}}