Lean-Intl - A leaner and more modern fork of Intl.js

Lean-Intl is a lean polyfill for Intl-APIs for browsers which are not yet supporting this API. It's a modern fork of Intl.js for modern development and tooling requirements.

Introduction

In December 2012, ECMA International published the first edition of Standard ECMA-402, better known as the ECMAScript Internationalization API. This specification provides the framework to bring long overdue localization methods to ECMAScript implementations.

All modern browsers and NodeJS (except Safari <= 10 and IE <= 10) have implemented this API. Lean-Intl fills the void of availability for this API. It will provide the framework as described by the specification, so that developers can take advantage of the native API in environments that support it, or Lean-Intl for legacy or unsupported environments.

See browser support on the official CanIUse Database for details

Changes compared to Intl.js

For Users

• Intl.js is not maintained. It has failing tests. This one is maintained - but nothing more. It does not receive much love other than data updates and dependency updates.
• Both projects are based on the same CLDR data. Intl.js uses version 29.0.0, this one uses 35.0.0. That's a major difference of about three years.
• Updated ECMA Test Suite from 99 tests to 126 tests. Covering a wider range of use cases.
• Removed JSONP data. Replaced with pure JSON (manual addition required, via IntlPolyfill.__addLocaleData()) and JS files (they register automatically + they load the polyfill before as well).
• Removed "complete" UMD package which contains everything - this is not a good use case for browser usage for pure size considerations.
• Responsive author: If there is anything we can fix or you have issues with, let's try to fix it together.

Internal

• Removed previous manual library publishing with Preppy
• Removed special IE8 support in test suite. We are focusing on >= IE10 and other modern browsers.
• Removed HTML output for test suite as we only test compatibility in NodeJS via CI.
• Removed Bower support. That's the past. Either use Webpack or Fusebox, please.
• Cleaned up Readme from old hints on using direct scripts and NodeJS support.
• Prettified source code using Prettier and ESLint.
• Cleaned up dependencies from all unused packages dramatically improving CI speed.

Getting started

Lean Intl is meanted to be used by module bundlers. We are not offering any pre-built browser-ready scripts anymore. In todays landscape it's much better to rely on some kind of bundling for delivering your frontend goods.

• NodeJS is natively supporting Intl. Just make sure to install it with full ICU data for real i18n support. (On Mac this can be easily done via brew install node --with-full-icu)
• For browsers install the package via NPM or Yarn. Then use tools like Webpack, Rollup or Parcel for bundling.

For server side just import the whole package and assign it to the global Intl object:

import Intl from 'intl'
global.Intl = Intl

On the client side decide whether you want to use JS and JSON data packages. JS has the benefit of auto-registration, JSON is slightly smaller (no imports, no registration code) but requires manual work.

Using JS data

import 'lean-intl/locale-data/js/de' // German data
import 'lean-intl/locale-data/js/en' // English data

Using JSON data

import Intl from 'lean-intl'
import esData from 'lean-intl/locale-data/json/es.json'
import frData from 'lean-intl/locale-data/json/fr.json'

global.Intl = global.IntlPolyfill

Intl.__addLocaleData(esData)
Intl.__addLocaleData(frData)

Using conditional loading

import Intl from 'lean-intl'
global.Intl = global.IntlPolyfill

const locale = getBrowserLocale() // requires implementation
const localeData = await import(`lean-intl/locale-data/json/${locale}.json`)
Intl.__addLocaleData(localeData)

Status

Current progress is as follows:

Implemented

• All internal methods except for some that are implementation dependent
• Checking structural validity of language tags
• Canonicalizing the case and order of language subtags
• Intl.NumberFormat
  • The Intl.NumberFormat constructor (11.1)
  • Properties of the Intl.NumberFormat Constructor (11.2)
  • Properties of the Intl.NumberFormat Prototype Object (11.3)
  • Properties of Intl.NumberFormat Instances(11.4)
  • Intl.DateTimeFormat
  • The Intl.DateTimeFormat constructor (12.1)
  • Properties of the Intl.DateTimeFormat Constructor (12.2)
  • Properties of the Intl.DateTimeFormat Prototype Object (12.3)
  • Properties of Intl.DateTimeFormat Instances(12.4)
  • Locale Sensitive Functions of the ECMAScript Language Specification
  • Properties of the Number Prototype Object (13.2)
  • Properties of the Date prototype object (13.3)

Not Implemented

• BestFitSupportedLocales internal function
• Implementation-dependent numbering system mappings
• Calendars other than Gregorian
• Support for time zones
• Collator objects (Intl.Collator) (see below)
• Properties of the String prototype object

A few of the implemented functions may currently be non-conforming and/or incomplete. Most of those functions have comments marked as 'TODO' in the source code.

The test suite is run with Intl.Collator tests removed, and the Collator constructor removed from most other tests in the suite. Also some parts of tests that cannot be passed by a JavaScript implementation have been disabled, as well as a small part of the same tests that fail due to (this bug in v8)[https://code.google.com/p/v8/issues/detail?id=2694].

What about Intl.Collator?

Providing an Intl.Collator implementation is no longer a goal of this project. There are several reasons, including:

• The CLDR convertor does not automatically convert collation data to JSON
• The Unicode Collation Algorithm is more complicated that originally anticipated, and would increase the code size of Lean Intl too much.
• The Default Unicode Collation Element Table is huge, even after compression, and converting to a native JavaScript object would probably make it slightly larger. Server-side JavaScript environments will (hopefully) soon support Intl.Collator, and we can't really expect client environments to download this data.

Compatibility

Lean Intl is designed to be compatible with ECMAScript 3.1 environments in order to follow the specification as closely as possible. However, some consideration is given to legacy (ES3) environments, and the goal of this project is to at least provide a working, albeit non-compliant implementation where ES5 methods are unavailable.

A subset of the tests in the test suite are run in IE 8. Tests that are not passable are skipped, but these tests are mostly about ensuring built-in function behavior.

Locale Data

Lean Intl uses the Unicode CLDR locale data, as recommended by the specification. The main Lean Intl file contains no locale data itself. The data should be loaded as JSON and passed into a JavaScript object using the IntlPolyfill.__addLocaleData() method. Alternatively there is a JS data file available as well for each locale which directly executes that code.

Contents of the locale-data directory are a modified form of the Unicode CLDR data found at http://www.unicode.org/cldr/.

RegExp cache / restore

Lean Intl attempts to cache and restore static RegExp properties before executing any regular expressions in order to comply with ECMA-402. This process is imperfect, and some situations are not supported. This behavior is not strictly necessary, and is only required if the app depends on RegExp static properties not changing (which is highly unlikely). To disable this functionality, invoke Intl.__disableRegExpRestore().

License

This software is licensed under the MIT license. See the LICENSE.txt file accompanying this software for terms of use.

Copyright

Copyright 2013 Andy Earnshaw
Copyright 2016-2019 Sebastian Software GmbH