Globalize

A JavaScript library for internationalization and localization that leverage the official Unicode CLDR JSON data. The library works both for the browser and as a Node.js module.

• About Globalize
• Why globalization?
• Why Globalize?
• Migrating from Globalize 0.x
• Where to use it?
• Where does the data come from?
• Only load and use what you need
• Browser support
• Getting started
• Requirements
• Installation
• Usage
• Performance
• Compilation and the Runtime modules
• Examples
• Community
• API
• Core
• Date module
• Message module
• Number module
  • Currency module
• Plural module
• Relative time module
• Unit module
• more to come...
• Error reference
• Contributing
• Roadmap
• Development
• File structure
• Source files
• Tests
• Build

About Globalize

Why globalization?

Each language, and the countries that speak that language, have different expectations when it comes to how numbers (including currency and percentages) and dates should appear. Obviously, each language has different names for the days of the week and the months of the year. But they also have different expectations for the structure of dates, such as what order the day, month and year are in. In number formatting, not only does the character used to delineate number groupings and the decimal portion differ, but the placement of those characters differ as well.

A user using an application should be able to read and write dates and numbers in the format they are accustomed to. This library makes this possible, providing an API to convert user-entered number and date strings - in their own format - into actual numbers and dates, and conversely, to format numbers and dates into that string format.

Even if the application deals only with the English locale, it may still need globalization to format programming language bytes into human-understandable language and vice-versa in an effective and reasonable way. For example, to display something better than "Edited 1 minutes ago".

Why Globalize?

Globalize provides number formatting and parsing, date and time formatting and parsing, currency formatting, message formatting (ICU message format pattern), and plural support.

Design Goals.

• Leverages the Unicode CLDR data and follows its UTS#35 specification.
• Keeps code separate from i18n content. Doesn't host or embed any locale data in the library. Empowers developers to control the loading mechanism of their choice.
• Allows developers to load as much or as little data as they need. Avoids duplicating data if using multiple i18n libraries that leverage CLDR.
• Keeps code modular. Allows developers to load the i18n functionalities they need.
• Runs in browsers and Node.js, consistently across all of them.
• Makes globalization as easy to use as jQuery.

Globalize is based on the Unicode Consortium's Common Locale Data Repository (CLDR), the largest and most extensive standard repository of locale data available. CLDR is constantly updated and is used by many large applications and operating systems, so you'll always have access to the most accurate and up-to-date locale data.

Globalize needs CLDR content to function properly, although it doesn't embed, hard-code, or host such content. Instead, Globalize empowers developers to load CLDR data the way they want. Vanilla CLDR in its official JSON format (no pre-processing) is expected to be provided. As a consequence, (a) Globalize avoids bugs caused by outdated i18n content. Developers can use up-to-date CLDR data directly from Unicode as soon as it's released, without having to wait for any pipeline on our side. (b) Developers have full control over which locale coverage they want to provide on their applications. (c) Developers are able to share the same i18n dataset between Globalize and other libraries that leverage CLDR. There's no need for duplicating data.

Globalize is systematically tested against desktop and mobile browsers and Node.js. So, using it you'll get consistent results across different browsers and across browsers and the server.

Globalize doesn't use native Ecma-402 yet, which could potentially improve date and number formatting performance. Although Ecma-402 support is improving among modern browsers and even Node.js, the functionality and locale coverage level varies between different environments (see Comparing JavaScript Libraries slide 25). Globalize needs to do more research and testings to use it reliably.

For alternative libraries and more, check out this JavaScript globalization overview.

Migrating from Globalize 0.x

Are you coming from Globalize 0.x? Read our migration guide to learn what have changed and how to migrate older 0.x code to up-to-date 1.x.

Where to use it?

Globalize is designed to work both in the browser, or in Node.js. It supports both AMD and CommonJS.

Where does the data come from?

Globalize uses the Unicode CLDR, the largest and most extensive standard repository of locale data.

We do NOT embed any i18n data within our library. However, we make it really easy to use. Read How to get and load CLDR JSON data for more information on its usage.

Pick the modules you need

File	Minified + gzipped size	Runtime minified + gzipped size	Summary
globalize.js	1.7KB	1.1KB	Core library
globalize/currency.js	3.0KB	0.7KB	Currency module provides currency formatting
globalize/date.js	7.7KB	4.3KB	Date module provides date formatting and parsing
globalize/message.js	5.3KB	0.7KB	Message module provides ICU message format support
globalize/number.js	4.4KB	2.6KB	Number module provides number formatting and parsing
globalize/plural.js	2.3KB	0.4KB	Plural module provides pluralization support
globalize/relative-time.js	0.8KB	0.5KB	Relative time module provides relative time formatting support
globalize/unit.js	0.9KB	0.6KB	Unit module provides unit formatting support

