Which Hijri calendars should Temporal support?

[sffc]

There are several ongoing discussions on related topics, including unicode-org/icu4x#6330, unicode-org/icu4x#6210, tc39/ecma402#971, and others. For this issue, I wanted to focus on Temporal and the problems unique to Temporal.

Say I want to encode "the date of Eid al-Fitr in 1446 AH". I might write

Temporal.PlainDate.from({ calendar: "islamic-tbla", year: 1446, month: 10, day: 1 })

This gets encoded in the data model as: 2025-03-30[u-ca=islamic-tbla]

This is fine, except that it requires one of the invariants that we've previously described as being paramount to our data model: roundtripability with ISO. Looking at all the Hijri variants:

• islamic-tbla and islamic-civil retain this invariant since they are backed by a rule-based algorithm.
• islamic-umalqura retains this invariant for current and historical dates. However, if Saudi Arabia publishes a new almanac for Umm al-Qura, ICU will adopt it, meaning that it's possible that the roundtripability could change for future dates.
• islamic (which in ICU is the same as islamic-rgsa) is currently backed by an astronomic simulation that does not match ground truth in any known country. The definition of islamic-rgsa is that it should match the "Saudi Arabia sighting", which, like Umm al-Qura, implies that the underlying code might change over time. However, this might also change for dates in the past, since tweaking the simulation algorithm could impact dates across a wider range.

So overall, I think it's safest to stick with islamic-tbla, islamic-civil, and islamic-umalqura in Temporal (and acknowledge the caveat with Umm al-Qura). Although my motivation is different, this aligns with @dminor's proposal in tc39/ecma402#971 to consider unshipping islamic and islamic-rgsa from Intl.DateTimeFormat.

Just to be clear to onlookers: Temporal retains full support for Hijri with this proposal, including formatting and arithmetic.* The only difference is in conversion to ISO and Gregorian; since we can't predict that conversion into the future with an observation-based calendar, we only support the algorithmic versions. However, one can still write their own function that uses observation data to augment the conversion to Gregorian in user land. * Caveat: it may not be possible to represent the 30th day in a particular month if the rule-based islamic calendar does not give that month 30 days. We could consider something that can represent all possible dates if proposed, perhaps naming it islamic-thirty.

[ptomato]

We discussed this in the Temporal meeting 2025-04-03. We think that it wouldn't be good to just withdraw those calendar IDs after they've been available on the web for so long. It's fine to redirect them to other Hijri calendar IDs with calculations that match the calendars that users actually expect, but we don't think that those calendar IDs should start to throw.

[Manishearth]

Hmm. They've been on the web, but broken in hard-to-notice ways, are there actual users?

[justingrant]

TC39 (pushed by Apple and Google who are very risk-averse when it comes to backwards compatibility) bends over backwards to avoid introducing crashing bugs into JS code that previously didn't crash, even in obscure cases and even if the results returned by existing APIs are not what we'd want if we could design them fresh from the start.

Given the number of JS developers, even obscure features have a lot of users. And islamic calendars are relatively non-obscure! Even if only 0.1% of developers in Islamic countries use Islamic calendars, that's still probably thousands of developers and thousands of apps. Large enough for TC39 to be worried about!

Whatever is decided here, it seems unlikely Chrome and Safari would ship a release that throws for currently-non-crashing calendars. Instead, JS engines will presumably deprecate some IDs and implement them using results from some other Islamic calendar that is still supported.

So the question for ICU4X is this: do you want JS engines or ICU4X to decide which existing calendar IDs should be accepted and how deprecated IDs are mapped to supported calendars? I think it'd be better for the ecosystem for this acceptance and redirection decision to be centralized. This would also make it possible for ICU4X to implement these calendars better in the future.

[Manishearth]

Given the number of JS developers, even obscure features have a lot of users. And islamic calendars are relatively non-obscure! Even if only 0.1% of developers in Islamic countries use Islamic calendars, that's still probably thousands of developers and thousands of apps. Large enough for TC39 to be worried about!

I don't think this clearly follows: these calendars are broken. I'm sure there are thousands of developers and apps who want to use these calendars. I'm unconvinced that there are thousands of developers and apps who actually use these based on actual users.

