Non-Gregorian calendars
Displaying dates in systems such as Hijri, Hebrew, or Japanese eras, with real calendar rules instead of relabeling a Gregorian date.
What it is
Non-Gregorian calendar support lets the same date appear in systems such as the Islamic Hijri calendar, the Hebrew calendar, or Japan's era-based calendar. JavaScript's Intl.DateTimeFormat can select one with the calendar option or a Unicode locale extension such as 'en-u-ca-hebrew'. The locale still controls language and formatting; the calendar controls how the year, month, day, and era are named and numbered.
Reach for it when users, institutions, or legal documents work in a calendar other than Gregorian. Keep instants on the timeline in a stable machine representation, then format them in the selected calendar at the edge. Treat calendar as its own preference rather than assuming it from language or country.
Gotcha: this is not a matter of swapping year numbers. Month structures, leap rules, eras, and even variants within the Islamic calendar differ. Eras also change on real dates: when Japan moved from Heisei to Reiwa on 1 May 2019, vendors from Microsoft to the JDK maintainers had to ship patches, because Heisei 31 and Reiwa 1 are the same Gregorian year. Do not write conversion arithmetic or translate Gregorian month names. Use CLDR-backed Intl data, show the era when it disambiguates the year, and test the exact calendars your product claims to support.
Ask AI for it
Add selectable calendar support with Intl.DateTimeFormat. Keep stored instants unchanged, save the calendar preference separately from locale and time zone, and format with the calendar option using the exact values 'gregory', 'islamic-umalqura', 'hebrew', and 'japanese'. Include year, month, day, and era where the chosen calendar needs it. Build a settings preview for each choice, fall back visibly when Intl.supportedValuesOf('calendar') does not include a requested value, and add tests proving the same instant formats differently without changing its stored timestamp.