Available Calendars

This guide describes every CLDR-aligned calendar that ships with Calendrical, grouped by the underlying mechanism. For each calendar it gives the CLDR identifier, the epoch, the month structure, the leap-year rule, and a worked reference date so you can verify a conversion in iex.

The 17 CLDR-acceptable calendar types are all implemented. Each section below cites the corresponding CLDR identifier and the Calendrical module that exposes it.

Gregorian calendars

These are calendars whose month and day structure is identical to (or derived from) the proleptic Gregorian calendar. They differ only in their week structure or in their year numbering.

Month-based Gregorian calendars

A month-based Gregorian calendar lays out years as 12 months of 28–31 days following the proleptic Gregorian rule. Date arithmetic and the leap-year rule are inherited from Calendar.ISO. They differ from each other only in year numbering and in which month starts the calendar year (for fiscal calendars).

Worked example. Buddhist year 2567:

iex> {:ok, gregorian} = Date.new(2024, 1, 1, Calendrical.Gregorian)
iex> {:ok, buddhist} = Date.convert(gregorian, Calendrical.Buddhist)
iex> buddhist
~D[2567-01-01 Calendrical.Buddhist]

Week-based Gregorian calendars

A week-based Gregorian calendar lays out years as a fixed number of 52 (or 53) seven-day weeks rather than 12 calendar months. Each "month" is a contiguous block of weeks (typically 4 or 5) so that quarters always have an exact number of complete weeks. The two share the same proleptic Gregorian day numbering as the month-based calendars but expose a very different period structure.

The key differences between month- and week-based Gregorian calendars:

Both kinds use exactly the same date_to_iso_days/3 and date_from_iso_days/1 arithmetic to map to the proleptic Gregorian day count, so a date in either kind round-trips through Date.convert/2 correctly with all other Calendrical calendars.

Julian calendars

These calendars use the proleptic Julian rule "every fourth year is a leap year" with no centurial exception. They share a single set of date-arithmetic primitives, but differ in the day on which the year begins, which affects how a Gregorian-style date corresponds to a Julian year.

Leap-year rule (all variants). A Julian year y is a leap year when rem(y, 4) == 0. Note that this is the proleptic rule applied without the Gregorian centurial exception, so 1900 is a Julian leap year.

The historical year-start variants are useful for reading and writing dates from medieval and early-modern documents. They are also the building blocks for Calendrical.Composite (see below) when constructing a calendar that transitioned from Julian to Gregorian on a specific date.

Worked example.

iex> {:ok, julian} = Date.new(2024, 1, 1, Calendrical.Julian)
iex> {:ok, gregorian} = Date.convert(julian, Calendrical.Gregorian)
iex> gregorian
~D[2024-01-14 Calendrical.Gregorian]

Solar, lunar, and lunisolar calendars

The remaining CLDR calendars are not derived from Gregorian or Julian. They are grouped here by their underlying astronomical mechanism.

Solar (non-Gregorian)

A solar calendar tracks the tropical year (the time between successive vernal equinoxes) but does not use the Gregorian/Julian leap-year rule. Each implementation has its own tropical-year approximation and its own month layout.

Worked example (Persian).

iex> {:ok, persian} = Date.new(1403, 1, 1, Calendrical.Persian)
iex> {:ok, gregorian} = Date.convert(persian, Calendrical.Gregorian)
iex> gregorian
~D[2024-03-20 Calendrical.Gregorian]

Lunar

A lunar calendar tracks the synodic month (the ~29.5-day cycle of lunar phases) but does not attempt to stay aligned with the tropical year. Twelve lunar months are about 354 days, so a lunar calendar drifts ~11 days per year against the seasons.

The Islamic family is the only CLDR-supported lunar calendar family. All five variants share the same month names (Muharram → Dhuʻl-Hijjah) and year numbering (Anno Hegirae) but differ in how they decide which Gregorian day each lunar month begins on.

Islamic calendars

All Islamic calendars share the same 12-month layout:

In the observational and Umm al-Qura variants, individual months may be 29 or 30 days based on actual lunar visibility, so the table above only describes Civil and Tbla.

Worked example.

iex> {:ok, gregorian} = Date.new(2025, 3, 1, Calendrical.Gregorian)
iex> {:ok, hijri} = Date.convert(gregorian, Calendrical.Islamic.UmmAlQura)
iex> hijri
~D[1446-09-01 Calendrical.Islamic.UmmAlQura]

iex> Calendrical.localize(hijri, :month, locale: "en")
"Ramadan"

