Search documentation of Localize

# Localize.Calendar (Localize v0.39.0)

Copy Markdown View Source

Calendar localization functions for retrieving locale-specific names for eras, months, days, quarters, and day periods.

Also provides territory-based week preferences (first day of week, weekend days) and functions to produce localized date part strings from `Date`, `DateTime`, and `NaiveDateTime` structs.

## Display names

The `display_name/3` function provides a unified API for localized calendar-related names, modeled on the JavaScript `Intl.DisplayNames` API:

Type | Value | Example result
--- | --- | ---
`:calendar` | `:gregorian` | `"Gregorian Calendar"`
`:era` | `1` | `"Anno Domini"`
`:month` | `1` | `"January"`
`:day` | `1` (ISO Monday) | `"Monday"`
`:quarter` | `1` | `"1st quarter"`
`:day_period` | `:am` | `"AM"`
`:date_time_field` | `:year` | `"year"`

All types support `:locale` and `:style` options. The `:month`, `:day`, `:quarter`, and `:day_period` types also support a `:context` option (`:format` or `:stand_alone`).

## Data access

Lower-level data access functions (`eras/2`, `months/2`, `days/2`, `quarters/2`, `day_periods/2`) return full data maps for use in formatting pipelines.

## Summary

### Types

context()
format()
part()

### Functions

acceptable_calendars()

Returns the acceptable CLDR calendar types.

cyclic_years(locale, calendar_type \\ :gregorian)

Returns the cyclic year names for a locale and calendar type.

day_periods(locale, calendar_type \\ :gregorian)

Returns the day period names for a locale and calendar type.

days(locale, calendar_type \\ :gregorian)

Returns the day names for a locale and calendar type.

display_name(type, value, options \\ [])

Returns a localized display name for a calendar-related item.

eras(locale, calendar_type \\ :gregorian)

Returns the era names for a locale and calendar type.

first_day_for_locale(locale)

Returns the first day of the week for a locale.

first_day_for_territory(territory)

Returns the first day of the week for a territory.

known_calendars()

Returns the list of known CLDR calendar types.

localize(datetime, part, options \\ [])

Returns a localized string for a part of a date or time.

min_days_for_locale(locale)

Returns the minimum days in the first week of the year for a locale.

min_days_for_territory(territory)

Returns the minimum days in the first week of the year for a territory.

month_patterns(locale, calendar_type \\ :gregorian)

Returns the month pattern data for a locale and calendar type.

months(locale, calendar_type \\ :gregorian)

Returns the month names for a locale and calendar type.

quarters(locale, calendar_type \\ :gregorian)

Returns the quarter names for a locale and calendar type.

strftime_options!(options \\ [])

Returns a keyword list of options for use with `Calendar.strftime/3`.

weekdays(territory)

Returns the weekday numbers for a territory as a list of ISO day-of-week numbers.

weekend(territory)

Returns the weekend days for a territory as a list of ISO day-of-week numbers.

## Types

# context()

    @type context() :: :format | :stand_alone

# format()

    @type format() :: :wide | :abbreviated | :narrow

# part()

    @type part() ::
      :era
      | :quarter
      | :month
      | :day_of_week
      | :days_of_week
      | :am_pm
      | :day_periods

## Functions

# acceptable_calendars()

    @spec acceptable_calendars() :: [atom(), ...]

Returns the acceptable CLDR calendar types.

### Returns

- A list of atoms.

# cyclic_years(locale, calendar_type \\ :gregorian)

    @spec cyclic_years(Localize.locale(), atom()) ::
      {:ok, map()} | {:error, Exception.t()}

Returns the cyclic year names for a locale and calendar type.

Cyclic year names are used by some calendar systems (such as Chinese and Dangi) that follow a 60-year cycle of named years.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

- `calendar_type` is a CLDR calendar type atom. The default is `:gregorian`.

### Returns

- `{:ok, cyclic_year_data}` where `cyclic_year_data` is a map of cyclic name sets.

- `{:error, exception}` if the locale or calendar is not found.

# day_periods(locale, calendar_type \\ :gregorian)

    @spec day_periods(Localize.locale(), atom()) :: {:ok, map()} | {:error, Exception.t()}

