Simplifying Relative Time Representations in JavaScript
Published: 2023-09-03 18:13:21

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](https://dev.to/diorla/a-guide-to-date-and-time-formatting-in-javascript-2ol2). 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.

```ts
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](https://dev.to/diorla/a-guide-to-date-and-time-formatting-in-javascript-2ol2), `Intl.RelativeTimeFormat` is excellent for handling internationalization. By specifying different locales, you can easily display relative times in various languages and formats.

```javascript
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
```ts
// 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").

```ts
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:

```javascript
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.