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.

The astronomical calendars and the ephemeris

Several calendars are astronomical, computing month and year starts from the positions of the sun and moon via the Astro library, and each answers for its own range of years:

• The observational Islamic calendars (Observational, Rgsa) and UmmAlQura.Astronomical judge each month's crescent from the JPL ephemeris. Since Astro 2.5 a compact ephemeris covering 1900–2100 ships with the package, so they work immediately after installation; outside it the observational calendars' conversions raise Calendrical.UnsupportedDateRangeError, and UmmAlQura.Astronomical returns {:error, %Calendrical.UnsupportedDateRangeError{}}. Running mix astro.download_ephemeris installs the full 1849–2150 ephemeris and widens their range accordingly.

• The Persian calendar takes its new year from the ephemeris for Persian years 1279 to 1479 (Gregorian 1900 to 2100) and from ICU's arithmetic 33-year cycle outside them, so it answers for every year.

• The Chinese, Korean, Lunar Japanese and Vietnamese calendars compute new moons and solar terms from Astro's series rather than the ephemeris, and answer for the 40,001 years counted from their epoch as Gregorian years -20,000 to 20,000, raising Calendrical.UnsupportedDateRangeError beyond them.

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.

A week-based calendar's "months" have no names of their own, so its cldr_calendar_type/0 is :generic and they take the names of CLDR's generic calendar, "M01" to "M12", while its days, quarters and eras keep the Gregorian names. A date of one is a year, a month of its pattern and a day of that month, as a date of any calendar is: the second day of week 25 is ~D[2026-06-16 Calendrical.ISOWeek], and date_to_string/3 writes it "2026-06-16". The week is asked of the date (Calendrical.week_of_year/1, week_date_from_date/3), and parse_date/1 and the ~D sigil read a week date, "2026-W25-2", as the date it names.

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, and in which January year gives a year its number.

The number of a year. A year reckoned from 1 March or 25 March begins after 1 January of the same number, so its January and February, and March to the 24th, carry the number of the year before. A year reckoned from 1 September or 25 December begins before it, so its last months carry the number of the year to come: Christmas Day 1099 is the first day of 1100 in Calendrical.Julian.Dec25. C. R. Cheney's A Handbook of Dates sets out the reckonings from Christmas Day, the Annunciation and Venice's 1 March, and a Byzantine year of the world begins on 1 September, four months before the January year that is 5508 less. A variant of your own names its new-year day and the Julian year that numbers it: use Calendrical.Calendar.Shifted, base: Calendrical.Julian, year_begins: {3, 25}, year_number: :ending, written_year: :label is the Pisan reckoning, a year ahead of Florence's.

Counted months. A variant's dates carry counted months: month 1 begins on the new-year day and the months follow in the order of time, so a date's fields order as its days do and Date.compare/2 holds. A variant whose year begins on the first of a Julian month has twelve counted months, each a whole Julian month; one whose year begins within a month (March25, Dec25) has thirteen, the split month's later days as a short month 1 and its earlier days as a short month 13. The Julian month and day that name a date come from cardinal_month/1 and cardinal_day/3, the Julian date itself from each variant's base_date/3, and Calendrical.named_month/3 gives a named month's days in the order of time, in two ranges where it is split.

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 other variants a month is 29 or 30 days as its calendar decides it: by predicted crescent visibility in Observational and Rgsa, by the Umm al-Qura rule in UmmAlQura.Astronomical, and by KACST's and ICU's tables in UmmAlQura. The table above describes only 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", style: :wide)
"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 five 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, month 8 of a leap year
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 (Sweden, 1753 transition).

iex> Date.shift(~D[1753-02-17 Calendrical.Reform.Sweden], day: 1)
~D[1753-03-01 Calendrical.Reform.Sweden]

The 11 "missing" days (18 February 1753 through 28 February 1753) are not valid dates in the Swedish composite calendar — Calendrical.Reform.Sweden.valid_date?(1753, 2, 20) 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]