cldr

# Getting Started with Cldr

![Build status](https://github.com/elixir-cldr/cldr/actions/workflows/ci.yml/badge.svg)
[![Hex.pm](https://img.shields.io/hexpm/v/ex_cldr.svg)](https://hex.pm/packages/ex_cldr)
[![Hex.pm](https://img.shields.io/hexpm/dw/ex_cldr.svg?)](https://hex.pm/packages/ex_cldr)
[![Hex.pm](https://img.shields.io/hexpm/dt/ex_cldr.svg?)](https://hex.pm/packages/ex_cldr)
[![Hex.pm](https://img.shields.io/hexpm/l/ex_cldr.svg)](https://hex.pm/packages/ex_cldr)

> #### Support for ex_cldr libraries {: .info}
>
> Support for `ex_cldr` and related libraries is provided until December 31, 2027.
> Consumers are encouraged to migrate to the [localize](https://hex.pm/packages/localize)
> library as a direct replacement. See [future support](https://github.com/elixir-cldr#future-support)
> for more information.

> #### Change to :json_library configuration {: .warning}
> As of `ex_cldr` version 2.37.2 the configuration parameter `:json_library`
> does not attempt to read the configuration of either Phoenix or Ecto.

> #### Automatic configuration of :json_library  {: .info}
> OTP 27 and Elixir 1.18 both include native JSON libraries. Therefore if running on either (or both) of these platforms, no `:json_library` configuration is required or recommended.

## Introduction

`ex_cldr` is an Elixir library for the [Unicode Consortium's](http://unicode.org) [Common Locale Data Repository (CLDR)](http://cldr.unicode.org).  The intentions of CLDR, and this library, is to simplify the locale specific formatting and parsing of numbers, lists, currencies, calendars, units of measure and dates/times.  As of August 16th 2024 and `ex_cldr` Version 2.40.1, `ex_cldr` is based upon [CLDR version 45.0](http://cldr.unicode.org/index/downloads/cldr-45).

The first step is to define a module that will host the desired `ex_cldr` configuration and the functions that serve as the public API.  This module is referred to in this documentation as a `backend` module. For example:

```elixir
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
```

This strategy means that different configurations can be defined and it also
means that one `ex_cldr` implementation won't interfere with implementations in another,
potentially dependent, applications.

The functions you are mostly likely to use are:

* `MyApp.Cldr.default_locale/0`
* `MyApp.Cldr.put_locale/1`
* `MyApp.Cldr.get_locale/0`
* `MyApp.Cldr.known_locale_names/0`
* `MyApp.Cldr.Locale.new/1`
* `MyApp.Cldr.validate_locale/1`

## Use Case

Use this library if you need to:

* Support multiple languages and locales in your application

* Support formatting numbers, dates, times, date-times, units and lists in one language or many

* Need to access the data maintained in the CLDR repository in