Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

One moment, what time is it everywhere? Intl date and time formatting, explained plainly

The same moment is 12/20/2020 in the US, 20/12/2020 in Britain, and 2012. 12. 19. in Korea. This guide follows MDN's Intl.DateTimeFormat and Intl overview: locales, time zones, 12/24-hour time, calendars and numbering systems, formatToParts, and reusing formatters.

Real photo: the Seiko world clock at Narita Airport Terminal 2, a day-and-night world map, with times for Dallas, Santiago, Paris, Istanbul, Nairobi, Taipei, and Singapore

First, the boundaries of this guide. The site already has a practical guide to Promises and async/await, about the ways to write code that waits for a result to come back; a practical guide to the event loop, about the order code runs in; and a practical guide to closures and scope, about who can see a variable. This guide is about none of those. It is about one thing only: how a single moment in time should be written on the page. When the time is shown wrong, a customer thinks the order was lost, the owner thinks the system broke, and customer service cannot reconcile anything. The "Greenstone Cafe" used below is still the same fictional practice project: a small web tool that takes orders for a street-side cafe. This time it takes online orders, its customers may be anywhere in the world, and the order time has to be shown in each customer's own convention. Every operation, code sample, and number built around it was invented to explain the technique, not a real record. All syntax and behavior of date and time formatting comes from MDN's Intl.DateTimeFormat reference page and the Intl overview page; see each article's meta information and evidence record for sources. MDN's own examples, such as the 20 December 2012 moment and the Dallas and Taipei world clocks, are the documentation's examples, not real user data.

Step 1: There is only one moment, but countless ways to write it

In JavaScript, first separate two things: the moment and the writing. A moment is one instant, stored with new Date, and underneath it is just the number of milliseconds since 1 January 1970 — it has nothing to do with which country anyone is in. The writing is turning that instant into a string a person can read, and that step does depend on language and region. The same instant is written 12/20/2020 by habit in the United States, 20/12/2020 in Britain, 2012. 12. 19. in Korea, and ١٩/١٢/٢٠١٢ in Arabic digits in Egypt. MDN puts it plainly: DateTimeFormat uses the default locale and default options when no locale is specified. In other words, if you do not tell it whose convention to follow, it follows the convention of the machine the code runs on, and the same line of code prints different strings on different people's computers. That is the most common first trap.

The Greenstone Cafe's online order page stepped into this trap: the order detail page showed the order time with a plain new Date().toLocaleString(). On the owner's computer, a Chinese system, it showed "2026/11/19 08:30:00"; when a customer in London opened the same page, they saw "19/11/2026, 08:30:00". Two people looking at the same order, reading it in two different writings, and they nearly mistook it for two different orders while reconciling. Remember the first sentence: the moment is objective, the writing is local; if the writing is not pinned down, the page looks different to everyone.

Step 2: The locales argument is "whose convention do we write in"

The first argument of Intl.DateTimeFormat, locales, answers the question "whose convention do we write in". You can pass one string, such as en-US, or an array, such as ["ban", "id"], meaning try Balinese first and fall back to Indonesian if Balinese is not supported. MDN's example is direct: the same moment, new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738)), formatted with en-US gives 12/20/2020, and with ["ban", "id"] gives 20/12/2020. The order, the separators, even what the digits look like — all of it follows the locale.

A locale identifier itself has structure, and MDN's Intl overview explains it clearly: it is a language subtag, a script subtag, a region subtag, and more, joined by hyphens. zh-Hans-CN is Chinese, simplified characters, mainland China; de-AT is German as used in Austria; hi is simply Hindi. Locale identifiers are case-insensitive, but the convention is title case for script subtags, upper case for region subtags, and lower case for everything else. Do not guess a locale string from feeling: a misspelled one may be treated as an unrecognized language and silently ignored, falling back to the default, with the page showing the wrong convention and no error at all.

Step 3: Omitting locales hands the decision to someone else's computer

MDN warns explicitly that toLocaleString without arguments depends on the implementation, the default locale, and the default time zone. In plain words: if you do not pass a locale, the browser follows the settings of the user's computer. The owner's computer is Chinese, the customer's computer is English, and the same line of code produces two results — it looks fine on your own machine during testing and changes shape once it ships.

