Tristan Labelle

Internationalizing Dates and Times for Couchers.org

Couchers.org is an international community of travelers meeting up around the globe, which opens the door to a surprising number of ways that dates and times on the platform can cause misunderstandings. Since joining the project, I've been working on such aspects of internationalization, and in this post I'll be presenting related technical challenges and solutions.

Localization

We support Couchers.org users speaking various languages with translated version of our apps, but localizing dates and times is tricky because everything can change: the names of the days and months, the order of components (year-month-day or day-month-year?), 12-hour vs 24-hour clock, separators, etc. This is a lot of complexity to implement.

Thankfully, the Unicode CLDR provides an industry-standard dataset of localized formats, so we don't need to know the details of how to put together a date in Chinese or German. Better yet, it ships with every browser via the Intl.DateTimeFormat API, and we can likewise use it in our Python backend via the babel library. That's a good start!

Flexible formats

Dates and times come in various formats throughout Couchers.org: you can schedule an event from one date and time to another, you can request to be hosted between a start and an end date, you can view the local time in another user's time zone in hours and minutes, and the date they joined the platform in months and years. It's useful to show the day of the week for events and host requests, but not so much for a user's session expiration date and time.

Date and time formatting libraries usually have built-in short and long formats, but this doesn't provide enough control for our needs. While the Unicode CLDR has flexible building blocks for custom date and time formats, the way they are exposed in libraries such as JavaScript's Intl.DateTimeFormat requires getting a lot of parameters right.

We ended up defining simple and intuitive functions that build on the Unicode CLDR: localizeDateTime(dateTime, locale), and their localizeDate and localizeTime variants. These take a date-time object and a locale, and default to producing longform strings with all basic information, for example "10 septembre 2026 à 09:40" in French. Various optional parameters then allow customizing it: includeDayOfWeek, omitCurrentYear, includeSeconds, abbreviate. This ensures that even developers not familiar with the intricacies of date and time internationalization can get it right.

The en-US case

U.S. English is mostly unique in using month-day-year dates (MM/DD/YYYY), and this is the format that the Unicode CLDR assigns to the generic English en locale. This is a problem for Couchers.org because many of our worldwide users use our website in English, with their browsers requesting the en locale, but they get confused with the unfamiliar ordering, resulting in incorrect birthdates, event and host request dates.

To fix this, we split our English language into two: "English" and "English (US)". The former uses the en locale, but which we remap to en-001 (Global English) for formatting operations, and the latter uses the en-US locale. We still have a single translation, generally based on American English, but this ensures that our worldwide English users see more familiar DD/MM/YYYY dates.

At this time, English is the only language that we split into two locales to resolve formatting ambiguities.

Time zones

Couchers.org users regularly arrange stays or register for events in other countries, so our platform needs to help avoid confusion with different time zones. In general, people expect dates and times to be expressed in the local time zone at the location in question. We had several bugs where this was not the case, but could appear so under simple testing conditions.

The solution is mostly technical: when dealing with dates and times, we must clearly disambiguate the concept of an instant and that of date-time components. An instant is a point in time, for example when the Tokyo fireworks went off for year 2000, which is independent from what different clocks around the world were indicating at that time. Instants are often represented as UNIX timestamps, or milliseconds since January 1st 1970 UTC. Date-time components are the year, month, day, hour and minute values that are used to represent time in written form. The key is that instants and date-time components are only related within the context of a specific time zone.

Older programming languages and their standard libraries tend to conflate the two concepts by assuming the machine's time zone, so we solved most of our problems by switching to more modern date APIs. In our TypeScript frontend, we removed usages of the old Date type in favor of the new Temporal APIs, especially Temporal.Instant and Temporal.PlainDateTime. For example, our localizeDateTime function takes a Temporal.PlainDateTime, forcing the calling code to account for any time zone conversions. In our Python backend, we made sure every datetime was time zone-aware. Finally, in our protocol buffer API, we carefully represent instants as timestamps and date-time components as ISO8601 strings ("YYYY-MM-DDTHH:MM").

As an example, when creating an event, date and time information entered by the user is represented as a Temporal.PlainDateTime on the frontend, then sent as a ISO8601 string to the backend, and only resolved to a time zone-aware datetime (an instant) after looking up the time zone at the provided geographical location.

Conclusion

Dates and times expose all the messiness of human languages and cultures, so internationalizing them is not without its challenges. When done right, international users won't even notice it, and on Couchers.org, I hope that means they'll simply get to their host's place or next event at the scheduled time.

Thoughts or feedback? Send me an email.