Intl and IntlHelper for all Date, Time, Number and Collators

[Zibi Braniecki]

Hi Gaia Devs!

I'm pleased to announce that we just landed IntlHelper that makes working with Intl API much easier for our apps.

In 2.5 cycle we are migrating away from using l10n_date and mozL10n.DateTimeFormat custom DIY solution to JS standard which is faster, more robust and removes a burden on our localizers.

That means that wherever you need to use absolute dates (relative dates are not covered yet[0]), instead of using the old mozL10n.DateTimeFormat, use Intl API[1].

The simplest use of Intl API is a method on Date object:

var x = new Date();
x.toLocaleString(navigator.languages, {
day: 'numeric',
month: 'numeric'
});

but there are several problems with this approach. First, it's not very fast. If your code is performance sensitive, this method creates a new formatter on every call.

For that, Intl API provides a way to offload the costly part and create a formatter that you can then use in a hotpath:

var formatter = Intl.DateTimeFormat(navigator.languages, {
day: 'numeric',
month: 'numeric'
});

for (var i = 0; i <messages.length; i++) {
messages[i].dateElement.textContent = formatter.format(messages[i].date);
}

But secondly, it doesn't work well with language changes and time format (12/24h clock) changes on fly.

Here comes IntlHelper. IntlHelper allows you to define your DateTimeFormats, NumberFormats and Collators, name them and makes it easy to refire formatting/sorting/searching functions when your Intl object is affected by some change like languagechange or timeformatchange (or others in the future).

The code is in https://github.com/mozilla-b2g/gaia/blob/master/shared/js/intl_helper.js

The way it works:

IntlHelper.define('shortDate', 'datetime', {
day: 'numeric',
month: 'numeric'
});

function setValue() {
const formatter = IntlHelper.get('shortDate');
element.textContent = formatter.format(currentDate);
}

setValue();

IntlHelper.observe('shortDate', setValue); // first argument may be an array of multiple names if setValue reformats multiple

>From that moment, anytime your formatter has to be recreated, we will fire setValue for you and you will get new formatter.

We will also handle timeformat for you, so no need to define that, just do:

IntlHelper.define('shortTime', 'datetime', {
hour: 'numeric',
});

and we'll recognize that this formatter uses 'hour' and will fire the setValue callback when timeformatchanges and add it to the DateTimeFormat options for you.
In the future we'll also handle pseudo-locales in IntlHelper.

I'll document that in our docs, but first wanted to get this to you in case you have any questions or feedback.
And please, start using it for all Date, Time, sorting, searching and Number formatting.

It's a huge step to get our UI to be more localizable.

Thanks!
zb.

[0] https://github.com/tc39/ecma402/issues/35
[1] https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl