Cldr v0.0.8 Cldr.Config

Locales are configured for use in Cldr by either specifying them directly or by using a configured Gettext module.

Locales are configured in config.exs (or any included config). For example the following will configure English and French as the available locales. Note that only locales that are contained within the CLDR repository will be available for use. There are currently 511 locales defined in CLDR.

config :ex_cldr,
  locales: ["en", "fr"]

Working with Gettext

It’s also possible to use the locales from a Gettext configuration:

config :ex_cldr,
  locales: ["en", "fr"]
  gettext: App.Gettext

In which case the combination of locales “en”, “fr” and whatever is configured for App.Gettext will be generated.

Locale wildcards

Locales can also be configured by using a regex which is most useful when dealing with locales that have many regional variants like English (over 100!) and French. For example:

config :ex_cldr,
  locales: ["fr-*", "en-[A-Z]+"]

will configure all French locales and all English locales that have alphabetic regional variants. The expansion is made using Regex.match? so any valid regex can be used.

Configuring all locales

As a special case, all locales in CLDR can be configured by using the keyword :all. For example:

config :ex_cldr,
  locales: :all

Configuring all locales is not recommended*. Doing so imposes a significant compilation load as many functions are created at compmile time for each locale.

The Cldr test configuration does configure all locales in order to ensure good test coverage. This is done at the expense of significant compile time.

Storage location for the locale definiton files

Locale files are downloaded and installed at compile time based upon the configuration. These files are only used at compile time, they contain the json representation of the locale data.

By default the locale files are stored in ./priv/cldr/locales.

The locale of the locales can be changed in the configuration with the :data_dir key. For example:

config :ex_cldr,
  locales: ["en", "fr"]
  data_dir: "/apps/data/cldr"

The directory will be created if it does not exist and an exception will be raised if the directory cannot be created.

Summary

Functions

Returns a list of all locales in the CLDR repository

Return the directory where Cldr stores its core data

Return the root path of the cldr application

Returns a list of all locales configured in the config.exs file

Return the path name of the CLDR data directory for a client application

Return the default locale

Expands wildcards in locale names

Read the locale json, decode it and make any necessary transformations

Return the configured Gettext module name or nil

Returns true if a Gettext module is configured in Cldr and the Gettext module is available

Return a list of the lcoales defined in Gettext

Returns a list of all locales that are configured and available in the CLDR repository

Returns the location of the json data for a locale or nil if the locale can’t be found

Returns a list of all configured locales

Returns a list of all locales that are configured but not available in the CLDR repository

Types

t()
t :: binary

Functions

all_locales()
all_locales :: [Cldr.Locale.t]

Returns a list of all locales in the CLDR repository.

Returns a list of the complete locales list in CLDR, irrespective of whether they are configured for use in the application.

Any configured locales that are not present in this list will raise an exception at compile time.

cldr_data_dir()

Return the directory where Cldr stores its core data

cldr_home()

Return the root path of the cldr application

configured_locales()
configured_locales :: [Cldr.Locale.t]

Returns a list of all locales configured in the config.exs file.

In order of priority return either:

  • The list of locales configured configured in mix.exs if any

  • The default locale

If the configured locales is :all then all locales in CLDR are configured.

The locale “root” is always added to the list of configured locales since it is required to support some RBNF functions.

This is not recommended since all 514 locales take quite some time (minutes) to compile. It is however helpful for testing Cldr.

data_dir()

Return the path name of the CLDR data directory for a client application.

default_locale()
default_locale :: Cldr.Locale.t

Return the default locale.

In order of priority return either:

  • The default locale specified in the mix.exs file
  • The Gettext.get_locale/1 for the current configuratioh
  • “en”
expand_locales(locales)
expand_locales([Cldr.Locale.t]) :: [Cldr.Locale.t]

Expands wildcards in locale names.

Locales often have region variants (for example en-AU is one of 104 variants in CLDR). To make it easier to configure a language and all its variants, a locale can be specified as a regex which will then do a match against all CLDR locales.

Examples

iex> Cldr.Config.expand_locales(["en-A+"])
["en-AG", "en-AI", "en-AS", "en-AT", "en-AU"]

iex(15)> Cldr.Config.expand_locales(["fr-*"])
["fr", "fr-BE", "fr-BF", "fr-BI", "fr-BJ", "fr-BL", "fr-CA", "fr-CD", "fr-CF",
 "fr-CG", "fr-CH", "fr-CI", "fr-CM", "fr-DJ", "fr-DZ", "fr-GA", "fr-GF",
 "fr-GN", "fr-GP", "fr-GQ", "fr-HT", "fr-KM", "fr-LU", "fr-MA", "fr-MC",
 "fr-MF", "fr-MG", "fr-ML", "fr-MQ", "fr-MR", "fr-MU", "fr-NC", "fr-NE",
 "fr-PF", "fr-PM", "fr-RE", "fr-RW", "fr-SC", "fr-SN", "fr-SY", "fr-TD",
 "fr-TG", "fr-TN", "fr-VU", "fr-WF", "fr-YT"]
get_locale(locale)

Read the locale json, decode it and make any necessary transformations.

This is the only place that we read the locale and we only read it once. All other uses of locale data are references to this data.

Additionally the intention is that this is read only at compile time and used to construct accessor functions in other modules so that during production run there is no file access or decoding.

If a locale file is not found then it is installed.

gettext()
gettext :: atom

Return the configured Gettext module name or nil.

gettext_configured?()
gettext_configured? :: boolean

Returns true if a Gettext module is configured in Cldr and the Gettext module is available.

Example

iex> Cldr.Config.gettext_configured?
false
gettext_locales()
gettext_locales :: [Cldr.Locale.t]

Return a list of the lcoales defined in Gettext.

Return a list of locales configured in Gettext or [] if Gettext is not configured.

known_locales()
known_locales :: [Cldr.Locale.t]

Returns a list of all locales that are configured and available in the CLDR repository.

locale_path(locale)

Returns the location of the json data for a locale or nil if the locale can’t be found.

  • locale is any locale returned from Cldr.known_locales()`
requested_locales()
requested_locales :: [Cldr.Locale.t]

Returns a list of all configured locales.

The list contains locales configured both in Gettext and specified in the mix.exs configuration file as well as the default locale.

unknown_locales()
unknown_locales :: [Cldr.Locale.t]

Returns a list of all locales that are configured but not available in the CLDR repository.