Status: Stage 1

Champion: Shane F Carr (Google i18n)

Slides:

• Ask for Stage 1 @ 111th Meeting of TC39
• Ask for Stage 2 @ 113th Meeting of TC39

The i18n community has converged on the principle that a number ought to be annotated with the quantity it is measuring. Unlike the localized decimal separators, numbering systems for digits, and grouping strategy, the unit is a core part of the data model to be formatted, not a style that gets applied by the formatter.

For example, when formatting messages, this allows the measurement to be localized with locale unit preferences.

const message = "You are {$distance :unit usage=road} from your destination";
let formatter = new MessageFormat("en", message);
formatter.format({
  distance: /* what goes here? */
})

A number annotated with a unit is the only data type required for MessageFormat 2.0 that does not have an analog in JavaScript. See: List of functions in MessageFormat 2.0.

Adding a new primordial, such as Amount, would solve this problem and multiple others impacting i18n. A key question is how Amount interfaces with Intl and how third-party libraries can implement an Amount-like object. The champions believe that this is a sufficiently different problem space that they are pursuing Intl Unit Protocol as a standalone proposal.

Add a protocol to Intl.NumberFormat.prototype.format that accepts a numeric type paired with a unit. The protocol should also be accepted by Intl.PluralRules.prototype.select.

Given these inputs:

let locale = /* an Intl.Locale, a string, or a list of these */;
let unit = /* a string */;
let value = /* a Number, a BigInt, or a string */;

The user can currently write:

let formatter = new Intl.NumberFormat(locale, {
    style: "unit",
    unit,
});
let result = formatter.format(value);

With a protocol, the user can instead write:

let formatter = new Intl.NumberFormat(locale, {
    style: "unit",
});
let result = formatter.format({
    value,
    unit,
});

Intl has long allowed constructors and formatting functions to be separate. This achieves two ends:

1. The formatter can encapsulate the locale and options to specify the style and context of the value being formatted, such as when initializing a templating engine.
2. Locale data can be initialized ahead of time, allowing increased efficiency when formatting multiple items in a loop.

By moving unit from the constructor bucket to the formatting bucket, we advance goal 1.

The proposal comes at some cost to goal 2, since loading the unit display name has some implementation cost that must now be deferred. We will work with ICU[4X] to minimize this cost.

The protocol would allow currency units to be specified in a similar way.

let locale = /* an Intl.Locale, a string, or a list of these */;
let currency = /* a string consisting of 3 upper-case ASCII letters */;
let value = /* a Number, a BigInt, or a string */;

// Today:
let formatter = new Intl.NumberFormat(locale, {
    style: "currency",
    currency,
});
let result = formatter.format(value);

// With the protocol:
let formatter = new Intl.NumberFormat(locale, {
    style: "currency",
});
let result = formatter.format({
    value,
    unit: currency,
});

The protocol accepts objects with a value getter even if their unit getter returns undefined:

let formatter = new Intl.NumberFormat(locale, {
    style: "unit",
    unit,
});
let result = formatter.format({
    value,
});

If the constructor has a unit and the unit is not the same as the one in the protocol, an exception will be thrown, since this is a programmer error.

new Intl.NumberFormat("en", {
    style: "unit",
    unit: "meter",
}).format({
    value: 1234,
    unit: "kilometer",
}) // throws a RangeError

When the Amount proposal advances, this can be changed to automatically convert the input unit to the formatter unit.

If a unit is set in the protocol, but the formatter was not configured with style "unit" or "currency", an error will occur.

This helps implementations know that they need to load unit or currency data in the constructor, partially mitigating the "construction vs formatting" impact discussed above.

let formatter = new Intl.NumberFormat(locale);
let result = formatter.format({
    value,
    unit,
}) // throws a TypeError

Currently, formatting a range requires the units to be equal. This restriction may be relaxed in the future.

new Intl.NumberFormat("en", {
    style: "unit",
    unit: "meter",
}).formatRange({
    value: 1000,
    // if `unit` is not specified, the constructor unit is used
}, {
    value: 2000,
    unit: "meter",
}) // "1000-2000 meters"

The Amount proposal seeks to add a primordial encapsulating a numeric type with a unit. It will implement the Intl protocol specified here.

The Decimal proposal seeks to add a primordial that represents a decimal number in a form designed for correct and efficient arithmetic. It will likely be supported as another number type for the value field in the protocol.

Other fields could be added to this protocol in the future, such as alternative ways of expressing precision or an override to the number of significant digits specified in the constructor.