This is also not about all islamic calendars, we cannot extrapolate based on the number of developers in Islamic countries. umalqura is well-defined and used, and ICU4C embeds dates from the published data. There's some concern around future dates, but it's patchable: it doesn't break regularly IIRC. tbla/civil are similarly well defined and at least one of them is used. It's really just islamic and islamic-rgsa that's on the table here.

Whatever is decided here, it seems unlikely Chrome and Safari would ship a release that throws for currently-non-crashing calendars. Instead, JS engines will presumably deprecate some IDs and implement them using results from some other Islamic calendar that is still supported.

Temporal is an experimental API, and IIRC what Chrome currently ships (behind a flag?) does not match the spec and would need to change anyway. The "don't break already shipped code" is irrelevant, it's not shipped.

There's a separate question here about whether DateTimeFormat should unship this. That's an interesting one, and I think it would be fine to perform some sort of fallbacking with a console warning for DTF. But I'm still not convinced there are actual users who meaningfully depend on this. It would be nice if we could spec that these SHOULD return an error but implementors MAY silently accept and fall back to a different islamic calendar (or perhaps, fall back to gregorian?) if they desire for backwards compat reasons.

We have a bunch of knobs here. I'm very much not convinced that there are meaningful users of this, and even if there are , we can handle this a couple different ways here that should be pinned down.

[justingrant]

Whatever is decided here, it seems unlikely Chrome and Safari would ship a release that throws for currently-non-crashing calendars. Instead, JS engines will presumably deprecate some IDs and implement them using results from some other Islamic calendar that is still supported.

Temporal is an experimental API, and IIRC what Chrome currently ships (behind a flag?) does not match the spec and would need to change anyway. The "don't break already shipped code" is irrelevant, it's not shipped.

Oh! Despite the title of this issue, I misunderstood the scope. I thought we were talking about both DateTimeFormat and Temporal, not just Temporal behavior.

But if we're considering making *only* Temporal throw for 'islamic' and 'islamic-rgsa', then it would break the invariant that someTemporalObject.toLocaleString(...args) and new Intl.DateTimeFormat(...args).format(someTemporalObject) will produce equivalent output.

So my suggestion would be to have the same calendars accepted by Intl.DateTimeFormat and Temporal.*.toLocaleString, because those APIs are intended to be mostly interchangeable.

But I'm still not convinced there are actual users who meaningfully depend on this. It would be nice if we could spec that these SHOULD return an error but implementors MAY silently accept and fall back to a different islamic calendar (or perhaps, fall back to gregorian?) if they desire for backwards compat reasons.

This sounds like the worst of all worlds, because different engines would exhibit different behavior so app and library developers would have to support both thrown exceptions AND bad output instead of just one. It also means that switching from a polyfill to a native implementation would be more likely to cause differences in behavior.

As a point of comparison, for time zones it's taken us hundreds of hours of work and *years* of calendar time to try to get the three major engines aligned on their behavior after they previously diverged due to wiggle room in the spec. Introducing *new* cross-engine variation seems like something that should be a very last resort and there should be a very high bar to do it.

I'm very much not convinced that there are meaningful users of this

Does Google has the ability to measure usage of particular calendars? This seems like a question that could be answered with real data.

Also, what's "meaningful" ?

The only anecdotal info I have about usage is was I've seen an unexpectedly high level of interest (3K views, 15 upvotes) in my 2022 StackOverflow answer about differences between Islamic calendars. This doesn't prove that these two suspect calendars get a lot of usage, but it does suggest that there's confusion among Islamic calendar users. As a general rule whenever there's confusion and multiple options to choose from, a large percentage of usage will be somewhat arbitrarily allocated across the confusing options. Users just pick one and move on. If this pattern holds here too, there will be a fair amount of usage for every Islamic calendar variant.

[Manishearth]

Also, what's "meaningful" ?

Meaningful as in actually relying on the output. Given that these are just broken. Technically a website that lets you enter the locale in a text box "uses" these calendars, but not meaningfully.

This sounds like the worst of all worlds, because different engines would exhibit different behavior so app and library developers would have to support both thrown exceptions AND bad output instead of just one. It also means that switching from a polyfill to a native implementation would be more likely to cause differences in behavior.

Perhaps. Then maybe we can spec that they fall back, but show a warning in the console.

But if we're considering making only Temporal throw for 'islamic' and 'islamic-rgsa', then it would break the invariant that someTemporalObject.toLocaleString(...args) and new Intl.DateTimeFormat(...args).format(someTemporalObject) will produce equivalent output.

