relative-time-format

A convenient Intl.RelativeTimeFormat polyfill.

No dependencies (doesn't require Intl.PluralRules because it's already built in).

See Demo

Install

npm install relative-time-format --save

If you're not using a bundler then use a standalone version from a CDN.

Use

import RelativeTimeFormat from "relative-time-format"
import en from "relative-time-format/locale/en.json"

RelativeTimeFormat.addLocale(en)

// Returns "2 days ago"
new RelativeTimeFormat("en", {
  style: "long" // "long" is the default. Other options: "short", "narrow".
}).format(-2, "day")

Locales

The localization resides in the locale folder. The format of a localization is:

{
  …
  "day": {
    "past": {
      "one": "{0} day ago",
      "other": "{0} days ago"
    },
    "future": {
      "one": "in {0} day",
      "other": "in {0} days"
    }
  },
  …
}

The past and future can be defined by any of: zero, one, two, few, many and other. For more info on which is which read the official Unicode CLDR documentation. Unicode CLDR (Common Locale Data Repository) is an industry standard and is basically a collection of formatting rules for all locales (date, time, currency, measurement units, numbers, etc). All localizations come from cldr-dates-full package (for example, en-US).

To determine whether a certain amount of time (number) is one, few, or something else, relative-time-format uses Unicode CLDR rules for formatting plurals. These rules are number quantifying functions (one for each locale) which can tell if a number should be treated as zero, one, two, few, many or other. Knowing how these pluralization rules work is not required but anyway here are some links for curious advanced readers: rules explanation, list of rules for all locales, list of rules for all locales in JSON format (part of cldr-core/supplemental package), converting those rules to javascript functions. These quantifying functions can be found as quantify properties of a locale data.

The locale folder is generated from CLDR data by running:

npm run generate-locales

Locale data is extracted from cldr-data (quantifiers) and cldr-dates-full (relative time messages) packages which usually get some updates once or twice a year.

npm install [email protected] [email protected] [email protected] --save-dev
npm run generate-locales

Higher-level API

Intl.RelativeTimeFormat is intentionally a low-level API. Third-party libraries are supposed to be built on top of this base-level API. An example of such library is javascript-time-ago which uses Intl.RelativeTimeFormat internally and provides a higher-level API:

import TimeAgo from 'javascript-time-ago'

// Load locale-specific relative date/time formatting rules.
import en from 'javascript-time-ago/locale/en'

// Add locale-specific relative date/time formatting rules.
TimeAgo.addLocale(en)

// Create relative date/time formatter.
const timeAgo = new TimeAgo('en-US')

timeAgo.format(new Date())
// "just now"

timeAgo.format(Date.now() - 60 * 1000)
// "a minute ago"

timeAgo.format(Date.now() - 2 * 60 * 60 * 1000)
// "2 hours ago"

timeAgo.format(Date.now() - 24 * 60 * 60 * 1000)
// "a day ago"

CDN

One can use any npm CDN service, e.g. unpkg.com or jsdelivr.net

<script src="https://unpkg.com/[email protected][version]/bundle/relative-time-format.js"></script>

<script>
  var en = ... // Somehow import `relative-time-format/locale/en.json`.
  RelativeTimeFormat.addLocale(en)
  console.log(new RelativeTimeFormat('en').format(-1, 'day'))
</script>

where [version] is an npm package version range (for example, 0.2.x or ^0.2.0).

Test262

There's a test suite of about 150 test cases for Intl.RelativeTimeFormat specification implementations. It's called "Test262". These tests check every possible imaginable aspect of formal correctness of a spec implementation including the weirdest artificial cases imaginable like accepting strings instead of numbers, accepting objects having keys 0, 1, etc instead of arrays, accepting objects with toString() method instead of strings, defining all class methods as special "non-enumerable" properties via Object.defineProperty() instead of the regular way everyone defines class methods in real life, and so on. Handling all these formal edge cases would result in an unnecessarily convoluted and less readable code and I'd prefer to keep things simple and elegant, so this library intentionally chose not to pass all of the "Test262" test cases while still passing most of them: it passes the functional correctness part and skips the not-relevant-in-real-life cases part.

License

MIT