The right practice is to always pass a locale explicitly for any time shown to a user. If you can get the user's preferred language, use navigator.language; if you want to leave a fallback path, pass navigator.languages, a list sorted by preference, and let the runtime negotiate the best fit. MDN's example is: const formattedDate = new Intl.DateTimeFormat(navigator.language).format(date), formatting with the browser's reported preferred language. After the cafe's order page changed to this, customers in London saw 19/11/2026, customers in the United States saw 11/19/2026, each in their own convention, and nobody had to guess any more.

Step 4: What happens when a locale is wrong — three different endings

A wrong locale has three different endings, and they must be told apart. First, if what you pass is not a string or an object — a number, say — MDN says a TypeError is thrown. Second, if the string is syntactically invalid, a RangeError is thrown. Third, if the string is well-formed but the runtime does not recognize the language — MDN's example is new Intl.DateTimeFormat("default"), where "default" is syntactically fine but is no language at all — the runtime ignores it and falls back to the system locale. The third ending is the most treacherous: nothing throws, nothing crashes, it just quietly uses the default writing, and by the time you notice, the page has been showing the wrong convention for a long time.

So write the locale list as a priority list: the one you want most first, the fallback last. That is what MDN's ["ban", "id"] means: Balinese may not be supported, so use Indonesian. The cafe's practice is to pass the language the user picked on the page first, then navigator.languages, and finally nothing at all — because passing nothing means the default, and the fallback is always last. While writing the code, do one more handy thing: read the locale that actually took effect with resolvedOptions() and log it, so that when something goes wrong you can see at a glance whose convention was used.

Step 5: dateStyle and timeStyle — pick the length first, then the details

Once you know whose convention to write in, the next step is how long to write it. Intl.DateTimeFormat offers dateStyle and timeStyle, each taking full, long, medium, or short. MDN's example: en-GB, dateStyle full, timeStyle long, time zone Australia/Sydney, formatting the 20 December 2020 moment, gives "Sunday, 20 December 2020 at 14:23:16 GMT+11". Weekday, month, day, hour, minute, second, and time zone are all written out, and anyone can check it at a glance.

Which level to pick depends on the scene. In an order list where every row is short on space, short is enough; on an order detail page where someone must confirm the time at a glance, long or full is safer. The cafe's rule is: the list page shows the date in short, the detail page shows the date in long plus the time in short, and the full form is only read out over the phone to a customer. The level is written for people, not for machines; between machines, always pass a timestamp or an ISO string, never a formatted string, because parsing one back loses the time zone and the precision.

Step 6: weekday, month, hour — single options for exactly what you want

dateStyle and timeStyle are set menus; weekday, year, month, day, hour, minute, and second are a la carte. MDN's example: weekday long, year numeric, month long, day numeric, formatting 20 December 2012 in a German locale, gives "Donnerstag, 20. Dezember 2012". Want the weekday to appear, add weekday; want the month written out in full, set month to long; want the month as a number only, set it to numeric.

Time works the same way: set hour, minute, and second each to numeric, add timeZoneName, and you get a complete time with its zone abbreviation. In MDN's examples, the same moment with the time zone set to UTC and the zone name set to short gives "Thursday, December 20, 2012, GMT" in an English locale; with the zone set to Australia/Sydney it gives "2:00:00 pm AEDT" in Australian English; and with fractionalSecondDigits set to 3 it gives "2:00:00.200 pm AEDT", milliseconds included. On the cafe's kitchen printer, precision to the second is enough; on a reconciliation statement, precision to the millisecond adds nothing and only makes it harder to read. The rule for fine options is: for every extra field on the page, ask whether the user really needs to see it, and leave it out if not.

Step 7: 12-hour or 24-hour — do not make the user guess

The same moment written in 12-hour and 24-hour form looks completely different, and mixing them is an accident waiting to happen. MDN's example: set hour12 to false and the time zone to America/Los_Angeles, and the 19 December 2012 moment is written "12/19/2012, 19:00:00" in an English locale; leave hour12 unset, and the same moment in Australian English is written "2:00:00 pm". 19:00 and 2 pm describe the same instant as wall-clock time in different zones, and once the writing changes, a reader can easily mistake them for two different times.

