Cldr.Locale (Cldr v2.33.0) View Source

Functions to parse and normalize locale names into a structure locale represented by a Cldr.LanguageTag.

CLDR represents localisation data organized into locales, with each locale being identified by a locale name that is formatted according to RFC5646.

In practise, the CLDR data utilizes a simple subset of locale name formats being:

  • a Language code such as en or fr

  • a Language code and Tertitory code such as en-GB

  • a Language code and Script such as zh-Hant

  • and in only two cases a Language code, Territory code and Variant such as ca-ES-valencia and en-US-posix.

The RFC defines a language tag as:

A language tag is composed from a sequence of one or more "subtags", each of which refines or narrows the range of language identified by the overall tag. Subtags, in turn, are a sequence of alphanumeric characters (letters and digits), distinguished and separated from other subtags in a tag by a hyphen ("-", [Unicode] U+002D)

Therefore Cldr uses the hyphen ("-", [Unicode] U+002D) as the subtag separator. On certain platforms, including POSIX platforms, the subtag separator is a "_" (underscore) rather than a "-" (hyphen). Where appropriate, Cldr will transliterate any underscore into a hyphen before parsing or processing.

Locale name validity

When validating a locale name, Cldr will attempt to match the requested locale name to a configured locale. Therefore Cldr.Locale.new/2 may return an {:ok, language_tag} tuple even when the locale returned does not exactly match the requested locale name. For example, the following attempts to create a locale matching the non-existent "english as spoken in Spain" local name. Here Cldr will match to the nearest configured locale, which in this case will be "en".

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

Matching locales to requested locale names

When attempting to match the requested locale name to a configured locale, Cldr attempt to match against a set of reductions in the following order and will return the first match:

  • language, script, territory, [variants]
  • language, territory, [variants]
  • language, script, [variants]
  • language, [variants]
  • language, script, territory
  • language, territory
  • language, script
  • language
  • requested locale name
  • nil

Therefore matching is tolerant of a request for unknown scripts, territories and variants. Only the requested language is a requirement to be matched to a configured locale.

Substitutions for Obsolete and Deprecated locale names

CLDR provides data to help manage the transition from obsolete or deprecated locale names to current names. For example, the following requests the locale name "mo" which is the deprecated code for "Moldovian". The replacement code is "ro" (Romanian).

iex> Cldr.Locale.new("mo", TestBackend.Cldr)
{:ok, %Cldr.LanguageTag{
  backend: TestBackend.Cldr,
  extensions: %{},
  gettext_locale_name: nil,
  language: "ro",
  language_subtags: [],
  language_variants: [],
  locale: %{}, private_use: [],
  rbnf_locale_name: :ro,
  requested_locale_name: "mo",
  script: :Latn,
  transform: %{},
  canonical_locale_name: "ro",
  cldr_locale_name: :ro,
  territory: :RO
}}

Likely subtags

CLDR also provides data to indetify the most likely subtags for a requested locale name. This data is based on the default content data, the population data, and the the suppress-script data in [BCP47]. It is heuristically derived, and may change over time. For example, when requesting the locale "en", the following is returned:

iex> Cldr.Locale.new("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: []
}}

Which shows that a the likely subtag for the script is :Latn and the likely territory is "US".

Using the example for Substitutions above, we can see the result of combining substitutions and likely subtags for locale name "mo" returns the current language code of "ro" as well as the likely territory code of "MD" (Moldova).

Unknown territory codes

Whilst Cldr is tolerant of invalid territory codes. Therefore validity is not checked by Cldr.Locale.new/2 but it is checked by Cldr.validate_locale/2 which is the recommended api for forming language tags.

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

Locale extensions

Unicode defines the U extension which support defining the requested treatment of CLDR data formats. For example, a locale name can configure the requested:

  • calendar to be used for dates
  • collation
  • currency
  • currency format
  • number system
  • first day of the week
  • 12-hour or 24-hour time
  • time zone
  • and many other items