Lunisolar

A lunisolar calendar tracks the synodic month and keeps the year aligned with the tropical year by inserting a leap (or embolismic) month every two or three years. The result is a year of either 12 months (~354 days) or 13 months (~384 days), with month boundaries on the new moon.

Year length. All four lunisolar calendars produce year lengths of 353, 354, 355, 383, 384, or 385 days (Hebrew is restricted to these specific lengths by additional dehiyyah postponement rules; the Chinese family permits the full range).

Worked example (Hebrew).

iex> {:ok, hebrew} = Date.new(5784, 1, 1, Calendrical.Hebrew)  # 1 Tishri 5784
iex> {:ok, gregorian} = Date.convert(hebrew, Calendrical.Gregorian)
iex> gregorian
~D[2023-09-16 Calendrical.Gregorian]

iex> {:ok, passover} = Date.new(5784, 8, 15, Calendrical.Hebrew)  # 15 Nisan
iex> {:ok, gregorian} = Date.convert(passover, Calendrical.Gregorian)
iex> gregorian
~D[2024-04-23 Calendrical.Gregorian]

Composite calendars

A composite calendar uses one base calendar before a specified date and a different calendar afterwards. This is the canonical way to model the historical Julian-to-Gregorian transition for individual countries, where the calendar in use literally changed on a known date and a window of "missing" days appeared in the historical record.

Worked example (England, 1752 transition).

iex> day_before = ~D[1752-09-02 Calendrical.England]
iex> Date.shift(day_before, day: 1)
~D[1752-09-14 Calendrical.England]

The 11 "missing" days (3 September 1752 through 13 September 1752) are not valid dates in the English composite calendar — Calendrical.England.valid_date?(1752, 9, 5) returns false.

See calendar_behaviour.md for the syntax of use Calendrical.Composite.

Ecclesiastical calendars

The Calendrical.Ecclesiastical module is not a calendar in the Calendar behaviour sense — it does not implement date_to_iso_days/3 or valid_date?/3 and is not registered as a CLDR calendar type. Instead, it provides functions that, given a Gregorian year, return the dates of the principal Christian liturgical events for that year. The algorithms are taken from Dershowitz & Reingold, Calendrical Calculations (4th ed.), Chapter 9 ("Ecclesiastical Calendars").

Three Easter traditions

Calendrical exposes three different Easter computations because they really are three distinct calculations. The differences are small in most years (and the three frequently coincide) but the underlying definitions and target audiences are different.

Western Easter and Orthodox Easter coincide in years like 2025; they can differ by one, four, or five weeks in other years because the Western (Gregorian) and Eastern (Julian) computus use different lookup tables and different leap-year rules. The astronomical reckoning agrees with the Western Gregorian computus for most years in the 21st century but is not actually used by any Church — it is included for comparison and research.

Movable feasts (Western)

Western (Roman Catholic, Anglican, most Protestants). All return Calendrical.Gregorian dates.

Movable feasts (Eastern Orthodox)

All return Calendrical.Julian dates so the calendar context is visible in the result.

Movable feasts (astronomical, WCC 1997)

The World Council of Churches' 1997 Aleppo proposal for unifying Western and Eastern Easter. No Church currently follows it. All return Calendar.ISO dates and are restricted to year range 1000..3000.

Fixed feasts

Worked example.

iex> Calendrical.Ecclesiastical.easter_sunday(2024)
~D[2024-03-31 Calendrical.Gregorian]

iex> Calendrical.Ecclesiastical.orthodox_easter_sunday(2024)
~D[2024-04-22 Calendrical.Julian]

# Project onto Gregorian: Orthodox Easter 2024 = May 5 Gregorian
iex> {:ok, gregorian} =
...>   Date.convert(
...>     Calendrical.Ecclesiastical.orthodox_easter_sunday(2024),
...>     Calendrical.Gregorian
...>   )
iex> gregorian
~D[2024-05-05 Calendrical.Gregorian]

iex> Calendrical.Ecclesiastical.pentecost(2025)
~D[2025-06-08 Calendrical.Gregorian]

iex> Calendrical.Ecclesiastical.orthodox_pentecost(2025)
~D[2025-05-26 Calendrical.Julian]

iex> Calendrical.Ecclesiastical.advent(2025)
~D[2025-11-30 Calendrical.Gregorian]

iex> Calendrical.Ecclesiastical.orthodox_advent(2025)
~D[2025-11-15 Calendrical.Julian]