ex_cldr

Because CLDR data is massive, ex_cldr uses a provider system to allow you to include only the functionality you need (e.g., just numbers, or just dates).

• To include specific functionality: List the provider modules in the :providers key of your backend module.
• To include everything installed: If :providers is nil (the default), ex_cldr will attempt to configure all known providers that are present in your deps.
• To include nothing: Set :providers to [].

defmodule MyApp.Cldr do
  use Cldr,
    locales: ["en", "zh"],
    default_locale: "en",
    providers: [Cldr.Number, Cldr.List]
end

The U extension allows you to request specific treatments for CLDR data formats within a locale string. Supported keys vary by library, but ex_cldr_numbers (v2.10+) supports:

• cf: currency format
• cu: currency
• nu: number system

Example of a complex locale requesting a specific timezone and accounting currency format: en-AU-u-tz-ausyd-cf-account

# Validating a locale with extensions
MyApp.Cldr.validate_locale "en-AU-u-tz-ausyd-cf-account"
# Returns %Cldr.LanguageTag{} with extensions populated

ex_cldr uses IETF standard locale strings (RFC5646) using hyphens (-) as separators, rather than the POSIX underscore (_) convention.

Conventions:

• Language codes: lower-case
• Territory codes: UPPER-CASE
• Script names: Capital-case
• Other subtags: lower-case

Key Functions:

• Cldr.known_locale_names(backend): Returns locales known to your specific configuration.
• Cldr.all_locale_names(): Returns all locales available in the CLDR data repository.
• Locales are always handled as binary strings in the API, but parsed internally into %Cldr.LanguageTag{} structs.

To use ex_cldr, you must define a module to host your configuration (such as supported locales and the default locale) and serve as your public API. This module is referred to as a backend module. Using a backend module allows different parts of an application to have isolated configurations without interference.

defmodule MyApp.Cldr do
  @moduledoc """
  Define a backend module that will host our
  Cldr configuration and public API.

  Most function calls in Cldr will be calls
  to functions on this module.
  """
  use Cldr,
    locales: ["en", "fr", "zh", "th"],
    default_locale: "en"

end

The CLDR toolchain requires a GitHub token with the read:packages scope to function. You must add this token to your Maven settings.xml file.

1. Generate a token at https://github.com/settings/tokens with the read:packages scope.
2. Modify or create $HOME/.m2/settings.xml.
3. Add a <server> stanza inside the <servers> section using the ID githubicu.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
 <servers>
  <server>
   <id>githubicu</id>
   <username>your github user id</username>
   <password>your access token</password>
  </server>
 </servers>
</settings>

You can install ex_cldr via GitHub or Hex. The number of locales installed depends on the installation method:

• GitHub: Cloning the repository installs all 571 locales into your application dependencies.
• Hex: Only the locales en, en-001, and und are installed by default. Additional locales are downloaded during application compilation when you configure them.

Add ex_cldr and a compatible JSON library to your mix dependencies. A compatible library must implement encode!/1 and decode!/1. :jason is recommended.

Note on OTP 27 and Elixir 1.18+: If you are running on OTP 27 or Elixir 1.18 or later, no :json_library configuration is required or recommended, as ex_cldr will automatically use the native JSON libraries included in these versions.

defp deps do
  [
    {:ex_cldr, "~> 2.37"},
    # Poison or any other compatible json library
    # that implements `encode!/1` and `decode!/1`
    # :jason is recommended
    {:jason, "~> 1.0"}
    # {:poison, "~> 2.1 or ~> 3.0"}
  ]
end

Once the JSON data has been generated in the $CLDR_PRODUCTION directory, you must consolidate it into the ex_cldr format.

Steps:

1. Update your local ex_cldr repository via git pull.
2. Run mix cldr.consolidate to consolidate locales into the ex_cldr format.
3. Regenerate the language_tags.ebin file. Use the DEV=true environment variable to disable stale locale tests during this process.

cd $EX_CLDR
git pull
mix cldr.consolidate
DEV=true mix cldr.generate_language_tags

To use CLDR plural rules with gettext, create a custom plural forms module that uses Cldr.Gettext.Plural. This module must be passed to the plural_forms option in your Gettext configuration.

Note: Cldr.Gettext.Plural may return different plural indices than the default Gettext engine, which can cause issues if mixing engines.

# 1. Define the plural module using your Cldr backend
defmodule MyApp.Gettext.Plural do
  use Cldr.Gettext.Plural, cldr_backend: MyApp.Cldr
end

# 2. Configure Gettext to use it
defmodule MyApp.Gettext do
  use Gettext, plural_forms: MyApp.Gettext.Plural
end

To upgrade from version 1.x to 2.x, follow these steps:

1. Create a backend module: Follow the configuration instructions to define a custom backend module (e.g., MyApp.Cldr).
2. Clean up global configuration: Remove any duplicated global configuration in config.exs. Only :default_locale and :json_library are supported in global configuration.
3. Update Plugs: Update any plugs to use your new configured backend.
4. Update API calls: Change calls from Cldr.some_function to your backend module, e.g., MyApp.Cldr.some_function. Alternatively, use an alias: alias MyApp.Cldr, as: Cldr.