For example, the following locale name will request the use of the timezone Australia/Sydney, and request the use of accounting format when formatting currencies:

iex> MyApp.Cldr.validate_locale "en-AU-u-tz-ausyd-cf-account"
{
  :ok,
  %Cldr.LanguageTag{
    backend: MyApp.Cldr,
    canonical_locale_name: "en-AU-u-cf-account-tz-ausyd",
    cldr_locale_name: :"en-AU",
    extensions: %{},
    gettext_locale_name: "en",
    language: "en",
    language_subtags: [],
    language_variants: [],
    locale: %Cldr.LanguageTag.U{
      calendar: nil,
      cf: :account,
      col_alternate: nil,
      col_backwards: nil,
      col_case_first: nil,
      col_case_level: nil,
      col_normalization: nil,
      col_numeric: nil,
      col_reorder: nil,
      col_strength: nil,
      collation: nil,
      currency: nil,
      dx: nil,
      em: nil,
      fw: nil,
      hc: nil,
      lb: nil,
      lw: nil,
      ms: nil,
      numbers: nil,
      rg: nil,
      sd: nil,
      ss: nil,
      timezone: "Australia/Sydney",
      va: nil,
      vt: nil
    },
    private_use: '',
    rbnf_locale_name: :en,
    requested_locale_name: "en-AU",
    script: :Latn,
    territory: :AU,
    transform: %{}
  }
}

Link to this section Summary

Types

The name of a language

The name of a locale

A reference to a locale

The name of a script

The list of language subtags as strings

A territory code as an ISO3166 Alpha-2 in atom form

The name of a territory

The list of language variants as strings

Functions

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

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

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

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

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

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

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

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

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

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

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

Mapping of language data to known scripts and territories

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

Returns the map of likely subtags.

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

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

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

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

Returns the parent for a given locale.

Returns mappings between a locale and its parent.

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

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

Returns the script for a locale.

Returns the script for a locale.

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

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

Returns the effective territory for a locale.

Returns the effective territory for a locale.

Returns the effective time zone for a locale.

Returns the effective time zone for a locale.

Link to this section Types

Specs

language() :: String.t() | nil

The name of a language

Specs

locale_name() :: atom()

The name of a locale

Specs

locale_reference() :: Cldr.LanguageTag.t() | locale_name() | String.t()

A reference to a locale

Specs

script() :: atom() | String.t() | nil

The name of a script

Specs

subtags() :: [String.t(), ...] | []

The list of language subtags as strings

Specs

territory_code() :: atom()

A territory code as an ISO3166 Alpha-2 in atom form

Specs

territory_reference() :: atom() | String.t() | nil

The name of a territory

Specs

variants() :: [String.t()] | []

The list of language variants as strings

Link to this section Functions

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)

Link to this function

canonical_language_tag(locale_name, backend, options \\ [])

View Source

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: []
  }
}
Link to this function

canonical_language_tag!(language_tag, backend, options \\ [])

View Source

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

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]
Link to this function

fallback_locale_names(locale)

View Source (since 2.26.0)

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]}
Link to this function

fallback_locale_names(locale_name, backend \\ Cldr.default_backend!())

View Source (since 2.26.0)

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

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]}
Link to this function

fallback_locale_names!(locale)

View Source

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]
Link to this function

fallback_locales(locale)

View Source (since 2.26.0)

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]>]}
Link to this function

fallback_locales(locale_name, backend \\ Cldr.default_backend!())

View Source (since 2.26.0)

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

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]>]}
Link to this function

first_match(language_tag, fun, omit_singular_script? \\ false)

View Source

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.
Link to this macro

is_locale_name(locale_name)

View Source (macro)

Mapping of language data to known scripts and territories

Link to this function

languages_for_territories()

View Source (since 2.26.0)

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: []
  },
  ...
Link to this function

likely_subtags(locale_name)

View Source

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

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: []
}
Link to this function

locale_for_territory(territory, backend \\ Cldr.default_backend!())

