Simplifying Relative Time Representations in JavaScript

Dealing with time in web applications often involves displaying relative time representations, such as "2 hours ago" or "in 3 days." JavaScript provides a powerful tool to make this task easier and more language-aware through the Intl.RelativeTimeFormat object. In this blog post, we'll explore the world of Intl.RelativeTimeFormat and how it simplifies working with relative time.

Introduction to Intl.RelativeTimeFormat

The Intl.RelativeTimeFormat object is part of the Internationalization API, just like Intl.DateTimeFormat. It's designed to format time intervals in a human-readable way by taking into account the user's preferred language and region.

With Intl.RelativeTimeFormat, you can:

1. Format time intervals as relative times (e.g., "in 5 minutes" or "2 weeks ago").
2. Display time intervals in a way that respects grammatical rules of different languages.
3. Customize the formatting to suit your application's needs.

Basic Usage

Let's begin with a basic example. To create a new instance of Intl.RelativeTimeFormat, you'll pass two arguments: the user's locale and an options object. The options object allows you to customize how the relative time is displayed.

const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
console.log(rtf.format(-2, 'day')); // "2 days ago"
console.log(rtf.format(3, 'hour')); // "in 3 hours"

In this example, we create an rtf object that formats relative time in English ('en') with 'auto' numeric style, which means it will automatically choose between 'numeric' and 'long' formats based on the value.

To format a relative time, you can use the format method of the rtf object, passing in the numeric value and the unit:

Localization and Internationalization

Much like Intl.DateTimeFormat, Intl.RelativeTimeFormat is excellent for handling internationalization. By specifying different locales, you can easily display relative times in various languages and formats.

const rtfSpanish = new Intl.RelativeTimeFormat('es', { numeric: 'auto' });

console.log(rtfSpanish.format(-2, 'day')); // "hace 2 días"
console.log(rtfSpanish.format(3, 'hour')); // "en 3 horas"

This code creates an rtfSpanish object for the Spanish ('es') locale, allowing you to display relative times in Spanish.

Below is another example using Standard Chinese

// Chinese relative time format
const chineseFormat = new Intl.RelativeTimeFormat("zh", { numeric: "auto" });
console.log(chineseFormat.format(-2, "day")); // "前天"
console.log(chineseFormat.format(3, "hour")); // "3小时后"

Intl.RelativeTimeFormat takes care of converting numeric values and units into a meaningful and localized relative time string.

Customizing Relative Time Formatting

Customization is where Intl.RelativeTimeFormat truly shines. You can control how relative time is displayed by tweaking the options object when creating an instance. Some commonly used options include:

• numeric: This option can be set to always or auto. 'always' will always use numeric representations (e.g., "5 days"), while 'auto' will choose between numeric and long forms based on the value (e.g., "in 2 weeks" or "yesterday").

const autoNumeric = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
console.log(autoNumeric.format(-1, "day")); // yesterday
console.log(autoNumeric.format(1, "month")); // next month

const alwaysNumeric = new Intl.RelativeTimeFormat("en", { numeric: "always" });
console.log(alwaysNumeric.format(-1, "day")); // 1 day ago
console.log(alwaysNumeric.format(1, "month")); // in 1 month

• style: You can set this to 'long', 'short', or 'narrow' to control the style of units. For example, 'long' might display "3 days ago," while 'short' displays "3d ago."

Here's an example of customizing the formatting:

const customRTF = new Intl.RelativeTimeFormat("en", {
  style: "short",
});

console.log(customRTF.format(3, "hour")); // "in 3 hr."

// long
console.log(customRTF.format(3, "hour")); // "in 3 hours"
// narrow
console.log(customRTF.format(3, "hour")); // "in 3h"

Browser Support

Intl.RelativeTimeFormat is supported in most modern web browsers, including Chrome, Firefox, Safari, and Edge.

Conclusion

Intl.RelativeTimeFormat is a powerful tool for simplifying the display of relative time intervals in web applications. It brings internationalization and localization to your relative time representations, making your application more user-friendly and culturally sensitive. By mastering this API, you can provide a more seamless experience for users around the world, enhancing the usability and accessibility of your web applications.