A hotel card says "Mar 3, 2026 - Mar 5, 2026". A meeting row says "10:00 AM - 11:00 AM". Both come from the same helper: format the start, format the end, put a hyphen between them. In English the result is clumsy. In German, Korean, or Japanese it is wrong, because each locale has its own rules for which fields to repeat, which punctuation joins the two ends, and where the shared month or year goes. Date range formatting is CLDR data, the same way single dates are. This guide shows how to replace hand-built interval strings with the platform interval formatters on the web, iOS, and Android, and how to avoid the bugs teams still ship after they switch: the wrong end date, the wrong time zone, the wrong language, and tests that break on New Year.
It assumes you already format single dates and numbers with locale-aware APIs, as covered in localizing app dates, times, and numbers, and that you keep full sentences in translator-owned messages, as covered in stopping concatenating strings in app localization. A range sits between those two: it takes two instants and returns one string whose shape depends on the locale.
The short answer
- Store a range as two values with explicit meaning: an inclusive last day or an exclusive end instant, plus the time zone the range belongs to.
- Format it once with the platform interval formatter (
Intl.DateTimeFormat.prototype.formatRange,Date.IntervalFormatStyleorDateIntervalFormatter, ICUDateIntervalFormatorDateUtils.formatDateRange). Never format the two ends separately and join them. - Pass the locale your app resolved for the session and the event's time zone, not the device defaults.
- Use parts output (
formatRangeToParts) when you need to style the start and end differently. Do not split the finished string on a dash. - Test with a pinned clock, a pinned zone, and ranges that cross a day, a month, and a year.
Why the hand-built range breaks
Interval formatting is pattern-driven. Unicode's LDML interval formats describe how software takes a skeleton (the fields you want, such as year, abbreviated month, and day) plus two datetimes, finds the calendar field with the greatest difference, and picks a pattern for that case. The greatest difference in "Jan 10-12, 2008" is the day; in "Jan 10 - Feb 12, 2008" it is the month. When no specific pattern exists, CLDR falls back to a locale fallback pattern of the form {0} - {1}. Android's ICU DateIntervalFormat documents the same model: interval patterns map a skeleton and "the largest different calendar field" to a pattern, and the supported fields run year, month, date, hour, minute, second.
A helper that formats two complete dates cannot do any of that. It always repeats the month and year, it always uses your hyphen, and it never learns that a locale shares the month at the end instead of the start. Here is what Node 22's bundled ICU prints for March 3 to March 5, 2026, with { year: "numeric", month: "short", day: "numeric" }:
en-US "Mar 3\u2009\u2013\u20095, 2026"
en-GB "3\u2009\u2013\u20095 Mar 2026"
de "3.\u20135. März 2026"
fr "3\u20135 mars 2026"
ko "2026년 3월 3일~5일"
ja "2026/03/03~2026/03/05"
The escapes make the separators visible. English output uses an en dash surrounded by thin spaces (U+2009), German drops the spaces, Korean uses a tilde and writes the year and month once, and Japanese switches to numeric fields with a fullwidth tilde. A hyphen helper gets every one of these wrong. A Stack Overflow question about two NSDates asked how to produce "July 7-9" in English and the German equivalent, and its author concluded they might need "a switch for each locale". A much older .NET question on localizing date ranges wanted "smart" ranges such as "August 1 - 9, 2009" and could find no range support in the framework. Both are author reports; the platform APIs below answer them.
Range output also does not have to match single-date output. A question about Japanese formatRange literals reports that format prints 2022年7月13日 while formatRange with the same options prints 2022/07/13~2022/07/14. That is CLDR interval data for that skeleton, not a bug in your code, so a test that builds the expected range from two format calls will fail.
Use the platform interval formatter
Web: formatRange and formatRangeToParts
MDN describes formatRange() as formatting "a date range in the most concise way based on the locales and options" of the Intl.DateTimeFormat instance. Both arguments must be the same type, and if the start and end are equivalent at the precision of the output, you get a single date. The TC39 proposal that added it states that it is based on the ICU date interval formatter and the CLDR interval data. Can I use lists support from Chrome 76, Firefox 91, and Safari 14.1, about 97% of global usage.
function formatStay(checkIn, lastNight, appLocale, propertyZone) {
const fmt = new Intl.DateTimeFormat(appLocale, {
year: "numeric",
month: "short",
day: "numeric",
timeZone: propertyZone,
});
if (typeof fmt.formatRange !== "function") {
return fallbackRange(fmt, checkIn, lastNight, appLocale);
}
return fmt.formatRange(checkIn, lastNight);
}
When the design needs the start and end styled separately, use formatRangeToParts(). Each part carries type, value, and a source of startRange, endRange, or shared. For the English example above, the month and year come back as shared, the 3 as startRange, the 5 as endRange, and the separator as a shared literal. Wrap parts by source instead of searching the string for a dash, because the separator is not a hyphen in English and is not a dash at all in Korean.
Check the runtime before you rely on it in React Native. React Native issue #50422 reports Intl.DateTimeFormat#formatRange as undefined on iOS and Android in 0.76.7 and 0.77.2, which crashed Luxon's Interval.toLocaleString(). Feature-detect as in the example, and make the fallback a translator-owned pattern such as a {start} and {end} message per locale rather than a hard-coded hyphen. Framework wrappers lag too: a Transloco feature request asks for a dateRange pipe on top of formatRange, so check whether your i18n library exposes range formatting before you write your own.
iOS and macOS: Date.IntervalFormatStyle and DateIntervalFormatter
Apple's Date.IntervalFormatStyle (iOS 15 and later) creates "user-readable strings in the form of <start> - <end>" from locale and language information. Its initializer takes date, time, locale, calendar, and timeZone, and it offers locale(_:) and timeZone(_:) modifiers, so you can bind both explicitly. For older targets, DateIntervalFormatter (iOS 8 and later) does the same job with dateStyle, timeStyle, dateTemplate, calendar, locale, and timeZone properties, and Apple notes it is safe to share across threads as long as you do not reconfigure it while it is in use.
let formatter = DateIntervalFormatter()
formatter.locale = appLocale // the language the app selected
formatter.timeZone = eventTimeZone // where the stay or event happens
formatter.calendar = appCalendar
formatter.dateStyle = .medium
formatter.timeStyle = .none
let text = formatter.string(from: checkIn, to: lastNight)
Apple documents that the default value of DateIntervalFormatter.locale is "the current user's locale". If your app has its own language picker, or uses per-app language settings that do not match the region format, a formatter left at its default renders ranges in a different language from the surrounding UI. Set the locale from the same source your string lookup uses.
Two configuration traps show up in practitioner reports. A question about DateIntervalFormatter across multiple days sets dateStyle = .none and timeStyle = .short for a 23:45 to 00:45 slot and still gets "1/1/2020, 11:45 PM - 1/2/2020, 12:45 AM", because the formatter adds dates when the ends fall on different days. A question about year borders reports that a dateTemplate built from YYYYMMMd printed "Dec 27, 2016 - Jan 3, 2016" while dateStyle printed the correct "Dec 27, 2015 - Jan 3, 2016". Uppercase YYYY is the week-based year, so prefer dateStyle or a template with y. An openradar mirror entry also reports that NSDateIntervalFormatter ignored the 24-hour setting on iOS 9 while NSDateFormatter respected it. That is an old author report, but it is a good reason to include a 24-hour device in your test matrix.
Android: DateIntervalFormat or DateUtils.formatDateRange
Android offers two paths. DateUtils.formatDateRange "formats a date or a time range according to the local conventions" using bit flags such as FORMAT_SHOW_DATE, FORMAT_SHOW_TIME, FORMAT_SHOW_YEAR, and FORMAT_ABBREV_MONTH, and one overload takes an explicit time zone ID. Its simplest overload, formatDateRange(Context, long, long, int), has no locale parameter. For an app whose selected language can differ from the system, ICU's DateIntervalFormat (API 24 and later) is the more explicit choice because it takes a skeleton and a locale:
val fmt = DateIntervalFormat.getInstance(DateFormat.YEAR_ABBR_MONTH_DAY, appLocale)
fmt.timeZone = android.icu.util.TimeZone.getTimeZone(eventZoneId)
val text = fmt.format(
DateInterval(checkInMillis, lastNightMillis),
StringBuffer(),
FieldPosition(0),
).toString()
ICU supports formatting only, not parsing, so keep the two instants as your data.
Decide what the end date means
Decide whether the stored end is an inclusive last day or an exclusive end instant before formatting, because Android DateUtils.formatDateRange renders an end at 12:00am as the previous day while formatRange prints the end you pass.
The Android reference spells the rule out: if the end "ends at 12:00am at the beginning of a day", it is formatted as the end of the previous day for single-day events and whenever the time is not displayed, so a start of Nov 10 and an end of Nov 12 at 00:00 prints "Nov 10 - 11". A developer who passed March 5 and March 6 at midnight in a DateUtils question got only "Mar 5", and an answer explains that the formatter treats the end as exclusive. formatRange on the web and DateIntervalFormatter on Apple platforms do no such adjustment; they print the instants you give them.
So the same booking can render three ways depending on the platform, unless your model is explicit. Our recommendation, based on those documented behaviors: store hotel stays, rentals, and multi-day events as a start date plus an exclusive end (check-out day or the first day after the event), and convert at the edge of the UI to what each label means. A "Your stay" label usually shows the nights, so format check-in to the last night. A "Check-out" label shows the check-out day on its own. Write that conversion once, in shared code, and name it (lastNight, lastDay) so nobody passes a check-out instant to a formatter that already subtracts a day.
Format in the event's time zone
Compute both endpoints in the time zone where the event happens, not the phone's zone, because a trip or booking range read in the viewer's zone can gain or lose a whole date at either end.
The same instants from June 10 09:00 UTC to June 14 18:00 UTC format as "Jun 10" to "14" with timeZone: "Atlantic/Reykjavik" and "Jun 10" to "15" with timeZone: "Asia/Taipei".
Every formatter above accepts a zone: timeZone in the Intl.DateTimeFormat options, timeZone on DateIntervalFormatter and Date.IntervalFormatStyle, setTimeZone on ICU DateIntervalFormat, and the timeZone argument of DateUtils.formatDateRange. Store the IANA zone ID with the booking or event, pass it every time, and only use the device zone for things that really happen where the user is, such as a reminder they set for themselves.
Overnight time ranges are the related edge. Luxon issue #1662 reports that formatRange with timeStyle: 'short' turns a 7:00 p.m. to 2:00 a.m. slot into two full dates, and Node prints "9/17/2026, 7:00\u202fPM\u2009\u2013\u20099/18/2026, 2:00\u202fAM" for the same shape in en-US. The standard adds dates whenever the ends fall on different calendar days in the formatter's zone. If your design wants a time-only label for a shift or a late event, format the times with a time-only range on the start day's schedule and show the date once elsewhere, or accept the dated form. Do not trim the dates out of the string by hand.
Test ranges without flaky snapshots
Pin the year and the clock in range tests, because DateUtils.formatDateRange hides the year only when it matches the current year, so the same range string changes on January 1.
The Android reference says that without FORMAT_SHOW_YEAR, "the year is shown only if it is different from the current year, or if the start and end dates fall on different years". A snapshot recorded in December for a range in the same year will gain a year on January 1, and a test that passes on a developer laptop can fail in CI on New Year's Day. Either set FORMAT_SHOW_YEAR where the design always wants a year, or inject a fixed clock in tests. The same habit helps on the web and Apple platforms, where tests should create formatters with an explicit locale and zone instead of reading the machine defaults.
Compare against formatter output, not hand-typed strings. Range separators include U+2009 thin spaces in English and U+202F narrow no-break spaces before AM and PM, so "Mar 3 - 5, 2026" typed into a test will never match. Build expected values from parts, or assert structure: one startRange day, one endRange day, shared month and year.
A practical test matrix for each range surface:
| Case | Example input | What to assert |
|---|---|---|
| Same day | 10:00 to 11:00 | One date, collapsed time range |
| Same month | Mar 3 to Mar 5 | Month and year shared once |
| Cross month | Mar 3 to Apr 2 | Both months, one year |
| Cross year | Dec 27 to Jan 3 | Both years, correct year field |
| Midnight end | Nov 10 to Nov 12 00:00 | Last day matches your end semantics |
| Overnight time | 19:00 to 02:00 | Accepted dated form or your time-only design |
| Zone shift | Same instants, two zones | Dates follow the event zone |
| App language differs from device | Device en-US, app de | German output |
| 24-hour device setting | en-US with 24-hour time | Time style follows the setting |
Run it in English, in a trailing-month locale such as German, and in Korean or Japanese.
Failure handling and tradeoffs
Keep a fallback for runtimes without interval support, and make it honest. The Runebook formatRange article shows the common fallback of formatting each date and joining them with a separator. That is acceptable as a last resort if the separator comes from a localized message, both ends use the same zone and locale, and you log that the fallback ran. It is not acceptable as the main path.
Accept that range strings are opaque. MDN describes range output as localized and opaque, which is why parts exist. Do not parse range strings back into dates, do not truncate them to fit a chip, and do not upper-case them for a header. If a layout cannot fit the long form, pick a shorter skeleton (abbreviated month, no weekday) and let the formatter choose the pattern.
Expect output to change across ICU and OS updates. CLDR data is versioned, so separators and spacing can shift between releases. Tests that compare to formatter output generated in the same run survive that; golden strings checked into the repository do not.
What most guides leave out
Most guides stop at the web API. The OpenReplay Intl guide shows one formatRange call with dateStyle: 'medium', and the browser-focused pages cover fallbacks. None of them connects end-date semantics, the event's time zone, app-language binding, and year-dependent output, and those gaps are what put wrong dates on screen.
Next step
Search your codebase for range helpers: string templates with " - " or " to " between two formatted dates, calls to formatDateRange without FORMAT_SHOW_YEAR, and DateIntervalFormatter instances with no locale or timeZone set. Pick the busiest surface, usually the booking or event card, write down whether its end is inclusive or exclusive and which zone it belongs to, switch it to the platform interval formatter with the app locale, and add the nine-case matrix above to its tests before moving to the next screen.