View Source (since 2.26.0)

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"}}

Link to this function

locale_from_host(host, backend, options \\ [])

View Source (since 2.26.0)

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\""}}
Link to this function

locale_name_from(language_tag, omit_singular_script? \\ true)

View Source

Return a locale name from a Cldr.LanguageTag

Options

Example

iex> Cldr.Locale.locale_name_from Cldr.Locale.new!("en", TestBackend.Cldr)
"en"
Link to this function

locale_name_from(language, script, territory, variants, omit_singular_script? \\ true)

View Source

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"
Link to this function

locale_name_from_posix(locale_name)

View Source

See Cldr.Config.locale_name_from_posix/1.

Link to this function

locale_name_to_posix(locale_name)

View Source

See Cldr.Config.locale_name_to_posix/1.

Link to this function

new(locale_name, backend)

View Source

See Cldr.Locale.canonical_language_tag/2.

Link to this function

new!(locale_name, backend)

View Source

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.

Link to this function

parent(locale_name, backend \\ Cldr.default_backend!())

View Source

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.

Link to this function

parents(locale, acc \\ [])

View Source

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]>]}
Link to this function

put_gettext_locale_name(language_tag)

View Source

Specs

put_gettext_locale_name(Cldr.LanguageTag.t()) :: Cldr.LanguageTag.t()
Link to this function

put_gettext_locale_name(language_tag, config)

View Source

Specs

put_gettext_locale_name(Cldr.LanguageTag.t(), Cldr.Config.t()) ::
  Cldr.LanguageTag.t()
Link to this function

put_likely_subtags(language_tag)

View Source

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<sub>s</sub> is in the source, x<sub>m</sub> is in a match, and x<sub>r</sub> is in the final result.

Lookup

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

  • language<sub>s</sub>-script<sub>s</sub>-region<sub>s</sub>
  • language<sub>s</sub>-region<sub>s</sub>
  • language<sub>s</sub>-script<sub>s</sub>
  • language<sub>s</sub>
  • und-script<sub>s</sub>

Returns

  • If there is no match,either return

    • an error value, or
    • the match for und
  • Otherwise there is a match = language<sub>m</sub>-script<sub>m</sub>-region<sub>m</sub>

  • Let x<sub>r</sub> = x<sub>s</sub> if x<sub>s</sub> is not empty, and x<sub>m</sub> otherwise.

  • Return the language tag composed of language<sub>r</sub>-script<sub>r</sub>-region<sub>r</sub> + 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: []
}
Link to this function

script_from_locale(language_tag)

View Source (since 2.31.0)

Specs

script_from_locale(Cldr.LanguageTag.t() | locale_name()) :: script()

Returns the script 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 script to be used for localization purposes.

Examples

iex> Cldr.Locale.script_from_locale "en-US"
:Latn

iex> Cldr.Locale.script_from_locale "th"
:Thai
Link to this function

script_from_locale(locale, backend)

View Source (since 2.31.0)

Specs

script_from_locale(locale_reference(), Cldr.backend()) ::
  script() | {:error, {module(), String.t()}}

Returns the script 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 script to be used for localization purposes.

Examples

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

iex> Cldr.Locale.script_from_locale "th", TestBackend.Cldr
:Thai
Link to this function

substitute_aliases(language_tag)

View Source

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

Arguments

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 shsr_Latn or moro_MD. In such a case, the original script and/or region/territory are retained if there is one. Thus sh_Arab_AQsr_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: %{}
}
Link to this function

territory_from_host(host)

View Source (since 2.26.0)

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\""}}
Link to this function

territory_from_locale(language_tag)

View Source (since 2.18.2)

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.

Link to this function

territory_from_locale(locale, backend)

View Source (since 2.18.2)

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.

Link to this function

timezone_from_locale(language_tag)

View Source (since 2.19.0)

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"}}
Link to this function

timezone_from_locale(locale, backend)

View Source (since 2.19.0)

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

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"}}