Returns the day period names for a locale and calendar type.

Day periods include AM/PM indicators and may include additional periods like noon, midnight, morning, afternoon, evening, and night.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

- `calendar_type` is a CLDR calendar type atom. The default is `:gregorian`.

### Returns

- `{:ok, day_period_data}` where `day_period_data` is a map keyed by context, format, period, and variant.

- `{:error, exception}` if the locale or calendar is not found.

### Examples

    iex> {:ok, periods} = Localize.Calendar.day_periods(:en)
    iex> get_in(periods, [:format, :abbreviated, :am, :default])
    "AM"

# days(locale, calendar_type \\ :gregorian)

    @spec days(Localize.locale(), atom()) :: {:ok, map()} | {:error, Exception.t()}

Returns the day names for a locale and calendar type.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

- `calendar_type` is a CLDR calendar type atom. The default is `:gregorian`.

### Returns

- `{:ok, day_data}` where `day_data` is a map keyed by context (`:format`, `:stand_alone`), then format, then ISO day number (1 = Monday through 7 = Sunday).

- `{:error, exception}` if the locale or calendar is not found.

### Examples

    iex> {:ok, days} = Localize.Calendar.days(:en)
    iex> get_in(days, [:format, :wide, 6])
    "Saturday"

# display_name(type, value, options \\ [])

    @spec display_name(atom(), term(), Keyword.t()) ::
      {:ok, String.t()} | {:error, Exception.t()}

Returns a localized display name for a calendar-related item.

This is a unified API for retrieving localized names for calendar systems, date-time fields, eras, months, days, quarters, and day periods — modeled on the JavaScript `Intl.DisplayNames` API.

### Summary

Type | Value | Example result
--- | --- | ---
`:calendar` | `:gregorian` | `"Gregorian Calendar"`
`:era` | `1` | `"Anno Domini"`
`:month` | `1` | `"January"`
`:day` | `1` (ISO Monday) | `"Monday"`
`:quarter` | `1` | `"1st quarter"`
`:day_period` | `:am` | `"AM"`
`:date_time_field` | `:year` | `"year"`

### Arguments

- `type` is the type of calendar item. One of:

  - `:calendar` — a calendar system name (e.g., `:gregorian`).

  - `:era` — an era name by index (e.g., `1` for AD).

  - `:quarter` — a quarter name by number (1–4).

  - `:month` — a month name by number (1–12).

  - `:day` — a day-of-week name by ISO day number (1–7, Monday–Sunday).

  - `:day_period` — a day period name (e.g., `:am`, `:pm`, `:noon`, `:midnight`).

  - `:date_time_field` — a date-time field label (e.g., `:year`, `:month`, `:day`, `:hour`, `:minute`, `:second`).

- `value` is the value to look up. The type depends on the `type` argument (see above).

- `options` is a keyword list of options.

### Options

- `:locale` is a locale identifier. The default is `Localize.get_locale()`.

- `:style` is the display width. One of `:wide` (default), `:abbreviated`, `:narrow`, or `:short`. Not all styles are available for all types.

- `:context` is `:format` (default) or `:stand_alone`. Applies to `:month`, `:day`, `:quarter`, and `:day_period`.

- `:calendar` is the calendar system atom. The default is `:gregorian`.

### Returns

- `{:ok, name}` where `name` is the localized display name.

- `{:error, exception}` if the value is not found.

### Examples

    iex> Localize.Calendar.display_name(:calendar, :gregorian)
    {:ok, "Gregorian Calendar"}

    iex> Localize.Calendar.display_name(:month, 1)
    {:ok, "January"}

    iex> Localize.Calendar.display_name(:month, 1, style: :abbreviated)
    {:ok, "Jan"}

    iex> Localize.Calendar.display_name(:day, 1)
    {:ok, "Monday"}

    iex> Localize.Calendar.display_name(:day, 1, style: :narrow)
    {:ok, "M"}

    iex> Localize.Calendar.display_name(:day_period, :am)
    {:ok, "AM"}

    iex> Localize.Calendar.display_name(:date_time_field, :year)
    {:ok, "year"}

    iex> Localize.Calendar.display_name(:era, 1)
    {:ok, "Anno Domini"}

    iex> Localize.Calendar.display_name(:quarter, 1, style: :abbreviated)
    {:ok, "Q1"}

