Update date format to user local format

[SimenB]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Prerequisites

• [X] I'm using the latest version of Docusaurus.
• [ ] I have tried the npm run clear or yarn clear command.
• [ ] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• [ ] I have tried creating a repro with https://new.docusaurus.io.
• [ ] I have read the console error message carefully (if applicable).

Description

Doc pages have e.g. Last updated on 4/25/2022 by Simen Bekkhus, which is the US locale. This makes the date ambiguous when the date is 1-12. While that would still be the case if the date uses the local locale, at least I'd read it correctly 😅

Reproducible demo

https://github.com/facebook/jest

Steps to reproduce

Look at the bottom of e.g. https://jestjs.io/docs/jest-object#fake-timers

Expected behavior

For non-US locales, that it says Last updated on 25/04/2022 by Simen Bekkhus, like new Intl.DateTimeFormat().format() returns when I run it in the Chrome console. I.e. uses local locale, not US locale.

Actual behavior

It uses US date formatting.

Your environment

• Public source code:
• Public site URL: https://jestjs.io/
• Docusaurus version used: 2.0.0-beta.18
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Chrome 100 (and whatever version of node Netlify uses)
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS 12.13.1

Self-service

• [ ] I'd be willing to fix this bug myself.

[Josh-Cena]

It's a bit complicated and constantly brought up, but even after https://github.com/facebook/docusaurus/pull/6430, we don't have a good way to fix this issue (or is it an issue?) yet. We've added a little explanation in our docs. Basically, because the site's locale is en, which defaults to en-US, we choose to display the US date format instead.

Maybe we should update the date formatting once we are in browser in useEffect? @slorber thoughts? Would that be weird since the markup changes after hydration?

[SimenB]

I tried to search for an existent issue, didn't find those... But yeah, I don't want to decide per locale, I'd want the user's locale to "win". I've never really used React's hydration, so I don't have anything to contribute as to how feasible it is 😀 But defaulting to US is sorta weird (albeit understandable) - they're the only ones who use it 😅 Could do ISO (i.e. yyyy-MM-dd)? No ambiguity (albeit somewhat specific to code, but docusaurus is mainly dev docs (this is an assumption that might be wrong), so maybe fine?)

[Josh-Cena]

We don't specifically format the date by some format; we format it by currentLocale using Intl.DateTimeFormat. And it happens that per ISO spec, en defaults to en-US, so new Intl.DateTimeFormat("en").format(Date.now()) is 4/27/2022. And we probably don't want to have a special case for en where we always use yyyy-MM-dd, because... well, special cases are evil. Plus, if you use en-GB as locale name, you probably want specifically dd-MM-yyyy. Updating the date format after hydration is not a big problem IMO, considering it's usually below the visible area when the page first loads.

[SimenB]

I edited in a suggestion of ISO after original post, might be a good middle ground?

[Josh-Cena]

I'm not sure what scope you want that ISO format to apply: (a) to all locales, or (b) just to en, or (c) be a user config?

For (a), I'd say using the locale date format is usually not that ambiguous. e.g. fr would format the date as dd-MM-yyyy ~~which seems reasonable to every French-speaking people~~ (actually, maybe not, since fr-CA formats it as yyyy-MM-dd, so a fair proportion of them don't format as dd-MM-yyyy). It's just English that has this complication😅 And for (c), when it comes to i18n, it's usually not the site creator's call to say what to display, so a config option doesn't seem right to me either. So the solutions I can think of are:

• Special-case en (which is the default anyways, so it is already special in some sense) where we always use yyyy-MM-dd
• Update the date format after hydration

Both seem like good ways out, but the second way could potentially solve other edge-cases if there are other diverging date formats in other locales that I'm not aware of.

[Josh-Cena]

Wow, i18n is complicated... We should stop assuming language === region and update region-specific tags by user locale everywhere...

[slorber]

The doc page is static. At the end of the day, the HTML markup produced by the CI must output a date in a given format. And at this time the user locale is unknown.

I'm not sure we want to add "overrides". If en formats as en-US we should keep it, now you can set en-GB as the default site locale if you don't like the date format for en-US.

Open to fix the displayed local after React hydration, which means the user would see US date MM-dd-yyyy when static page loads, and then the format is swapped for the dd-MM-yyyy one. Note that this can produce a weird UX if the date is above the fold and the user can see the format change after page load.

Another option remains: build the site in both en-US and en-GB => have 2 static pages for the doc, with different date formats. Probably overkill though if it's just to solve this date format problem.

[slorber]

Will keep this open until we provide more flexibility for users to define how they want to handle blog/doc date formats

See also https://github.com/facebook/docusaurus/pull/7673#issuecomment-1170186409