# `Cldr.Locale` [🔗](https://github.com/elixir-cldr/cldr/blob/v2.47.3/lib/cldr/locale.ex#L1) 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](https://tools.ietf.org/html/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 Territory 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 China" local name. Here `Cldr` will match to the nearest configured locale, which in this case will be "en". iex> Cldr.Locale.new("en-CN", TestBackend.Cldr) {:ok, %Cldr.LanguageTag{ backend: TestBackend.Cldr, canonical_locale_name: "en-CN", cldr_locale_name: :"en-GB", extensions: %{}, gettext_locale_name: "en_GB", language: "en", locale: %{}, private_use: [], rbnf_locale_name: :en, requested_locale_name: "en-CN", script: :Latn, territory: :CN, 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 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-GB", extensions: %{}, gettext_locale_name: "en_GB", 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](https://unicode.org/reports/tr35/#Locale_Extension_Key_and_Type_Data) 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_GB", 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: %{} } } # `language` ```elixir @type language() :: String.t() | nil ``` The name of a language # `locale_name` ```elixir @type locale_name() :: atom() ``` The name of a locale # `locale_reference` ```elixir @type locale_reference() :: Cldr.LanguageTag.t() | locale_name() | String.t() ``` A reference to a locale # `script` ```elixir @type script() :: atom() | String.t() | nil ``` The name of a script # `script_direction` ```elixir @type script_direction() :: :ltr | :rtl ``` The direction in which a script is rendered # `subdivision_code` ```elixir @type subdivision_code() :: String.t() ``` A territory subdiviiosn code as a string # `subtags` ```elixir @type subtags() :: [String.t(), ...] | [] ``` The list of language subtags as strings # `territory_code` ```elixir @type territory_code() :: atom() ``` A territory code as an ISO3166 Alpha-2 in atom form # `territory_reference` ```elixir @type territory_reference() :: atom() | String.t() | nil ``` The name of a territory # `variants` ```elixir @type variants() :: [String.t()] | [] ``` The list of language variants as strings # `aliases` ```elixir @spec aliases() :: %{ script: %{required(script_alias :: String.t()) => script :: String.t()}, language: %{ required(language :: String.t()) => language_tag :: Cldr.LanguageTag.t() }, zone: %{ required(zone_alias :: String.t()) => String.t() | %{required(city :: String.t()) => zone :: String.t()} }, subdivision: %{ required(subdivision_alias :: String.t()) => subdivision :: territory_code() | subdivision_code() | [subdivision_code(), ...] }, variant: %{required(variant_alias :: String.t()) => variant :: String.t()}, region: %{required(region_alias :: String.t()) => region :: String.t()} } ``` Return a map of the known aliases for Language, Script and Territory # `aliases` ```elixir @spec 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) # `canonical_language_tag` ```elixir @spec 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` that determines 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](https://tools.ietf.org/html/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: [] } } # `canonical_language_tag!` ```elixir @spec 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. # `cldr_locale_name` ```elixir @spec cldr_locale_name(Cldr.LanguageTag.t()) :: locale_name() | nil ``` # `consider_as_tlds` 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] # `fallback_locale_names` *since 2.26.0* ```elixir @spec fallback_locale_names(Cldr.LanguageTag.t()) :: {:ok, [locale_name(), ...]} | {:error, {module(), binary()}} ``` Returns the list of fallback locale names, starting with 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. ### Arguments * `locale` is any `t:Cldr.LanguageTag.t/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(Cldr.Locale.new!("fr-CA", MyApp.Cldr)) {:ok, [:"fr-CA", :fr, :und]} # 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, :und]} # `fallback_locale_names` *since 2.26.0* ```elixir @spec 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. ### 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, :und]} # 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, :und]} # `fallback_locale_names!` Returns the list of fallback locale names, starting with 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. ### Arguments * `locale` is any `t:Cldr.LanguageTag.t/0` ### 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, :und] # 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, :und] # `fallback_locales` *since 2.26.0* ```elixir @spec 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. ### Arguments * `locale` is any `t:Cldr.LanguageTag.t/0` ### Returns * `{:ok, list_of_locales}` or * `{:error, {exception, reason}}` ### Examples Cldr.Locale.fallback_locales(Cldr.Locale.new!("fr-CA", MyApp.Cldr)) => {:ok, [#Cldr.LanguageTag, #Cldr.LanguageTag, #Cldr.LanguageTag]} # 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, #Cldr.LanguageTag, #Cldr.LanguageTag]} # `fallback_locales` *since 2.26.0* ```elixir @spec 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. ### 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 Cldr.Locale.fallback_locales(:"fr-CA") => {:ok, [#Cldr.LanguageTag, #Cldr.LanguageTag, #Cldr.LanguageTag]} # 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, #Cldr.LanguageTag, #Cldr.LanguageTag]} # `first_match` 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/2` is 2-arity function that takes a string locale name and subtags. The locale name is a built from the language, script, territory and variant combinations of `language_tag`. * `omit_singular_script?` is a boolean indicating if a match should fail if the language tag script is the only (default) script for the language. The default is `false`. ### Returns * The first `truthy` value returned by `fun/2` or `nil` if no match is made. # `is_locale_name` *macro* # `language_data` Mapping of language data to known scripts and territories # `languages_for_territories` *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", ... } # `likely_subtags` 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: [] }, ... # `likely_subtags` ```elixir @spec likely_subtags(locale_name() | String.t() | Cldr.LanguageTag.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 `t:Cldr.LanguageTag.t/0` 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: [] } # `locale_for_territory` *since 2.26.0* ```elixir @spec 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"}} # `locale_from_host` *since 2.26.0* ```elixir @spec 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, language_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\""}} # `locale_name_from` 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" # `locale_name_from` ```elixir @spec 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-Latn-001" iex> Cldr.Locale.locale_name_from("en", :Latn, :"001", []) "en-Latn-001" # `locale_name_from_posix` # `locale_name_to_posix` # `new` # `new!` # `omit_likely_subtags` # `parent` ```elixir @spec 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](https://unicode.org/reports/tr35/#Locale_Inheritance). 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. # `parent` ```elixir @spec parent(locale_name(), Cldr.backend()) :: {:ok, Cldr.LanguageTag.t()} | {:error, {module(), binary()}} ``` # `parent_locale_map` Returns mappings between a locale and its parent. The mappings exist only where normal inheritance rules are not applied. # `parents` Returns a list of all the parent locales for a given locale. ### Examples Cldr.Locale.parents "fr-ca" => {:ok, [#Cldr.LanguageTag, #Cldr.LanguageTag]} # `put_likely_subtags` Replace empty subtags within a `t: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: xs is in the source, xm is in a match, and xr is in the final result. ### Lookup Lookup each of the following in order, and stops on the first match: * languages-scripts-regions * languages-regions * languages-scripts * languages * und-scripts ### Returns * If there is no match,either return * an error value, or * the match for `und` * Otherwise there is a match = languagem-scriptm-regionm * Let xr = xs if xs is not empty, and xm otherwise. * Return the language tag composed of languager-scriptr-regionr + 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: [] } # `root_language` Returns the root language for CLDR. # `script_direction_from_locale` *since 2.37.0* ```elixir @spec script_direction_from_locale(Cldr.LanguageTag.t() | locale_name()) :: script_direction() ``` Returns the script direction 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 direction which is either `:ltr` (for left-to-right scripts) or `:rtl` (for right-to-left scripts). ### Examples iex> Cldr.Locale.script_direction_from_locale "en-US" :ltr iex> Cldr.Locale.script_direction_from_locale "ar" :rtl # `script_direction_from_locale` *since 2.37.0* ```elixir @spec script_direction_from_locale(locale_reference(), Cldr.backend()) :: script_direction() | {:error, {module(), String.t()}} ``` Returns the script direction 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 direction which is either `:ltr` (for left-to-right scripts) or `:rtl` (for right-to-left scripts). ### Examples iex> Cldr.Locale.script_direction_from_locale :"en-US", TestBackend.Cldr :ltr iex> Cldr.Locale.script_direction_from_locale :he, TestBackend.Cldr :rtl # `script_from_locale` *since 2.31.0* ```elixir @spec 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 # `script_from_locale` *since 2.31.0* ```elixir @spec 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 # `substitute_aliases` 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: %{} } # `territory_from_host` *since 2.26.0* ```elixir @spec 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\""}} # `territory_from_locale` *since 2.18.2* ```elixir @spec territory_from_locale(Cldr.LanguageTag.t() | locale_name() | String.t()) :: territory_code() | {:error, {module(), String.t()}} ``` 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](https://unicode.org/reports/tr35/#u_Extension) is used to define a [regional override](https://unicode.org/reports/tr35/#RegionOverride). 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. # `territory_from_locale` *since 2.18.2* ```elixir @spec 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](https://unicode.org/reports/tr35/#u_Extension) is used to define a [regional override](https://unicode.org/reports/tr35/#RegionOverride). 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. # `timezone_from_locale` *since 2.19.0* ```elixir @spec 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 `t:String.t/0` or `{:error, {exception, reason}}` ### Examples iex> Cldr.Locale.timezone_from_locale("en-US-u-tz-ausyd") "Australia/Sydney" iex> Cldr.Locale.timezone_from_locale("de-CH") "Europe/Zurich" iex> Cldr.Locale.timezone_from_locale("en-AU") {:error, {Cldr.AmbiguousTimezoneError, "Cannot determine the timezone since the territory :AU has 12 timezone IDs"}} # `timezone_from_locale` *since 2.19.0* ```elixir @spec 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 `t:String.t/0` 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 12 timezone IDs"}} --- *Consult [api-reference.md](api-reference.md) for complete listing*