View Source Cldr.Locale (Cldr v2.37.1)
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
orfr
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
anden-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
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
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
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
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
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
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 direction in which a script is rendered
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 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 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 from a Cldr.LanguageTag
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 root language for CLDR.
Returns the script direction for a locale.
Returns the script direction for a locale.
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
@type language() :: String.t() | nil
The name of a language
@type locale_name() :: atom()
The name of a locale
@type locale_reference() :: Cldr.LanguageTag.t() | locale_name() | String.t()
A reference to a locale
The name of a script
@type script_direction() :: :ltr | :rtl
The direction in which a script is rendered
@type subtags() :: [String.t(), ...] | []
The list of language subtags as strings
@type territory_code() :: atom()
A territory code as an ISO3166 Alpha-2 in atom form
The name of a territory
@type variants() :: [String.t()] | []
The list of language variants as strings
Link to this section Functions
@spec aliases() :: map()
Return a map of the known aliases for Language, Script and Territory
@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
Options
type
is one of[:language, :region, :script, :variant, :zone]
key
is the substitution key (a language, region, script, variant or zone)
@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
Arguments
language_tag
is any language tag returned byCldr.Locale.new/2
or anylocale_name
returned byCldr.known_locale_names/1
backend
is any module that includesuse Cldr
and therefore is aCldr
backend moduleoptions
is a keyword list of options
options
Options
:add_likely_subtags
is aboolean
thatdetermines if subtags that are likely to be applicable to this language tag are added to the language tag. The default istrue
.
returns
Returns
{:ok, language_tag}
or{:error, reason}
method
Method
The language tag is parsed in accordance with RFC5646
Any language, script or region aliases are replaced. This will replace any obsolete elements with current versions.
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
istrue
(the default).A
Cldr
locale name is selected that is the nearest fit to the requested locale.
example
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: []
}
}
@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
Arguments
language_tag
is any language tag returned byCldr.Locale.new/2
or anylocale_name
returned byCldr.known_locale_names/1
backend
is any module that includesuse Cldr
and therefore is aCldr
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
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]
@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
Arguments
locale
is anyLanguageTag.t
returns
Returns
{:ok, list_of_locale_names}
or{:error, {exception, reason}}
examples
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(locale_name, backend \\ Cldr.default_backend!())
View Source (since 2.26.0)@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
Arguments
locale_name
is any locale name returned byCldr.known_locale_names/1
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_locale/0
.
returns
Returns
{:ok, list_of_locale_names}
or{:error, {exception, reason}}
examples
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]}
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
Arguments
locale
is anyLanguageTag.t
returns
Returns
list_of_locale_names
orraises an exception
examples
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]
@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
Arguments
locale
is anyLanguageTag.t
returns
Returns
{:ok, list_of_locales}
or{:error, {exception, reason}}
examples
Examples
Cldr.Locale.fallback_locales(Cldr.Locale.new!("fr-CA", MyApp.Cldr))
=> {:ok,
[#Cldr.LanguageTag<fr-CA [validated]>, #Cldr.LanguageTag<fr [validated]>,
#Cldr.LanguageTag<und [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<und [validated]>]}
fallback_locales(locale_name, backend \\ Cldr.default_backend!())
View Source (since 2.26.0)@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
Arguments
locale_name
is any locale name returned byCldr.known_locale_names/1
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_locale/0
.
returns
Returns
{:ok, list_of_locales}
or{:error, {exception, reason}}
examples
Examples
Cldr.Locale.fallback_locales(:"fr-CA")
=> {:ok,
[#Cldr.LanguageTag<fr-CA [validated]>, #Cldr.LanguageTag<fr [validated]>,
#Cldr.LanguageTag<und [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<und [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
Arguments
language_tag
is any language tag returned byCldr.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 oflanguage_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 lanaguge. The default isfalse
.
returns
Returns
- The first
truthy
value returned byfun/2
ornil
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
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
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: []
},
...
@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
Options
locale
is any valid locale name returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct
examples
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(territory, backend \\ Cldr.default_backend!())
View Source (since 2.26.0)@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
Arguments
territory
is any ISO 3166 Alpha-2 territory code that can be validated byCldr.validate_territory/1
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module.
returns
Returns
{:ok, language_tag}
or{:error, {exception, reason}}
examples
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"}}
@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
Arguments
host
is any valid host namebackend
is any module that includesuse Cldr
and therefore is aCldr
backend module.options
is a keyword list of options. The default is[tlds: Cldr.Locale.consider_as_tlds()]
.
options
Options
:tlds
is a list of territory codes as upper-cased atoms that are to be considered as top-level domains. The default list isconsider_as_tlds/0
.
returns
Returns
{:ok, langauge_tag}
or{:error, {exception, reason}}
notes
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
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
Options
locale_name
is anyCldr.LanguageTag
struct returned byCldr.Locale.new!/2
example
Example
iex> Cldr.Locale.locale_name_from Cldr.Locale.new!("en", TestBackend.Cldr)
"en"
locale_name_from(language, script, territory, variants, omit_singular_script? \\ true)
View Source@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
Arguments
language
is a string representing a valid language codescript
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
Returns
- The atom locale name constructed from the non-nil arguments joined by a "-".
example
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"
@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.
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
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.
@spec 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
Examples
Cldr.Locale.parents "fr-ca"
=> {:ok, [#Cldr.LanguageTag<fr [validated]>, #Cldr.LanguageTag<en [validated]>]}
@spec put_gettext_locale_name(Cldr.LanguageTag.t()) :: Cldr.LanguageTag.t()
@spec 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
Arguments
language_tag
is any language tag returned byCldr.Locale.new/2
options
is a keyword list of options
options
Options
:add_likely
is a boolean indicating whether to add likely subtags. The default istrue
.
notes
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
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
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
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: []
}
Returns the root language for CLDR.
@spec script_direction_from_locale(Cldr.LanguageTag.t() | locale_name()) :: script_direction()
Returns the script direction for a locale.
arguments
Arguments
language_tag
is any language tag returned byCldr.Locale.new/2
or anylocale_name
returned byCldr.known_locale_names/1
. If the parameter is alocale_name
then a default backend must be configured inconfig.exs
or an exception will be raised.
returns
Returns
- The script direction which is either
:ltr
(for left-to-right scripts) or:rtl
(for right-to-left scripts).
examples
Examples
iex> Cldr.Locale.script_direction_from_locale "en-US"
:ltr
iex> Cldr.Locale.script_direction_from_locale "ar"
:rtl
@spec script_direction_from_locale(locale_reference(), Cldr.backend()) :: script_direction() | {:error, {module(), String.t()}}
Returns the script direction for a locale.
arguments
Arguments
locale_name
is any locale name returned byCldr.known_locale_names/1
.backend
is any module that includesuse Cldr
and therefore is aCldr
backend module.
returns
Returns
- The script direction which is either
:ltr
(for left-to-right scripts) or:rtl
(for right-to-left scripts).
examples
Examples
iex> Cldr.Locale.script_direction_from_locale :"en-US", TestBackend.Cldr
:ltr
iex> Cldr.Locale.script_direction_from_locale :he, TestBackend.Cldr
:rtl
@spec script_from_locale(Cldr.LanguageTag.t() | locale_name()) :: script()
Returns the script for a locale.
arguments
Arguments
language_tag
is any language tag returned byCldr.Locale.new/2
or anylocale_name
returned byCldr.known_locale_names/1
. If the parameter is alocale_name
then a default backend must be configured inconfig.exs
or an exception will be raised.
returns
Returns
- The script to be used for localization purposes.
examples
Examples
iex> Cldr.Locale.script_from_locale "en-US"
:Latn
iex> Cldr.Locale.script_from_locale "th"
:Thai
@spec script_from_locale(locale_reference(), Cldr.backend()) :: script() | {:error, {module(), String.t()}}
Returns the script for a locale.
arguments
Arguments
locale_name
is any locale name returned byCldr.known_locale_names/1
.backend
is any module that includesuse Cldr
and therefore is aCldr
backend module.
returns
Returns
- The script to be used for localization purposes.
examples
Examples
iex> Cldr.Locale.script_from_locale "en-US", TestBackend.Cldr
:Latn
iex> Cldr.Locale.script_from_locale "th", TestBackend.Cldr
:Thai
Substitute deprecated subtags with a Cldr.LanguageTag
with their
non-deprecated alternatives.
arguments
Arguments
language_tag
is any language tag returned byCldr.Locale.new/2
method
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
ormo
➞ro_MD
. In such a case, the original script and/or region/territory are retained if there is one. Thussh_Arab_AQ
➞sr_Arab_AQ
, notsr_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
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: %{}
}
@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
Arguments
host
is any valid host name
returns
Returns
{:ok, territory}
or{:error, {exception, reason}}
examples
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\""}}
@spec territory_from_locale(Cldr.LanguageTag.t() | locale_name() | String.t()) :: territory_code()
Returns the effective territory for a locale.
arguments
Arguments
language_tag
is any language tag returned byCldr.Locale.new/2
or anylocale_name
returned byCldr.known_locale_names/1
. If the parameter is alocale_name
then a default backend must be configured inconfig.exs
or an exception will be raised.
returns
Returns
- The territory to be used for localization purposes.
examples
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
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:
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 asen-US
ores-AR
are used.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.
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.
@spec territory_from_locale(locale_reference() | String.t(), Cldr.backend()) :: territory_code() | {:error, {module(), String.t()}}
Returns the effective territory for a locale.
arguments
Arguments
locale_name
is any locale name returned byCldr.known_locale_names/1
.backend
is any module that includesuse Cldr
and therefore is aCldr
backend module.
returns
Returns
- The territory to be used for localization purposes or
{:error, {exception, reason}}
.
examples
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
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:
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 asen-US
ores-AR
are used.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.
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.
@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
Arguments
language_tag
is any language tag returned byCldr.Locale.new/2
or anylocale_name
returned byCldr.known_locale_names/1
. If the parameter is alocale_name
then a default backend must be configured inconfig.exs
or an exception will be raised.
returns
Returns
- The time zone ID as a
String.t
or{:error, {exception, reason}}
examples
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"}}
@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
Arguments
locale_name
is any name returned byCldr.known_locale_names/1
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module
returns
Returns
- The time zone ID as a
String.t
or{:error, {exception, reason}}
examples
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"}}