# eras(locale, calendar_type \\ :gregorian)

    @spec eras(Localize.locale(), atom()) :: {:ok, map()} | {:error, Exception.t()}

Returns the era names for a locale and calendar type.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

- `calendar_type` is a CLDR calendar type atom. The default is `:gregorian`.

### Returns

- `{:ok, era_data}` where `era_data` is a map keyed by format (`:abbreviated`, `:wide`, `:narrow`) and era index.

- `{:error, exception}` if the locale or calendar is not found.

### Examples

    iex> {:ok, eras} = Localize.Calendar.eras(:en)
    iex> get_in(eras, [:abbreviated, 1])
    "AD"

# first_day_for_locale(locale)

    @spec first_day_for_locale(Localize.locale()) :: integer() | {:error, Exception.t()}

Returns the first day of the week for a locale.

Derives the territory from the locale and returns the first day of the week for that territory.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

### Returns

- An integer from 1 to 7.

- `{:error, exception}` if the locale is invalid.

### Examples

    iex> Localize.Calendar.first_day_for_locale(:en)
    7

# first_day_for_territory(territory)

    @spec first_day_for_territory(atom()) :: integer() | {:error, Exception.t()}

Returns the first day of the week for a territory.

Day numbers follow ISO 8601: 1 = Monday through 7 = Sunday.

### Arguments

- `territory` is a territory atom (e.g., `:US`, `:GB`).

### Returns

- An integer from 1 to 7.

- `{:error, exception}` if the territory is not known.

### Examples

    iex> Localize.Calendar.first_day_for_territory(:US)
    7

    iex> Localize.Calendar.first_day_for_territory(:GB)
    1

# known_calendars()

    @spec known_calendars() :: [atom(), ...]

Returns the list of known CLDR calendar types.

### Returns

- A list of calendar type atoms.

### Examples

    iex> calendars = Localize.Calendar.known_calendars()
    iex> :gregorian in calendars and :buddhist in calendars and :hebrew in calendars
    true

# localize(datetime, part, options \\ [])

Returns a localized string for a part of a date or time.

### Arguments

- `datetime` is any `Date.t/0`, `DateTime.t/0`, or `NaiveDateTime.t/0`.

- `part` is one of `:era`, `:quarter`, `:month`, `:day_of_week`, `:days_of_week`, or `:am_pm`.

- `options` is a keyword list of options. The default is `[]`.

### Options

- `:locale` is a locale identifier. The default is `:en`.

- `:format` is one of `:wide`, `:abbreviated`, or `:narrow`. The default is `:abbreviated`.

- `:context` is one of `:format` or `:stand_alone`. The default is `:format`.

- `:era` — if set to `:variant`, uses variant era names (e.g., "CE" instead of "AD" in English).

- `:am_pm` — if set to `:variant`, uses variant AM/PM names (e.g., "am"/"pm" instead of "AM"/"PM" in English).

### Returns

- A string representing the localized date part.

- A list of `{day_number, day_name}` tuples when `part` is `:days_of_week`.

- `{:error, exception}` if the part cannot be localized.

### Examples

    iex> Localize.Calendar.localize(~D[2019-06-01], :month)
    "Jun"

    iex> Localize.Calendar.localize(~D[2019-06-01], :month, format: :wide)
    "June"

    iex> Localize.Calendar.localize(~D[2019-06-01], :day_of_week)
    "Sat"

    iex> Localize.Calendar.localize(~D[2019-01-01], :era)
    "AD"

    iex> Localize.Calendar.localize(~D[2019-01-01], :era, era: :variant)
    "CE"

    iex> Localize.Calendar.localize(~D[2019-01-01], :quarter)
    "Q1"

# min_days_for_locale(locale)

    @spec min_days_for_locale(Localize.locale()) :: integer() | {:error, Exception.t()}

Returns the minimum days in the first week of the year for a locale.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

### Returns

- An integer from 1 to 7.

- `{:error, exception}` if the locale is invalid.

