View Source MyApp.Cldr (Cldr v2.39.2)
Provides the core functions to retrieve and manage the CLDR data that supports formatting and localisation.
It provides the core functions to access formatted CLDR data, set and retrieve a current locale and validate certain core data types such as locales, currencies and territories.
Summary
Functions
Returns the default locale
.
Returns the default territory when a locale does not specify one and none can be inferred.
Add locale-specific ellipsis to a string.
Return the current locale to be used for Cldr
functions that
take an optional locale parameter for which a locale is not supplied.
Returns either the Gettext locale_name
in Cldr format or
false
based upon whether the locale name is configured in
Gettext
.
Returns a boolean indicating if the specified locale name is configured and available in Gettext.
Returns a list of Gettext locale names but in CLDR format with
underscore replaced by hyphen in order to facilitate comparisons
with Cldr
locale names.
Returns either the locale_name
or false
based upon
whether the locale name is configured in Cldr
.
Returns a boolean indicating if the specified locale name is configured and available in Cldr.
Returns a list of the known locale names.
Returns a list of atoms representing the number systems types known to Cldr
.
Returns either the RBNF locale_name
or false
based upon
whether the locale name is configured in Cldr
and has RBNF rules defined.
Returns a boolean indicating if the specified locale name is configured and available in Cldr and supports rules based number formats (RBNF).
Returns a list of locale names which have rules-based number formats (RBNF).
Normalizes a string by applying transliteration of common symbols in numbers, currencies and dates
Set the current process's Gettext locale from a
t:Cldr.LanguageTag
.
Set the current locale to be used for Cldr
functions that
take an optional locale parameter for which a locale is not supplied.
Add locale-specific quotation marks around a string.
Returns a list of the locales names that are configured, but not known in CLDR.
Normalise and validate a locale name.
Normalise and validate a number system type.
Execute a function with a locale ensuring that the current locale is restored after the function.
Functions
@spec default_locale() :: Cldr.LanguageTag.t() | no_return()
Returns the default locale
.
Example
iex> MyApp.Cldr.default_locale()
%Cldr.LanguageTag{
backend: MyApp.Cldr,
canonical_locale_name: "en-001",
cldr_locale_name: :"en-001",
language_subtags: [],
extensions: %{},
gettext_locale_name: "en",
language: "en",
locale: %{},
private_use: [],
rbnf_locale_name: :en,
requested_locale_name: "en-001",
script: :Latn,
territory: :"001",
transform: %{},
language_variants: []
}
@spec default_territory() :: Cldr.Locale.territory_code()
Returns the default territory when a locale does not specify one and none can be inferred.
Example
iex> MyApp.Cldr.default_territory()
:"001"
Add locale-specific ellipsis to a string.
Arguments
string
is anyString.t
or a 2-element list ofString.t
between which the ellipsis is inserted.backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend!/0
. Note thatCldr.default_backend!/0
will raise an exception if no:default_backend
is configured under the:ex_cldr
key inconfig.exs
.options
is a keyword list of options
Options
:locale
is any valid locale name returned byCldr.known_locale_names/1
. The default isCldr.get_locale/0
.:location
determines where to place the ellipsis. The options are:after
(the default for a single string argument),:between
(the default and only valid location for an argument that is a list of two strings) and:before
.:format
formats based upon whether the ellipsis is inserted between words or sentences. The valid options are:word
or:sentence
. The default is:sentence
.
Examples
iex> MyApp.Cldr.ellipsis("And furthermore")
"And furthermore…"
iex> MyApp.Cldr.ellipsis(["And furthermore", "there is much to be done"], locale: :ja)
"And furthermore…there is much to be done"
iex> MyApp.Cldr.ellipsis("And furthermore", format: :word)
"And furthermore …"
iex> MyApp.Cldr.ellipsis(["And furthermore", "there is much to be done"], locale: :ja, format: :word)
"And furthermore … there is much to be done"
@spec get_locale() :: Cldr.LanguageTag.t()
Return the current locale to be used for Cldr
functions that
take an optional locale parameter for which a locale is not supplied.
Example
iex> MyApp.Cldr.put_locale("pl")
iex> MyApp.Cldr.get_locale()
%Cldr.LanguageTag{
backend: Elixir.MyApp.Cldr,
canonical_locale_name: "pl",
cldr_locale_name: :pl,
extensions: %{},
language: "pl",
locale: %{},
private_use: [],
rbnf_locale_name: :pl,
territory: :PL,
requested_locale_name: "pl",
script: :Latn,
transform: %{},
language_variants: []
}
Returns either the Gettext locale_name
in Cldr format or
false
based upon whether the locale name is configured in
Gettext
.
Arguments
locale
is any valid locale name returned byMyApp.Cldr.known_gettext_locale_names/0
Examples
iex> MyApp.Cldr.known_gettext_locale_name("en")
"en"
iex> MyApp.Cldr.known_gettext_locale_name("en-SA")
false
Returns a boolean indicating if the specified locale name is configured and available in Gettext.
Arguments
locale
is any valid locale name returned byMyApp.Cldr.known_locale_names/0
Examples
iex> MyApp.Cldr.known_gettext_locale_name?("en")
true
iex> MyApp.Cldr.known_gettext_locale_name?("!!")
false
@spec known_gettext_locale_names() :: [String.t()]
Returns a list of Gettext locale names but in CLDR format with
underscore replaced by hyphen in order to facilitate comparisons
with Cldr
locale names.
@spec known_locale_name(Cldr.Locale.locale_name()) :: String.t() | false
Returns either the locale_name
or false
based upon
whether the locale name is configured in Cldr
.
This is helpful when building a list of or
expressions
to return the first known locale name from a list.
Arguments
locale
is any valid locale name returned byMyApp.Cldr.known_locale_names/0
Examples
iex> MyApp.Cldr.known_locale_name(:"en-AU")
:"en-AU"
iex> MyApp.Cldr.known_locale_name(:"en-SA")
false
@spec known_locale_name?(Cldr.Locale.locale_name()) :: boolean()
Returns a boolean indicating if the specified locale name is configured and available in Cldr.
Arguments
locale
is any valid locale name returned byMyApp.Cldr.known_locale_names/0
Examples
iex> MyApp.Cldr.known_locale_name?(:en)
true
iex> MyApp.Cldr.known_locale_name?(:"!!")
false
Returns a list of the known locale names.
Known locales are those locales which
are the subset of all CLDR locales that
have been configured for use either
in this module or in Gettext
.
Returns a list of atoms representing the number systems types known to Cldr
.
Example
iex> MyApp.Cldr.known_number_system_types()
[:default, :finance, :native, :traditional]
@spec known_rbnf_locale_name(Cldr.Locale.locale_name()) :: String.t() | false
Returns either the RBNF locale_name
or false
based upon
whether the locale name is configured in Cldr
and has RBNF rules defined.
Arguments
locale
is any valid locale name returned byMyApp.Cldr.known_locale_names/0
Examples
iex> MyApp.Cldr.known_rbnf_locale_name(:en)
:en
iex> MyApp.Cldr.known_rbnf_locale_name(:"en-SA")
false
@spec known_rbnf_locale_name?(Cldr.Locale.locale_name()) :: boolean()
Returns a boolean indicating if the specified locale name is configured and available in Cldr and supports rules based number formats (RBNF).
Arguments
locale
is any valid locale name returned byMyApp.Cldr.known_locale_names/0
Examples
iex> MyApp.Cldr.known_rbnf_locale_name?(:en)
true
iex> MyApp.Cldr.known_rbnf_locale_name?(:"!!")
false
@spec known_rbnf_locale_names() :: [Cldr.Locale.locale_name()]
Returns a list of locale names which have rules-based number formats (RBNF).
Normalizes a string by applying transliteration of common symbols in numbers, currencies and dates
@spec put_gettext_locale(Cldr.LanguageTag.t()) :: {:ok, binary() | nil} | {:error, {module(), String.t()}}
Set the current process's Gettext locale from a
t:Cldr.LanguageTag
.
Arguments
locale
is aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
.
Returns
{:ok, gettext_locale_name}
or{:error, {exception, reason}}
Behaviour
If the
locale.gettext_locale_name
isnil
then an error is returned.The
gettext
locale for thegettext_backend
configured for the CLDR backend defined by thet:Cldr.LanguageTag
is set.
Examples
iex> import Cldr.LanguageTag.Sigil
iex> MyApp.Cldr.put_gettext_locale(~l"en")
{:ok, "en"}
iex> import Cldr.LanguageTag.Sigil
iex> MyApp.Cldr.put_gettext_locale(~l"de")
{
:error,
{
Cldr.UnknownLocaleError,
"Locale TestBackend.Cldr.Locale.new!(\"de-DE\") does not map to a known gettext locale name"
}
}
@spec put_locale(Cldr.Locale.locale_reference()) :: {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}
Set the current locale to be used for Cldr
functions that
take an optional locale parameter for which a locale is not supplied.
Arguments
locale
is any valid locale name returned byMyApp.Cldr.known_locale_names/0
or at:Cldr.LanguageTag
struct returned byMyApp.Cldr.Locale.new!/1
See rfc5646 for the specification of a language tag.
Examples
iex> MyApp.Cldr.put_locale("en")
{:ok,
%Cldr.LanguageTag{
backend: MyApp.Cldr,
canonical_locale_name: "en",
cldr_locale_name: :en,
language_subtags: [],
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: []
}}
iex> MyApp.Cldr.put_locale("invalid-locale!")
{:error, {Cldr.LanguageTag.ParseError,
"Expected a BCP47 language tag. Could not parse the remaining \"!\" starting at position 15"}}
Add locale-specific quotation marks around a string.
Arguments
string
is any valid Elixir stringoptions
is a keyword list of options
Options
locale
is any valid locale name returned byCldr.known_locale_names/1
. The default isCldr.get_locale/0
Examples
iex> MyApp.Cldr.quote("Quoted String")
"“Quoted String”"
iex> MyApp.Cldr.quote("Quoted String", locale: :ja)
"「Quoted String」"
@spec unknown_locale_names() :: [Cldr.Locale.locale_name()]
Returns a list of the locales names that are configured, but not known in CLDR.
Since there is a compile-time exception raised if there are any unknown locales this function should always return an empty list.
@spec validate_locale(Cldr.Locale.locale_name() | Cldr.LanguageTag.t() | String.t()) :: {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}
Normalise and validate a locale name.
Arguments
locale
is any valid locale name returned byMyApp.Cldr.known_locale_names/0
or aCldr.LanguageTag
struct returned byMyApp.Cldr.Locale.new!/1
Returns
{:ok, language_tag}
{:error, reason}
Notes
See rfc5646 for the specification of a language tag.
Examples
iex> MyApp.Cldr.validate_locale(:en)
{:ok,
%Cldr.LanguageTag{
backend: MyApp.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: []
}}
iex> MyApp.Cldr.validate_locale MyApp.Cldr.default_locale()
{:ok,
%Cldr.LanguageTag{
backend: MyApp.Cldr,
canonical_locale_name: "en-001",
cldr_locale_name: :"en-001",
extensions: %{},
gettext_locale_name: "en",
language: "en",
locale: %{},
private_use: [],
rbnf_locale_name: :en,
requested_locale_name: "en-001",
script: :Latn,
territory: :"001",
transform: %{},
language_variants: []
}}
iex> MyApp.Cldr.validate_locale("zzz")
{:error, {Cldr.InvalidLanguageError, "The language \"zzz\" is invalid"}}
@spec validate_number_system_type(String.t() | atom()) :: {:ok, atom()} | {:error, {module(), String.t()}}
Normalise and validate a number system type.
Arguments
number_system_type
is any number system type returned byCldr.known_number_system_types/1
Returns
{:ok, normalized_number_system_type}
or{:error, {exception, message}}
Examples
iex> MyApp.Cldr.validate_number_system_type(:default)
{:ok, :default}
iex> MyApp.Cldr.validate_number_system_type(:traditional)
{:ok, :traditional}
iex> MyApp.Cldr.validate_number_system_type(:latn)
{
:error,
{Cldr.UnknownNumberSystemTypeError, "The number system type :latn is unknown"}
}
iex> MyApp.Cldr.validate_number_system_type("bork")
{
:error,
{Cldr.UnknownNumberSystemTypeError, "The number system type \"bork\" is invalid"}
}
@spec with_locale(Cldr.Locale.locale_reference(), (-> any())) :: any()
Execute a function with a locale ensuring that the current locale is restored after the function.
Arguments
locale
is any valid locale name returned byCldr.known_locale_names/1
.fun
is any 0-arity function or function capture.
Returns
The value returned by the function
fun/0
or{:error, {exception, reason}}
if the locale is invalid orraises an exception if the current locale cannot be identified.