Browser Support

Globalize 1.x supports the following browsers:

• Chrome: (Current - 1) or Current
• Firefox: (Current - 1) or Current
• Safari: 5.1+
• Opera: 12.1x, (Current - 1) or Current
• IE9+

(Current - 1) or Current denotes that we support the current stable version of the browser and the version that preceded it. For example, if the current version of a browser is 24.x, we support the 24.x and 23.x versions.

Getting Started

npm install globalize cldr-data iana-tz-data

var Globalize = require( "globalize" );
Globalize.load( require( "cldr-data" ).entireSupplemental() );
Globalize.load( require( "cldr-data" ).entireMainFor( "en", "es" ) );
Globalize.loadTimeZone( require( "iana-tz-data" ) );

Globalize("en").formatDate(new Date());
// > "11/27/2015"

Globalize("es").formatDate(new Date());
// > "27/11/2015"

Note cldr-data is an optional module, read CLDR content section below for more information on how to get CLDR from different sources.

The iana-tz-data module is only needed when IANA time zones (via options.timeZone) are used with date functions. Read IANA time zone data below for more information.

Read the Locales section for more information about supported locales. For AMD, bower and other usage examples, see Examples section.

Installation

Downloading a ZIP or tarball archive

Click the GitHub releases tab and download the latest available Globalize package.

Using a package manager

You can use either npm or bower:

• npm install globalize
• bower install globalize

Building from source

1. git clone https://github.com/globalizejs/globalize.git
2. Build the distribution files

Requirements

1. Dependencies

If you use module loading like ES6 import, CommonJS, or AMD and fetch your code using package managers like npm or bower, you don't need to worry about this and can skip reading this section. Otherwise, you need to satisfy Globalize dependencies prior to using it. There is only one external dependency: cldr.js, which is a CLDR low level manipulation tool. Additionally, you need to satisfy the cross-dependencies between modules.

Module	Dependencies (load in order)
Core module	cldr.js
Currency module	globalize.js (core), globalize/number.js, and globalize/plural.js (only required for "code" or "name" styles)
Date module	globalize.js (core) and globalize/number.js
Message module	globalize.js (core) and globalize/plural.js (if using messages that need pluralization support)
Number module	globalize.js (core)
Plural	globalize.js (core)
Relative time module	globalize.js (core), globalize/number.js, and globalize/plural.js
Unit module	globalize.js (core), globalize/number.js, and globalize/plural.js

As an alternative to deducing this yourself, use this online tool. The tool allows you to select the modules you're interested in using and tells you the Globalize files and CLDR JSON that you need.

2. CLDR content

Globalize is the i18n software (the engine). Unicode CLDR is the i18n content (the fuel). You need to feed Globalize on the appropriate portions of CLDR prior to using it.

(a) How do I figure out which CLDR portions are appropriate for my needs?

Each Globalize function requires a special set of CLDR portions. Once you know which Globalize functionalities you need, you can deduce its respective CLDR requirements. See table below.

Module	Required CLDR JSON files
Core module	cldr/supplemental/likelySubtags.json
Currency module	cldr/main/locale/currencies.json

cldr/supplemental/currencyData.json

+CLDR JSON files from number module

+CLDR JSON files from plural module for name style support | | Date module | cldr/main/locale/ca-gregorian.json

cldr/main/locale/timeZoneNames.json

cldr/supplemental/metaZones.json

cldr/supplemental/timeData.json

cldr/supplemental/weekData.json

+CLDR JSON files from number module | | Number module | cldr/main/locale/numbers.json

cldr/supplemental/numberingSystems.json | | Plural module | cldr/supplemental/plurals.json (for cardinals)

cldr/supplemental/ordinals.json (for ordinals) | | Relative time module | cldr/main/locale/dateFields.json

+CLDR JSON files from number and plural modules | | Unit module | cldr/main/locale/units.json

+CLDR JSON files from number and plural module |

As an alternative to deducing this yourself, use this online tool. The tool allows you to select the modules you're interested in using and tells you the Globalize files and CLDR JSON that you need.

(b) How am I supposed to get and load CLDR content?

Learn how to get and load CLDR content... and use Globalize.load() to load it.

3. IANA time zone data

The IANA time zone (tz) database, sometimes called the Olson database, is the standard data used by Unicode CLDR, ECMA-402, Linux, UNIX, Java, ICU, and others. It's used by Globalize to circumvent the JavaScript limitations with respect to manipulating date in time