DEV Community

Cover image for Intl.Locale info: the browser knows your week
richi.codes
richi.codes

Posted on Originally published at richi.codes

Intl.Locale info: the browser knows your week

This note has an interactive demo. Try it in the original

Your date picker may well start the week on the wrong day for a lot of your users. Since July 2026 every major browser can tell you the right one: new Intl.Locale("he-IL").getWeekInfo() returns { firstDay: 7, weekend: [5, 6] }. That is Intl Locale Info, now Baseline, and it removes a whole category of hardcoded tables.

Pick a few locales in the demo above. The calendar reflows to start on the locale's first day, the weekend columns move, the clock switches between 12 and 24 hours, and the calendar flips right-to-left for Hebrew or Arabic. Every value comes straight from your browser; the code panel at the bottom shows the real return values.

What it is and why it matters

Intl.Locale has existed for years, but it only told you what was in a tag: language, script, region. The Intl Locale Info proposal adds methods that answer questions about a locale, using Unicode's locale data:

  • getWeekInfo(): firstDay (1 = Monday … 7 = Sunday) and weekend, an array of day numbers.
  • getHourCycles(): the preferred hour cycles, like ["h12"] for en-US or ["h23"] for ja-JP.
  • getTextInfo(): { direction: "ltr" } or "rtl".
  • getCalendars(): calendars in use, sorted by preference.
  • getTimeZones(): IANA time zones for the locale's region.

There are also getCollations() and getNumberingSystems(). The proposal reached Stage 4 and is part of ECMA-402, 13th edition (June 2026).

Why it matters: "the week starts on Sunday" is wrong for Spain, "the weekend is Saturday and Sunday" is wrong for Israel, and "use a 12-hour clock" is wrong for most of Europe. Before this, you either shipped a lookup table, pulled in a date library mainly for this, or guessed.

How it works

This is the core of the demo's calendar header. firstDay uses ISO numbering, so I build the seven column labels starting from it and let Intl.DateTimeFormat name each day:

const loc = new Intl.Locale(navigator.language);
const { firstDay, weekend } = loc.getWeekInfo();

const fmt = new Intl.DateTimeFormat(loc.baseName, { weekday: 'short', timeZone: 'UTC' });
const header = Array.from({ length: 7 }, (_, i) => {
  const isoDay = ((firstDay - 1 + i) % 7) + 1; // 1 = Monday … 7 = Sunday
  return fmt.format(new Date(Date.UTC(2024, 0, isoDay))); // 1 Jan 2024 was a Monday
});
// en-US → ["Sun", "Mon", …]   es-ES → ["lun", "mar", …]
Enter fullscreen mode Exit fullscreen mode

A day is part of the weekend when weekend.includes(isoDay), which is how the demo paints the teal columns. Note that getDay() returns 0 for Sunday, so I convert with date.getDay() || 7.

For the clock, I take the first preferred hour cycle and pass it to DateTimeFormat. Intl.DateTimeFormat already picks a sensible default when formatting, so where this really pays off is in your own UI: choosing whether a time picker opens in 12 or 24 hours.

const [hourCycle] = loc.getHourCycles();
new Intl.DateTimeFormat(loc.baseName, { hour: 'numeric', minute: '2-digit', hourCycle });
// en-US → "6:05 PM"   es-ES → "18:05"
Enter fullscreen mode Exit fullscreen mode

And getTextInfo().direction is what the demo uses to set dir="rtl" on the calendar.

The forced-region select in the demo uses the rg extension of the tag: en-US-u-rg-gbzzzz means "American English, but with UK regional preferences". Same language, but the week starts on Monday and the clock goes to 24 hours. That is a nice way to respect people who use a browser in English while living somewhere else.

I ran all of these snippets in Chromium, Firefox and WebKit through Playwright, and they returned the same week data in all three.

Browser support and gotchas

According to MDN's compatibility data, the methods shipped in Chrome 130, Safari 17 and, last, Firefox 153, which is what made the feature Baseline in July 2026. Node.js has the methods from version 24.

Things that will bite you:

  • The old accessor shape. Before the methods, Chrome (from 99), Safari (from 15.4) and Node (from 18) exposed these as properties (loc.weekInfo, loc.hourCycles…). They changed to methods because each access returned a new object, so loc.weekInfo === loc.weekInfo was false. If you need older engines, fall back: loc.getWeekInfo?.() ?? loc.weekInfo ?? { firstDay: 1, weekend: [6, 7] }. The demo does exactly that and shows a notice when it has to.
  • minimalDays is gone. Old docs show a third property for week-of-year rules. It has been removed from the spec and is being removed from browsers; none of the three engines I tested return it.
  • No region, no time zones. new Intl.Locale("es").getWeekInfo() still works, but getTimeZones() returns undefined when the tag has no region subtag. Try typing ar in the demo. Check before you call .length.
  • It is data, not a constant. The values come from Unicode locale data, and engines don't always agree on the long tail: for he-IL, Chromium and WebKit list islamic among the calendars and Firefox doesn't. Don't write tests that hardcode the full arrays.
  • navigator.language is a guess. It is the browser's UI language, not where the person lives. Let users override the first day of the week in settings; use this as the default.

What to keep an eye on

  • Date pickers and calendar components dropping their own week tables in favor of getWeekInfo().
  • Temporal, which pairs naturally with this for date maths once you know where the week starts.
  • How engines keep their locale data in sync, since small differences like the calendar list above can show up in UI.

Sources


Originally published at richi.codes.

Top comments (0)