# `GanttEx.I18n`
[🔗](https://github.com/rocket4ce/gantt_ex/blob/v0.1.0/lib/gantt_ex/i18n.ex#L1)

Translations and localized date formatting.

All user-facing strings of the chart (column titles, lightbox labels,
toolbar tooltips, month and day names...) live in the `GanttEx.Gettext`
backend. Date patterns are translatable too, so each language can choose
its own order and separators.

## Supported locales

`en`, `es`, `fr`, `it`, `de`, `pt`, `pt_BR`, `ja`

Locale names are normalized, so `"pt-BR"`, `"es-CL"` or `:fr` work too.

## Date patterns

Patterns use `Calendar.strftime/3` directives with localized month and day
names, plus `%V` for the ISO week number. Named patterns (atoms) resolve to
the translated pattern of the locale:

    iex> GanttEx.I18n.format(~N[2025-03-07 00:00:00], :month_year, "es")
    "marzo 2025"

    iex> GanttEx.I18n.format(~N[2025-03-07 00:00:00], :date, "de")
    "07.03.2025"

    iex> GanttEx.I18n.format(~N[2025-03-07 00:00:00], "%a %-d · W%V", "fr")
    "ven. 7 · W10"

    iex> GanttEx.I18n.format(~N[2025-03-07 00:00:00], :month_year, "ja")
    "2025年3月"

# `locale`

```elixir
@type locale() :: String.t()
```

A locale name such as `"es"` or `"pt_BR"`.

# `pattern`

```elixir
@type pattern() ::
  atom()
  | String.t()
  | (NaiveDateTime.t() -> String.t())
  | (NaiveDateTime.t(), locale() -> String.t())
```

A date pattern: a named pattern, a strftime string or a function.

# `calendar_names`

```elixir
@spec calendar_names(locale()) :: %{
  months: tuple(),
  months_short: tuple(),
  weekdays: tuple(),
  weekdays_short: tuple()
}
```

Returns localized month and weekday names as tuples.

    iex> GanttEx.I18n.calendar_names("it").months |> elem(0)
    "gennaio"

    iex> GanttEx.I18n.calendar_names("de").weekdays_short |> elem(6)
    "So"

# `confirm_delete_tasks`

```elixir
@spec confirm_delete_tasks(pos_integer(), locale()) :: String.t()
```

Returns the confirmation message to delete several tasks.

    iex> GanttEx.I18n.confirm_delete_tasks(3, "en")
    "Are you sure you want to delete these 3 tasks?"

# `duration`

```elixir
@spec duration(integer(), GanttEx.Dates.unit(), locale()) :: String.t()
```

Returns a translated duration such as `"3 days"`.

    iex> GanttEx.I18n.duration(3, :day, "es")
    "3 días"

    iex> GanttEx.I18n.duration(1, :hour, "en")
    "1 hour"

# `format`

```elixir
@spec format(NaiveDateTime.t() | Date.t() | nil, pattern(), locale()) :: String.t()
```

Formats a datetime with a pattern (see the module docs).

# `formatter`

```elixir
@spec formatter(locale()) :: (NaiveDateTime.t() | Date.t() | nil, pattern() ->
                          String.t())
```

Returns a 2-arity formatting function bound to `locale`.

Translations are looked up once, which makes it the efficient choice to
format many dates (for example all the cells of a time scale).

    iex> format = GanttEx.I18n.formatter("pt_BR")
    iex> format.(~N[2025-12-01 00:00:00], :month_year)
    "dezembro 2025"

# `labels`

```elixir
@spec labels(locale()) :: %{required(atom()) => String.t()}
```

Returns every UI label of the chart, translated.

    iex> GanttEx.I18n.labels("es").save
    "Guardar"

    iex> GanttEx.I18n.labels("en").task_name
    "Task name"

# `locales`

```elixir
@spec locales() :: [locale()]
```

Returns the bundled locales.

    iex> GanttEx.I18n.locales()
    ["en", "es", "fr", "it", "de", "pt", "pt_BR", "ja"]

# `normalize_locale`

```elixir
@spec normalize_locale(term()) :: locale()
```

Normalizes a locale name, falling back to the language and then to `"en"`.

    iex> GanttEx.I18n.normalize_locale("pt-br")
    "pt_BR"

    iex> GanttEx.I18n.normalize_locale("es-CL")
    "es"

    iex> GanttEx.I18n.normalize_locale(:ja)
    "ja"

    iex> GanttEx.I18n.normalize_locale("xx")
    "en"

# `pattern`

```elixir
@spec pattern(atom(), locale()) :: String.t()
```

Returns the translated pattern for a named date format.

Available names: `:date`, `:datetime`, `:time`, `:day`, `:weekday_day`,
`:day_month`, `:weekday_date`, `:month_year`, `:month`, `:year` and
`:quarter`.

    iex> GanttEx.I18n.pattern(:date, "en")
    "%m/%d/%Y"

    iex> GanttEx.I18n.pattern(:quarter, "es")
    "T%q"

# `with_locale`

```elixir
@spec with_locale(locale(), (-> result)) :: result when result: var
```

Runs `fun` with the GanttEx backend set to `locale`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*