# min_days_for_territory(territory)

    @spec min_days_for_territory(atom()) :: integer()

Returns the minimum days in the first week of the year for a territory.

### Arguments

- `territory` is a territory atom.

### Returns

- An integer from 1 to 7.

### Examples

    iex> Localize.Calendar.min_days_for_territory(:US)
    1

    iex> Localize.Calendar.min_days_for_territory(:GB)
    4

# month_patterns(locale, calendar_type \\ :gregorian)

    @spec month_patterns(Localize.locale(), atom()) ::
      {:ok, map()} | {:error, Exception.t()}

Returns the month pattern data for a locale and calendar type.

Month patterns are used by some calendar systems (such as Chinese and Hebrew) that have leap months. The patterns define how to format month names in leap and non-leap contexts.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

- `calendar_type` is a CLDR calendar type atom. The default is `:gregorian`.

### Returns

- `{:ok, month_pattern_data}` where `month_pattern_data` is a map of month patterns keyed by context and format width.

- `{:error, exception}` if the locale or calendar is not found.

# months(locale, calendar_type \\ :gregorian)

    @spec months(Localize.locale(), atom()) :: {:ok, map()} | {:error, Exception.t()}

Returns the month names for a locale and calendar type.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

- `calendar_type` is a CLDR calendar type atom. The default is `:gregorian`.

### Returns

- `{:ok, month_data}` where `month_data` is a map keyed by context (`:format`, `:stand_alone`), then format, then month number.

- `{:error, exception}` if the locale or calendar is not found.

### Examples

    iex> {:ok, months} = Localize.Calendar.months(:en)
    iex> get_in(months, [:format, :wide, 6])
    "June"

# quarters(locale, calendar_type \\ :gregorian)

    @spec quarters(Localize.locale(), atom()) :: {:ok, map()} | {:error, Exception.t()}

Returns the quarter names for a locale and calendar type.

### Arguments

- `locale` is a locale identifier atom, string, or `Localize.LanguageTag.t/0`.

- `calendar_type` is a CLDR calendar type atom. The default is `:gregorian`.

### Returns

- `{:ok, quarter_data}` where `quarter_data` is a map keyed by context (`:format`, `:stand_alone`), then format, then quarter number.

- `{:error, exception}` if the locale or calendar is not found.

### Examples

    iex> {:ok, quarters} = Localize.Calendar.quarters(:en)
    iex> get_in(quarters, [:format, :abbreviated, 2])
    "Q2"

# strftime_options!(options \\ [])

    @spec strftime_options!(Keyword.t()) :: Keyword.t()

Returns a keyword list of options for use with `Calendar.strftime/3`.

The returned keyword list contains callback functions that produce localized month names, day names, and AM/PM indicators.

### Arguments

- `options` is a keyword list.

### Options

- `:locale` is a locale identifier. The default is `:en`.

- `:calendar_type` is a CLDR calendar type atom. The default is `:gregorian`.

### Returns

- A keyword list with `:am_pm_names`, `:month_names`, `:abbreviated_month_names`, `:day_of_week_names`, and `:abbreviated_day_of_week_names` keys.

### Examples

    iex> options = Localize.Calendar.strftime_options!(locale: :en)
    iex> options[:month_names].(6)
    "June"

    iex> options = Localize.Calendar.strftime_options!(locale: :de)
    iex> options[:abbreviated_day_of_week_names].(1)
    "Mo."

# weekdays(territory)

    @spec weekdays(atom()) :: [1..7, ...]

Returns the weekday numbers for a territory as a list of ISO day-of-week numbers.

### Arguments

- `territory` is a territory atom.

### Returns

- A list of integers from 1 to 7.

### Examples

    iex> Localize.Calendar.weekdays(:US)
    [1, 2, 3, 4, 5]

# weekend(territory)

    @spec weekend(atom()) :: [integer()]

Returns the weekend days for a territory as a list of ISO day-of-week numbers.

### Arguments

- `territory` is a territory atom.

### Returns

- A list of integers from 1 to 7.

### Examples

    iex> Localize.Calendar.weekend(:US)
    [6, 7]

    iex> Localize.Calendar.weekend(:IL)
    [5, 6]