# elm-cldr

This Elm packages provides locale-aware formatting of [`Date`][datePackage]s, [`time`][timePackage]s, numbers, and durations. Formats for each locale are taken from the [Unicode CLDR Project][cldr]. It is intended to be accessible to developers who are familiar with the JS `Intl` API.

[datePackage]: https://package.elm-lang.org/packages/justinmimbs/date/latest/Date
[timePackage]: https://package.elm-lang.org/packages/elm/time/latest
[cldr]: https://cldr.unicode.org/index

## Installation

```sh
elm install enkidatron/elm-cldr
```


## Overview
- Parse a `Locale` from a locale identifier string to store in your `Model`: [`fromString`][fromString]
- Or choose a hardcoded date, such as [`en`][en]
- Format a `Date` from [`justinmimbs/date`][datePackage]: [`Format.Date.format`][dateFormat]
- Format a `Posix` from [`elm/time`][timePackage]: [`Format.DateTime.format`][dateTimeFormat]
- Format a `Float`: [`Format.Number.format`][numberFormat]
- Format a duration: [`Format.Duration.format`][durationFormat]

[fromString]: Cldr-Locale#fromString
[en]: Cldr-Locale#en
[dateFormat]: Cldr-Format-Date#format
[dateTimeFormat]: Cldr-Format-DateTime#format
[numberFormat]: Cldr-Format-Number#format
[durationFormat]: Cldr-Format-Duration#format

## Examples

See `examples` directory for full examples.

### Use a dynamic Locale
```elm
import Cldr.Format.Date
import Cldr.Format.Length exposing (Length(..))
import Cldr.Locale exposing (Locale, root)
import Date exposing (Date)
import Time

localeStringFromFlags : String
localeStringFromFlags = "uk"

locale : Maybe Locale
locale =
    Cldr.Locale.fromString
        Cldr.Locale.allLocales
        localeStringFromFlags

date : Date
date = Date.fromCalendarDate 2022 Time.Jan 10

formatted : String
formatted =
    Cldr.Format.Date.format
        (Cldr.Format.Date.WithLength Short)
        (Maybe.withDefault root locale)
        date
```

## Contributing

The `Cldr.Locale` file is automatically generated from the CLDR JSON. This is done by an `elm-pages` script in this repo named `GenerateCldr`. The multi-stage work of converting the CLDR JSON repository into this library is done by the various scripts and helper files in the `scripts` directory. Theoretically, updating the CLDR version is as easy as updating the `cldrVersion` constant in the `Constants.elm` file, but I am sure that each new CLDR version will introduce some new fresh edge case that this library doesn't handle properly yet.

## CLDR Version History

- 3.0.0: release-47
- 2.1.0: release-41
- 1.0.0: release-40