intl-relative-time-format: A TypeScript repository from wessberg

A fully spec-compliant polyfill for 'Intl.RelativeTimeFormat'

Description

This is a 1:1 implementation of the Intl.RelativeTimeFormat draft spec proposal ECMA-402, or the ECMAScript® Internationalization API Specification. Intl.RelativeTimeFormat is a really useful low-level primitive to build on top of which avoids the need to parse lots of CLDR raw data at the expense of your users and their internet connections.

It builds upon other members of the Intl family such as Intl.PluralRules, Intl.NumberFormat, and Intl.getCanonicalLocales, so these must be polyfilled. See this section for an overview.

This implementation passes all 150 Test262 Conformance tests from the Official ECMAScript Conformance Test Suite.

Features

Some highlights of this polyfill include:

A very precise implementation of the spec, with cross-references inlined in the source code
Conditional loading of Locale data for all CLDR locales
Well-tested and well-documented.
Passes all Official ECMAScript Conformance Tests

Description
- Features
Table of Contents
Install
- NPM
- Yarn
Applying the polyfill
Loading locale data
Usage
Dependencies & Browser support
Contributing
Maintainers
Backers
- Patreon
FAQ
- What is the default locale?
- Are there any known quirks?
License

Install

NPM

$ npm install intl-relative-time-format

Yarn

$ yarn add intl-relative-time-format

Applying the polyfill

The polyfill will check for the existence of Intl.RelativeTimeFormat and will only be applied if the runtime doesn't already support it.

To include it, add this somewhere:

import "intl-relative-time-format";

// Or with commonjs:
require("intl-relative-time-format");

However, it is strongly suggested that you only include the polyfill for runtimes that don't already support Intl.RelativeTimeFormat. One way to do so is with an async import:

if (!("RelativeTimeFormat" in Intl)) {
	await import("intl-relative-time-format");

	// or with commonjs:
	require("intl-relative-time-format");
}

Alternatively, you can use Polyfill.app which uses this polyfill and takes care of only loading the polyfill if needed as well as adding the language features that the polyfill depends on (See dependencies).

Loading locale data

By default, no CLDR locale data is loaded. Instead, you decide what data you want. To load data, you can import it via the /locale-data subfolder that comes with the NPM package:

With ES modules:

// Load the polyfill
import "intl-relative-time-format";

// Load data for the 'en' locale
import "intl-relative-time-format/locale-data/en";

And naturally, it also works with commonjs:

// Load the polyfill
require("intl-relative-time-format");

// Load data for the 'en' locale
require("intl-relative-time-format/locale-data/en");

Remember, if you're also depending on a polyfilled version of Intl.NumberFormat, Intl.getCanonicalLocales, and/or Intl.PluralRules, you will need to import those polyfills beforehand.

Usage

The following examples are taken directly from the original proposal

Intl.RelativeTimeFormat.prototype.format

// Create a relative time formatter in your locale
// with default values explicitly passed in.
const rtf = new Intl.RelativeTimeFormat("en", {
	localeMatcher: "best fit", // other values: "lookup"
	numeric: "always", // other values: "auto"
	style: "long" // other values: "short" or "narrow"
});

// Format relative time using negative value (-1).
rtf.format(-1, "day");
// > "1 day ago"

// Format relative time using positive  value (1).
rtf.format(1, "day");
// > "in 1 day"

// Create a relative time formatter in your locale
// with numeric: "auto" option value passed in.
const rtf = new Intl.RelativeTimeFormat("en", {numeric: "auto"});

// Format relative time using negative value (-1).
rtf.format(-1, "day");
// > "yesterday"

// Format relative time using positive day unit (1).
rtf.format(1, "day");
// > "tomorrow"

Intl.RelativeTimeFormat.prototype.formatToParts

const rtf = new Intl.RelativeTimeFormat("en", {numeric: "auto"});

// Format relative time using the day unit.
rtf.formatToParts(-1, "day");
// > [{ type: "literal", value: "yesterday"}]

rtf.formatToParts(100, "day");
// > [{ type: "literal", value: "in " }, { type: "integer", value: "100", unit: "day" }, { type: "literal", value: " days" }]

Intl.RelativeTimeFormat.prototype.resolvedOptions

const rtf = new Intl.RelativeTimeFormat("en", {
	numeric: "always",
	style: "narrow"
});

rtf.resolvedOptions();
// > [{ locale: "en", numberingSystem: "latn", numeric: "always", style: "narrow"}]

Intl.RelativeTimeFormat.supportedLocalesOf

Intl.RelativeTimeFormat.supportedLocalesOf(["foo", "bar", "en-US"]);
// > ["en-US"]

Dependencies & Browser support

This polyfill is distributed in ES3-compatible syntax, but is using some additional APIs and language features which must be available:

Array.prototype.includes
Object.create
Object.is
Number.prototype.toLocaleString
String.prototype.includes
String.prototype.replace
Symbol.toStringTag,
WeakMap
Intl.NumberFormat
Intl.PluralRules
Intl.getCanonicalLocales

For by far the most browsers, these features will already be natively available. Generally, I would highly recommend using something like Polyfill.app which takes care of this stuff automatically.

Contributing

Do you want to contribute? Awesome! Please follow these recommendations.

Maintainers


Frederik Wessberg Twitter: @FredWessberg Lead Developer

wessberg/intl-relative-time-format