I think that invariant is fine to break in the situation where it actually throws?

I think it's pretty bad that ECMA402 shipped with these broken calendars already. It seems like a further unforced error to ship broken/mislabeled calendars in Temporal, whose primary purpose is calendar arithmetic.

[sffc]

I'll post the 402 notes soon, but to cut to the chase, my proposal is, more specifically:

1. Temporal constructors support only the three "stable" islamic variants listed in the OP. This is required by ECMA-402 for conformance.
2. new Intl.DateTimeFormat("foo-u-ca-islamic").resolvedOptions().calendar performs fallback and returns one of the three stable islamic variants that we support. The exact fallback algorithm is ILD (implementation and locale dependent).
3. -u-ca-islamic-rgsa also performs fallback, and I expect most engines to choose to land on umalqura, but it is ILD.

Please note that point 2 is already legal in ECMA-402. For example, "foo-u-ca-tibetan" falls back to the default calendar for "foo" since we don't support "tibetan" yet, but that might change when we add support for "tibetan". This is no different than "islamic" becoming "islamic-umalqura", for example, in Saudi Arabia.

[sffc]

TG2 notes: https://github.com/tc39/ecma402/blob/main/meetings/notes-2025-04-03.md#which-hijri-calendars-should-temporal-support-29

[justingrant]

2. new Intl.DateTimeFormat("foo-u-ca-islamic").resolvedOptions().calendar performs fallback and returns one of the three stable islamic variants that we support. The exact fallback algorithm is ILD (implementation and locale dependent).
3. -u-ca-islamic-rgsa also performs fallback, and I expect most engines to choose to land on umalqura, but it is ILD.

Directionally this sounds like the right solution.

Only caveat: IMO it's preferable to have CLDR and/or ICU4* define the fallback behavior rather than leaving it up to engines to pick one, and therefore run the risk of cross-browser divergent behavior.

This doesn't mean we need to include he fallback behavior in any spec, but it'd be good if we didn't require engines to code the fallback logic themselves.

1. Temporal constructors support only the three "stable" islamic variants listed in the OP. This is required by ECMA-402 for conformance.

Does "support only" mean that Temporal.PlainDate.from("2025-01-01[u-ca=islamic]") would throw? If so, I think it'd be better to just treat 'islamic' and 'islamic-rgsa' like we currently treat other deprecated calendars like 'islamicc' where fallback happens and we canonicalize the calendarId of the Temporal object. Like this:

// current (in FF nightly)
Temporal.PlainDate.from("2025-01-01[u-ca=islamicc]")
// => Temporal.PlainDate 2025-01-01[u-ca=islamic-civil]

// proposed
Temporal.PlainDate.from("2025-01-01[u-ca=islamic-rsga]")
// => Temporal.PlainDate 2025-01-01[u-ca=islamic-umalqura]
Temporal.PlainDate.from("2025-01-01[u-ca=islamic]")
// => Temporal.PlainDate 2025-01-01[u-ca=islamic-something-TBD]

[sffc]

Only caveat: IMO it's preferable to have CLDR and/or ICU4* define the fallback behavior rather than leaving it up to engines to pick one, and therefore run the risk of cross-browser divergent behavior.

Yes. I see this fallback as landing on the ILD side, which in effect means ICU/CLDR.

Does "support only" mean that Temporal.PlainDate.from("2025-01-01[u-ca=islamic]") would throw? If so, I think it'd be better to just treat 'islamic' and 'islamic-rgsa' like we currently treat other deprecated calendars like 'islamicc' where fallback happens and we canonicalize the calendarId of the Temporal object.

Maybe, but I think I prefer Temporal being more strict than Intl.DateTimeFormat. For example, I would really like for -u-ca-islamic to fall back to whichever calendar is best for the region, which requires a full locale. I think the [u-ca] in the IXDTF should be more strict and not do this type of fallback.

[justingrant]

@sffc Would Temporal.PlainDate.from("2025-01-01[u-ca=islamicc]") also throw? If not, what's the difference between throwing with one deprecated calendar name vs. another?

[Manishearth]

If not, what's the difference between throwing with one deprecated calendar name vs. another?

One is formally an alias, the other is not supported but treated like an alias in datetime for legacy reasons.

[sffc]

Aliases != Unsupported. But if we want to also throw on Islamicc and ethioaa, fine with me