# i18n-timezones

[![Hex.pm](https://img.shields.io/hexpm/v/i18n_timezones.svg)](https://hex.pm/packages/i18n_timezones)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> Localized timezone names for Elixir -- 36 locales, 152 timezones, zero runtime complexity.

Building a timezone picker? Displaying meeting times across regions? Your users expect to see **"Eastern Time (US & Canada)"** -- in their own language, not as a raw IANA identifier.

**i18n_timezones** provides human-friendly, localized timezone display names sourced from [CLDR](https://cldr.unicode.org/), the same data that powers ICU, Chrome, and Android. All translation data comes from the `i18n_timezones_data` package -- no external files to manage.

## Why i18n_timezones?

- **36 locales** covering 4+ billion speakers -- from Arabic to Vietnamese
- **CLDR-sourced** -- accurate, professionally reviewed translations
- **ETS-backed** -- concurrent reads with zero bottleneck, powered by OTP
- **Register what you need** -- load individual locales or all at once
- **No panic** -- all lookups return `nil` for missing data, mutations return `{:error, reason}`
- **Minimal dependencies** -- only `jason` for JSON parsing

## Install

```elixir
def deps do
  [
    {:i18n_timezones, "~> 0.1"}
  ]
end
```

## Quick Start

```elixir
I18nTimezones.register_locale("de")
I18nTimezones.set_default_locale("de")

I18nTimezones.get_translation("Tokyo")
#=> "Tokio"
```

## Usage

### Register only what you need

```elixir
I18nTimezones.register_locale("de")
I18nTimezones.register_locale("fr")

I18nTimezones.get_translation_for_locale("de", "Tokyo")
#=> "Tokio"

I18nTimezones.get_translation_for_locale("fr", "Tokyo")
#=> "Tokyo"
```

### Register all locales at once

```elixir
I18nTimezones.register_all_locales()
# All 36 locales now available
```

### Using a default locale

```elixir
I18nTimezones.register_locale("de")
I18nTimezones.set_default_locale("de")

I18nTimezones.get_translation("Tokyo")   #=> "Tokio"
I18nTimezones.get_translation("Berlin")  #=> "Berlin"
```

### List available and registered locales

```elixir
I18nTimezones.available_locales()    # all 36 locales in the data package
I18nTimezones.registered_locales()   # only the ones you've loaded
```

## API Reference

| Function | Description |
|----------|-------------|
| `register_locale(locale)` | Load translations for a single locale. No-op if already registered. |
| `register_all_locales()` | Load all 36 available locales. |
| `set_default_locale(locale)` | Set the default locale. Returns `{:error, reason}` if not registered. |
| `get_default_locale()` | Get the current default locale, or `nil`. |
| `get_translation(key)` | Get the localized name using the default locale. |
| `get_translation_for_locale(locale, key)` | Get the localized name for a specific locale. |
| `get_all_translations(locale)` | Get all translations for a locale as `{:ok, map}`. |
| `available_locales()` | List all locales in the data package. |
| `registered_locales()` | List all currently loaded locales. |

All lookups return `nil` when a timezone or locale is not found -- no exceptions.

## Supported Locales

36 locales covering major world languages:

| | | | | | | |
|---|---|---|---|---|---|---|
| ar | bn | ca | cs | da | de | el |
| en | es | eu | fi | fr | he | hi |
| hr | hu | id | it | ja | ko | ms |
| nl | no | pl | pt | pt-BR | ro | ru |
| sq | sv | th | tr | uk | vi | zh-CN |
| zh-TW | | | | | | |

## Data Source

All translations come from the [Unicode CLDR](https://cldr.unicode.org/) (Common Locale Data Repository) -- the industry-standard source used by every major platform including iOS, Android, Chrome, and Java.

## Also Available For

- **[Ruby](https://github.com/onomojo/i18n-timezones)** -- Rails gem with automatic `time_zone_select` integration
- **[JavaScript/TypeScript](https://github.com/onomojo/i18n-timezones-js)** -- NPM package with tree-shaking and dropdown helpers
- **[Go](https://github.com/onomojo/i18n-timezones-go)** -- Go module with embedded data via `go:embed`
- **[Rust](https://github.com/onomojo/i18n-timezones-rs)** -- Crate with compile-time embedded data

## License

MIT