More subtle still is dayPeriod: in MDN's example the options carry only hour numeric and dayPeriod short, and the 20 December 2012 moment at 3 in the morning comes out in an English locale as "10 at night" — note, that is not 3 o'clock, it is the period-of-day wording for 10 at night, and MDN uses it to show that dayPeriod gives a localized phrase for the part of the day. The cafe's lesson is: for a time shown to a customer, either write clearly whether it is morning or afternoon, or use the 24-hour clock outright — never write a bare 2:00 and leave people guessing whether it is 2 in the morning or 2 in the afternoon. Write the hour12 option explicitly instead of relying on the default, because the default follows the locale: en-US defaults to 12-hour time, de-DE defaults to 24-hour time, and the same page changes shape when the language changes.

Step 8: timeZone — one instant, different clocks on different walls

A moment is unique, but the clocks on the wall differ everywhere. MDN's examples work this out plainly: the same instant is Sunday 20 December 2020, 14:23:16 in Sydney, and 19:00:00 on 19 December 2012 in Los Angeles. The timeZone option says "write it in the wall-clock time of which place", and it takes an IANA zone name such as Australia/Sydney, America/Los_Angeles, or Asia/Shanghai.

Without timeZone, the machine's local zone is used. The cafe stores order times as UTC timestamps, and when showing them it must pass timeZone explicitly: the customer's own zone for the customer, Asia/Shanghai for the owner, and UTC for customer-service reconciliation, with the zone name written out so anyone can see at a glance which zone the numbers were computed in. MDN also notes that timeZone and timeZoneName can be passed together in options, so that with timeZoneName set to short, an English locale appends abbreviations like GMT or AEDT. A time with no zone is a number with no unit, and reconciliation will go wrong sooner or later.

Step 9: Calendar and numbering system — one language can still have different writings

Language and zone settled, and still not done: one language can use different calendars and different digits. MDN's example: with calendar set to chinese and numberingSystem set to arab in options, resolvedOptions() reads back calendar as chinese, numberingSystem as arab, and timeZone as the machine's default zone, such as America/New_York. Calendar and numbering system can be set independently, or written after the locale with the -u- extension, as in ja-JP-u-ca-japanese — Japanese, Japanese calendar, where 2012 is year 24 of the Heisei era, formatting as 24/12/19.

The Intl overview gives more examples: th-TH-u-nu-thai uses Thai digits ๐๑๒๓๔๕๖๗๘๙; de-DE-u-co-phonebk uses German phonebook ordering; en-GB-u-ca-islamic-umalqura uses the Islamic Umm al-Qura calendar, where the Gregorian date 14 October 2017 is the Hijri date 24 Muharram 1439. The cafe has no use for the Islamic calendar, but the principle is the same: formatting a date is not "gluing numbers into a string", it is "writing it out under a complete local set of rules", and calendar, digits, ordering, and zone are all part of that set. On a page for overseas customers, calendar and numbering system should follow the locale — never hard-code them yourself.

Step 10: formatToParts — to lay it out yourself, first take it apart

Sometimes the layout a design asks for is something the formatter cannot give directly: the year in bold, the weekday in another color, the zone on its own line. In that case do not build the string yourself — use formatToParts. It returns an array of parts, each with a type and a value, such as year, month, day, weekday, and literal, where literal is the separator or space in between. With the parts array you can assemble the string any way you like: bold year, colored weekday, all just reassembling the parts.

Likewise, to show a range of time, do not format two dates yourself and join them with a dash — use formatRange. It writes the range in the most concise way for the locale, so two days in the same month may show the month only once in an English locale. Its counterpart formatRangeToParts takes the range apart into parts too, for custom layouts. The cafe's membership validity is written this way: formatRange shows "1 November 2026 – 30 November 2026", with the month appearing only where it should, instead of two repeated full dates. Remember the test: to change the layout, take it apart first; to write a range, use formatRange; never glue strings together yourself.

Step 11: Build the formatter once — never inside a loop

Creating a new Intl.DateTimeFormat() has a cost: every creation negotiates the locale, parses the options, and prepares localization data. An order list with hundreds of rows, each creating its own formatter, makes the page visibly slower. The right practice is to build the formatter once, keep it outside, and only call format inside the loop. MDN's examples are written this way too: first const dateFormat = new Intl.DateTimeFormat(undefined, options), then reuse it for every format call.

