View Source MyApp.Cldr (Cldr v2.40.0)

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

Link to this function

available_locale_name?(locale_name)

View Source

See Cldr.available_locale_name?/1.

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

ellipsis(string, options \\ [])

View Source
@spec ellipsis(String.t() | [String.t()], Keyword.t()) :: String.t()

Add locale-specific ellipsis to a string.

Arguments

  • string is any String.t or a 2-element list of String.t between which the ellipsis is inserted.

  • backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0. Note that Cldr.default_backend!/0 will raise an exception if no :default_backend is configured under the :ex_cldr key in config.exs.

  • options is a keyword list of options

Options

  • :locale is any valid locale name returned by Cldr.known_locale_names/1. The default is Cldr.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: []
 }

See Cldr.known_calendars/0.

See Cldr.known_currencies/0.

Link to this function

known_gettext_locale_name(locale_name)

View Source
@spec known_gettext_locale_name(String.t()) :: String.t() | false

Returns either the Gettext locale_name in Cldr format or false based upon whether the locale name is configured in Gettext.

Arguments

Examples

iex> MyApp.Cldr.known_gettext_locale_name("en")
"en"

iex> MyApp.Cldr.known_gettext_locale_name("en-SA")
false
Link to this function

known_gettext_locale_name?(locale_name)

View Source
@spec known_gettext_locale_name?(String.t()) :: boolean()

Returns a boolean indicating if the specified locale name is configured and available in Gettext.

Arguments

Examples

iex> MyApp.Cldr.known_gettext_locale_name?("en")
true

iex> MyApp.Cldr.known_gettext_locale_name?("!!")
false
Link to this function

known_gettext_locale_names()

View Source
@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.

Link to this function

known_locale_name(locale_name)

View Source
@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

Examples

iex> MyApp.Cldr.known_locale_name(:"en-AU")
:"en-AU"

iex> MyApp.Cldr.known_locale_name(:"en-SA")
false
Link to this function

known_locale_name?(locale_name)

View Source
@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

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.

Link to this function

known_number_system_types()

View Source

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]

See Cldr.known_number_systems/0.

Link to this function

known_rbnf_locale_name(locale_name)

View Source
@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

Examples

iex> MyApp.Cldr.known_rbnf_locale_name(:en)
:en

iex> MyApp.Cldr.known_rbnf_locale_name(:"en-SA")
false
Link to this function

known_rbnf_locale_name?(locale_name)

View Source
@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

Examples

iex> MyApp.Cldr.known_rbnf_locale_name?(:en)
true

iex> MyApp.Cldr.known_rbnf_locale_name?(:"!!")
false
Link to this function

known_rbnf_locale_names()

View Source
@spec known_rbnf_locale_names() :: [Cldr.Locale.locale_name()]

Returns a list of locale names which have rules-based number formats (RBNF).

See Cldr.known_territories/0.

Link to this function

normalize_lenient_parse(string, scope, locale \\ get_locale())

View Source

Normalizes a string by applying transliteration of common symbols in numbers, currencies and dates

Link to this function

put_gettext_locale(locale)

View Source (since 2.38.0)
@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

Returns

  • {:ok, gettext_locale_name} or

  • {:error, {exception, reason}}

Behaviour

  1. If the locale.gettext_locale_name is nil then an error is returned.

  2. The gettext locale for the gettext_backend configured for the CLDR backend defined by the t: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

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

quote(string, options \\ [])

View Source
@spec quote(String.t(), Keyword.t()) :: String.t()

Add locale-specific quotation marks around a string.

Arguments

  • string is any valid Elixir string

  • options is a keyword list of options

Options

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.

Link to this function

validate_calendar(calendar)

View Source

See Cldr.validate_calendar/1.

Link to this function

validate_currency(currency)

View Source

See Cldr.validate_currency/1.

@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

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

validate_number_system(number_system)

View Source

See Cldr.validate_number_system/1.

Link to this function

validate_number_system_type(number_system_type)

View Source
@spec validate_number_system_type(String.t() | atom()) ::
  {:ok, atom()} | {:error, {module(), String.t()}}

Normalise and validate a number system type.

Arguments

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

validate_territory(territory)

View Source

See Cldr.validate_territory/1.

Link to this function

with_locale(locale, fun)

View Source (since 2.32.0)
@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

Returns

  • The value returned by the function fun/0 or

  • {:error, {exception, reason}} if the locale is invalid or

  • raises an exception if the current locale cannot be identified.