The ECMAScript Internationalization API

[2013-09-22] dev, javascript, jslang
(Ad, please don’t block)
The ECMAScript Internationalization API is a standard JavaScript API that helps with tasks related to internationalization: collation, number formatting, date and time formatting. This blog post gives a brief overview and points to more reading material.

The ECMAScript Internationalization API, edition 1

The first edition of the API provides the following services:
  • Collation. supports two scenarios: sorting a set of strings and searching within a set of strings. Collation is parameterized by locale and aware of Unicode.
  • Number formatting. Parameters include:
    • Style of formatting: decimal, currency (which one and how to refer to it, is determined by other parameters), percent.
    • Locale (directly specified or best fit, searched for via a matcher object)
    • Numbering system (Western digits, Arabic digits, Thai digits, etc.)
    • Precision: number of integer digits, fraction digits, significant digits
    • Grouping separators on or off
  • Date and time formatting. Parameters include:
    • what information to format and in which style (short, long, numeric, etc.)
    • a locale
    • a time zone
Most of the functionality is accessed via an object in the global variable Intl, but the API also augments the following methods:
  • String.prototype.localeCompare
  • Number.prototype.toLocaleString
  • Date.prototype.toLocaleString
  • Date.prototype.toLocaleDateString
  • Date.prototype.toLocaleTimeString

What kind of standard is it?

The number of the standard “ECMAScript Internationalization API” (EIA) is ECMA-402. It is hosted by Ecma International, the same association that also hosts EMCA-262, the ECMAScript language specification. Both standards are maintained by TC39 [1]. Therefore, EIA is as close to language as you can get without being part of ECMA-262. The API has been designed to work with both ECMAScript 5 and ECMAScript 6.

A set of conformance tests complements the standard and ensures that the various implementations of the API are compatible (ECMA-262 has a similar test suite).

When can I use it?

Google Chrome and Internet Explorer 11 support the API, support in Firefox Nightly must be switched on via a flag. David Storey has created a detailed compatibility table (which browsers support which locales etc.).

Upcoming: edition 2

Work on edition 2 of the API is ongoing. The Internationalization API wiki gives first clues as to what features will be included in that edition. Three examples from the wiki page with strawman proposals:
  • Message formatting: format a string with placeholders, including plural and gender support.
  • Parsing numbers.
  • Text segmentation: break text into grapheme clusters, words, lines, and sentences.
Edition 2 will be based on ECMAScript 6, it will not be compatible with ECMAScript 5, any more.

Further reading

The specification of the ECMAScript Internationalization API is edited by Norbert Lindenberg. It is available in the formats PDF, HTML and EPUB. Additionally, there are several comprehensive introductory articles:


  1. A JavaScript glossary: ECMAScript, TC39, etc.