tc39 / proposal-intl-eradisplay

Intl.DateTimeFormat displays era field only if date displayed is in same era as today's

eraDisplay option for Intl.DateTimeFormat

This repository was built from the repository template for ECMAScript proposals.

Spec Text Preview: https://tc39.es/proposal-intl-eradisplay/spec

Status

• Champion(s): Shane Carr (@sffc)

• Author(s): Louis-Aimé de Fouquières (@Louis-Aime), Miletus, France

• Stage: 2

• Advanced to Stage 1 in 2021-01 TC39: https://github.com/tc39/notes/blob/main/meetings/2021-01/jan-27.md#eradisplay-for-stage-1

• Advanced to Stage 2 in 2022-11 TC39: https://github.com/tc39/notes/blob/main/meetings/2022-11/nov-29.md#eradisplay-option-for-intldatetimeformat

Overview/Motivation

With the present (Nov. 2020) implementation of ICUs and CLDR in navigators, an author using Intl.DateTimeFormat is unable to control whether the era part of a date should be displayed or not.

On the other hand, when displaying a simple gregory date prior to 0000-01-01 with no option or with dateStyle, the era field is not displayed and the date is ambiguous.

The proposed eraDisplay option may take 3 values: "never", always", "auto". If undefined, "auto" is assumed.

• "never": whatever the era option may be, the era part is not displayed.
• "always": whatever the other options may be, the era part is displayed, according to the value of the era. If era is undefined, it is resolved to "short".
• "auto", the default value: the era part is displayed if the year part is displayed, and the date's era is different from today's date, in the resolved calendar.

A presentation is available here : eraDIsplay presentation.

The index file shows the proposed changes to the specifications of DateTimeFormat Objects.

Use cases

You may use a mock-up on the proposal's web page

Most users will get a better result while not changing anything to the options they pass to Intl.DateTimeFormat.

• new Intl.DateTimeFormat("fr-FR").format(new Date(-752,3,13)) //> "13/4/753" as of present (Nov. 2020) implementation; with this proposal://>"13/4/753 BC", that is 1500 years earlier.
• new Intl.DateTimeFormat("en-US",{calendar : "ethiopic"}).format(new Date()) //> "3/15/2013 ERA1". Author did not ask for era name, which is missing in CLDR. //> "3/15/2013" with the proposed feature and the option set to default.

Demanding users, who want to have the era displayed even if it is today's, or who do not want because the reader will understand from the context, will use the non-default values.

Description

• Author may add option eraDisplay in the list of options when invoking new Intl.DateTimeFormat().
• If the eraDisplay option is undefined at DateTimeFormat Object's initialisation, it is is deemed "auto".
• When initializing the Intl.DateTimeFormat Object:
  • If, after resolving the format component set of options, [[Year]] slot is undefined, the "auto" value for [[EraDisplay]] slot is resolved to "never".
  • If [[EraDisplay]] is not "never" and [[Era]] is undefined, [[Era]] is set to "short".
• When creating the parts of a date string with an initialized Intl.DateTimeFormat object and a date, the [[era]] part is skipped:
  • if [[EraDisplay]] is "never"
  • or if [[EraDisplay]] is "auto" and the date's era is the same as today's using the Intl.DateTimeFormat object's[[calendar]].

Comparison

To our knowledge, there is no such function. Computer languages most generaly only give day/month/year without era, using only a very limited number of calendars, if not only one.

Implementations

Moke-up

Access to mock-up

Native implementations

TBC at later stages

Q&A

Q: Should'nt the date pattern be different depending on whether [[Era]] is displayed or not ?

A: With the present (Nov. 2020) version of ICU and CLDR, the separators ("/" or ".") between numeric components of a date are omitted if era is not undefined, for the gregory and iso8601 calendars. With non-numeric months, there is no difference. On the other hand, for most calendars (except chinese, dangi, gregory and iso8601), era is displayed if year is asked, whatever the era option may be; and for those calendars, the numeric date components are separated with "/" or "." depending on the locale, even though the era is displayed. There seems to be no reason for suppressing the separators between numeric date components when adding the era. I do not remember having seen any date string with numeric day, month, year and an era indication written without any separator.

Having the same rules for all calendar reduces the size of calendar-related informations for locale, and facilitates the author's choices. This is why I suggest to have patterns that always associate an era component when the year should be displayed. The default eraDisplay option shall skip this era component when it is not required.

We could change the proposal in setting a new pattern, "patternwoe" (pattern without era) in a similar way as "pattern12". The Intl.DateTimeFormat formatting methods would have to recompute the pattern for each date displayed, whereas here we propose to use the same pattern, just dropping a component in certain cases.

proposal-intl-eradisplay's Issues

Japanese calendar and eraDisplay

I think this is reasonable except for the splitting of era and year. In Japan, the current year is either 2022 or R4 (令和4年) but not just 4(年). Beyond just awkwardness, this would have the potential of incurring confusion between calendar years and year-length durations (as, depending on context, 4年 could also mean "4 years").

Originally posted by @rkirsling in #7 (comment)

Intl.DateTimeFormat.prototype.formatToParts ( date ) using eraDisplay - patterns or last time deletion ?

The result of the method will have a different number of components, depending on the date parameter.

If eraDisplay 's resolved value is "never" or "always", the structure of the formatted date is known at construction step, there is nothing new.

If eraDisplay is "auto", the method shall establish whether era shall be displayed or not. Date.now is computed, its [[era]] slot is compared to date's, and finally [[era]] is displayed if and only if the [[era]] slot's values differ.

After this decision is taken, one way is to choose the suitable date pattern. But normally this choice is done when DateTimeFormat is constructed (am I right ?).

The other option is to have a pattern with era handy, and if necessary to suppress the era part and the dependent literal if there is one. In this case, all patterns with years (y, Y etc.) would have an era part (g, G etc), which could simplify the number of patterns for each locale. Then the algorithm is easy to understand.

However, for certain locale (en-US, fr, most European ones...) there is a difference between date patterns with 2-digit fields and no era, and the same with era:
01/01/2020 versus 01 01, 2020 AD.
In my opinion, there should not be any difference. Both should be written with slashes. But I might be wrong.

What era to display for negative years in single-era calendars (Indian, Buddhist, Persian, Islamic)

There are several calendars that currently display the same era for both positive and negative years. Is this expected? If not, then what should be the era name for negative years, or should it be blank?

Examples:

const calendars = ['indian', 'buddhist', 'persian', 'islamic'];
const dates = [new Date('-010000-01-01T00:00Z'), new Date('2020-01-01T00:00Z')];
for (const date of dates) {
  console.log(date.toISOString());
  for (const calendar of calendars) {
    console.log(`${calendar}: ${date.toLocaleDateString('en-US', {calendar, timeZone: 'UTC'})}`);
  }
}

/* output: 
-010000-01-01T00:00:00.000Z
indian: 6146/12/-10583 Saka (ignore known bug with month number)
buddhist: 3/18/-9457 BE
persian: 10/10/-10622 AP
islamic: -6/15/-10947 AH

2020-01-01T00:00:00.000Z
indian: 10/11/1941 Saka
buddhist: 1/1/2563 BE
persian: 10/11/1398 AP
islamic: 5/6/1441 AH
*/

Former discussion

This proposal was designed starting from these discussions.

Connection with CLDR

The eraDisplay proposal came initially from a ticket at CLDR where I was worried that era field was displayed even if the author did not explicitly ask for it. This post is still in "new" state the day I'am writing this post. Seeing no reaction, I designed the first draft of the eraDisplay proposal in May 2020.

The presently distributed version of CLDR reacts in different ways when era option is not defined where year is. These is quite visible and easy to test on the proposal's moke-up on GitHub Pages. With "en-GB", when era is set to undefined for ethiopic or coptic, display is as if month was undefined !

I suspect there are certain "shortcuts" in designing the date display patterns that yield to unwanted effects.

I intend to issue a new post on CLDR on this issue.

Should we consider hiding lower-power fields in scope?

The principle behind the optional display of era names also carries to years and even smaller fields. For example, as a date approaches, one might say,

1. "November 20, 2021 CE"
2. "November 20, 2021" if the current era is CE
3. "November 20" if the current year is 2021 CE
4. "The 20th" if the current month is November 2021 CE

The question is, should we keep this proposal limited to just eraDisplay, or should we make it more general?

Transfer to tc39 org

The proposal has been accepted as Stage 1. This means that we should migrate this repo from Louis-Aime/proposal-intl-eradisplay to tc39/proposal-intl-eradisplay.

The first step is to transfer the repo to me, and then I will move it to tc39.

Resolving eraDisplay at construction time

As proposed on Dec. 8, here is the way Intl.DateTimeFormat handles eraDisplay at contruction time.

1. As Intl.DateTimeFormat is constructed, a resolved eraDisplay field is evaluated.
   1. value is set to "never" or "always" if it was specified so.
   2. else, including if no eraDisplay was passed, value is set to "auto".
   3. except if value was set to "never", era option is set to "short" if it was undefined.
   4. finally, if "auto" and if the year option is undefined, value is set to "never".

In other words:

• auto feature shall work most of the time, without changing user's code.
• If [[year]] is not to be displayed, by default [[era]] will not be displayed even if era was specified to some value.

Please note that, as of today (and I'm not sure this is in line with the original intention), if the only asked option is era, all date parts are displayed. With the proposed option, setting era only would result in having all date fields except era !

I thought that only if all date-time option fields were undefined the day month year combination was assumed. (see e.g. in MDN As of today, it is not possible to display the era alone. Something remains to be done here ("Best fit" resolving option ?).

That said, only very demanding users having rather special requirements (displaying era and other part of the date, except year) would have to change their code.