Two more handy practices go with it. First, Date's own toLocaleString, toLocaleDateString, and toLocaleTimeString run on the same Intl engine underneath, so one-off code can use them directly, while list rendering is steadier with an explicitly built formatter reused across rows. Second, once the options are settled, read them back with resolvedOptions() and confirm that the locale, calendar, numberingSystem, and timeZone that actually took effect are the ones you wanted — locale negotiation can quietly fall back to a default, and only a read-back makes you sure. After the cafe's list page switched to reusing one formatter, rendering hundreds of order rows became visibly faster, and the change was a single line moved to a different place.

Before passing a timeZone, you can also ask first whether that zone is supported at all. MDN's Intl overview describes Intl.supportedValuesOf(): pass "timeZone" and it returns a sorted array of the zone names the runtime supports; pass "calendar", "numberingSystem", "currency", "unit", or "collation" and it likewise returns the supported values for each. Before the cafe opens in a new city, it checks the target zone against that list first, and changes approach early if the zone is not there, instead of discovering on the day a customer orders that the zone name is not recognized. Its companion is Intl.getCanonicalLocales(), which normalizes a locale string a user passes in back to its canonical spelling, even when the casing was written wrong. Both are "check before you pass" tools, and resolvedOptions() is the "confirm after you pass" tool at the other end.

Step 12: 96 date-display incidents in one week — check yourself against the chart

Bar chart of 96 date-display incidents in one week in the fictional Greenstone Cafe project, by cause

The chart above shows a fictional week for the Greenstone Cafe project: 96 incidents related to date and time display in total. No locale passed, everything left to the machine's default convention: 34, or 35.4%, the largest group; no timeZone passed, so two places could not agree on the same moment: 26, or 27.1%; 12-hour and 24-hour forms mixed, so customers misread morning for afternoon: 16, or 16.7%; strings glued together by hand, with the year-month-day order written wrong: 12, or 12.5%; calendar and numbering system ignored, so overseas customers could not read the date: 8, or 8.3%. 34 + 26 + 16 + 12 + 8 = 96, and the books balance. These numbers are invented examples, meant to show at a glance that the first two groups together are over sixty percent — and that they are the same root cause in different spellings: a time shown to people with no explicit statement of whose convention and which time zone.

Checklist: after writing code that shows a time, tick each item

First, store the moment and the writing separately: pass timestamps or ISO strings between machines, and format only when showing it to a person. Second, always pass a locale explicitly for any time shown to a user — never rely on the running machine's default. Third, write the locale list as a priority list, most wanted first, fallback last, and tell apart a TypeError, a RangeError, and a silent fallback when a locale is wrong. Fourth, settle the length first with dateStyle and timeStyle, then add fine options like weekday, month, and hour one by one — leave out any field nobody needs. Fifth, write hour12 explicitly: either spell out morning and afternoon in 12-hour form, or use 24-hour form outright. Sixth, pass an IANA zone name as timeZone explicitly, and write the zone name next to the time — a number with no unit is no report at all. Seventh, let the calendar and numbering system follow the locale — never glue strings together yourself. Eighth, use formatToParts to change a layout and formatRange to write a range — never glue strings yourself. Ninth, build the formatter once and only call format in the loop, then read the settled options back with resolvedOptions() to confirm. If any item cannot be answered, go back to its section and read it again — that is worth more than memorizing ten more APIs.

Views 1Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

Real photo: a bank of light gray metal filing cabinets with one drawer pulled open, revealing rows of hanging file folders inside
Guide
A real database inside the browser: IndexedDB local storage, explained plainly

localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.

Tool TipsData WorkflowsFrontend Engineering
Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding
Real photo: a Casio scientific calculator on a wooden desk showing 123456789 + 987654321 = 1111111110, beside handwritten math notebooks, a pen, a mug, and a laptop edge
Guide
Don't let 0.1 + 0.2 break your bill: JavaScript numbers and Math, explained plainly

Numbers in JavaScript are one type, Number, stored as 64-bit floats — which is why 0.1 + 0.2 is 0.30000000000000004. This guide follows MDN's Basic math in JavaScript, Math, and Number: one number type, float error, counting money in cents, converting strings, NaN and Infinity, safe integers, the four rounding methods, Math.random, the Math toolbox, and formatting for display.

Tool TipsFrontend EngineeringAI Coding