A fully spec-compliant polyfill for 'Intl.ListFormat'
![Support on Patreon](https://img.shields.io/badge/patreon-donate-green.svg)
Description
This is a 1:1 implementation of the Intl.ListFormat
draft spec proposal ECMA-402, or the ECMAScript® Internationalization API Specification.
The Intl.ListFormat
object is a constructor for objects that enable language-sensitive list formatting.
It 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 another member of the Intl
family: Intl.getCanonicalLocales
, so this must be polyfilled. See this section for an overview.
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.
Table of Contents
Install
NPM
$ npm install intl-list-format
Yarn
$ yarn add intl-list-format
Applying the polyfill
The polyfill will check for the existence of Intl.ListFormat
and will only be applied if the runtime doesn't already support it.
To include it, add this somewhere:
import "intl-list-format";
require("intl-list-format");
However, it is strongly suggested that you only include the polyfill for runtimes that don't already support Intl.ListFormat
.
One way to do so is with an async import:
if (!("ListFormat" in Intl)) {
await import("intl-list-format");
require("intl-list-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:
import "intl-list-format";
import "intl-list-format/locale-data/en";
And naturally, it also works with commonjs:
require("intl-list-format");
require("intl-list-format/locale-data/en");
Remember, if you're also depending on a polyfilled version of Intl.getCanonicalLocales
, you will need to import that polyfill beforehand.
Usage
The following examples are taken directly from the original proposal
Intl.ListFormat.prototype.format
const lf = new Intl.ListFormat("en", {
localeMatcher: "best fit",
type: "conjunction",
style: "long"
});
lf.format(["Motorcycle", "Truck", "Car"]);
Intl.ListFormat.prototype.formatToParts
const lf = new Intl.ListFormat("en");
lf.formatToParts(["Foo", "Bar", "Baz"]);
Intl.ListFormat.prototype.resolvedOptions
const lf = new Intl.ListFormat("en", { type: "unit", style: "narrow" });
lf.resolvedOptions();
Intl.ListFormat.supportedLocalesOf
Intl.ListFormat.supportedLocalesOf(["foo", "bar", "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
String.prototype.replace
Symbol.toStringTag
,WeakMap
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
Backers
Patreon
Become a backer and get your name, avatar, and Twitter handle listed here.
![Backers on Patreon](https://patreon-badge.herokuapp.com/11315442.png)
FAQ
What is the default locale?
The default locale will be equal to the locale file you load first.
Are there any known quirks?
Nope!
License
MIT © Frederik Wessberg (@FredWessberg) (Website)