globalize

New age globalization and localization. Formats and parses strings, dates and numbers in over 350 cultures.

npm install globalize
59 downloads in the last day
295 downloads in the last week
1 182 downloads in the last month

Globalize

Build Status devDependency Status devDependency Status

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.

Heads up!

This is an alpha 1.x version

We're working on the migration to using the Unicode CLDR. This is an alpha version of Globalize. In other words, this is not a software for production environment (yet).

Not accepting 0.x fixes anymore

Patches to the previous 0.x codebase probably can't be used. If you have a problem, please create an issue first before trying to patch it.

Are you looking for 0.x docs? Find them here.

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.

Where to use it?

It's 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 size Summary
globalize.js 0.4KB Core library
globalize/date.js +9.2KB Date module provides date formatting and parsing
globalize/number.js +3.7KB Number module provides number formatting and parsing
globalize/translate.js +0.7KB Message module provides message translation

Browser Support

We officially support http://jquery.com/browser-support/. If you find any bugs, please just let us know.

Getting Started

Requirements

1. Dependencies

You need to satisfy Globalize dependencies prior to using it. The good news is, there is only one. It's the cldr.js, which is a CLDR low level manipulation tool.

If you use a package manager like bower or npm, you don't need to worry about it. If this isn't the case, then you need to manually download cldr.js yourself. Check the Hello World examples for more information.

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
Number module cldr/main/locale/numbers.json
Date module cldr/main/locale/ca-gregorian.json
cldr/supplemental/timeData.json
cldr/supplemental/weekData.json

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

Learn how to get and load CLDR content....

Installation

By downloading a ZIP or a TAR.GZ...

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

By using a package manager...

Use bower bower install globalize, or npm npm install globalize.

By using source files...

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

Usage

Globalize's consumable-files are located in the ./dist directory. If you don't find it, it's because you are using a development branch. You should either use a tagged version or build the distribution files yourself. Read installation above if you need more information on how to download.

Globalize can be used for a variety of different i18n tasks, eg. formatting or parsing dates, formatting or parsing numbers, formatting messages, etc. You may NOT need Globalize in its entirety. For that reason, we made it modular. So, you can cherry-pick the pieces you need, eg. load dist/globalize.js to get Globalize core, load dist/globalize/date.js to extend Globalize with Date functionalities, etc.

An example is worth a thousand words. Check out our Hello World demo (available to you in different flavors):

API

Core module

  • Globalize.load( cldrJSONData )

    This method allows you to load CLDR JSON locale data. Globalize.load() is a proxy to Cldr.load().

    Read more...

  • Globalize.locale( [locale] )

    Set default locale, or get it if locale argument is omitted.

    Read more...

Number module

  • Globalize.formatNumber( value [, attributes] [, locale] )

    Format a number according to the given attributes and the given locale (or the default locale if not specified).

    Read more...

  • Globalize.parseNumber( value [, formats], [locale] )

    TBD

Date module

  • Globalize.formatDate( value, format [, locale] )

    Format a date according to the given format and locale (or the current locale if not specified).

    Read more...

  • Globalize.parseDate( value [, formats] [, locale] )

    Parse a string representing a date into a JavaScript Date object, taking into account the given possible formats (or the given locale's set of preset formats if not provided). As before, the current locale is used if one is not specified.

    Read more...

Message module

  • Globalize.loadMessages( locale, messageData )

    Load message data per locale.

    Read more...

  • Globalize.translate( path [, locale] )

    Translate item given its path.

    Read more...

Development

File structure

├── bower.json (metadata file)
├── CONTRIBUTING.md (doc file)
├── dist/ (consumable files, the built files)
├── external/ (external dependencies, eg. cldr.js, QUnit, RequireJS)
├── Gruntfile.js (Grunt tasks)
├── LICENSE (license file)
├── package.json (metadata file)
├── README.md (doc file)
├── src/ (source code)
│   ├── build/ (build helpers, eg. intro, and outro)
│   ├── common/ (common function helpers across modules)
│   ├── core.js (core module)
│   ├── date/ (date source code)
│   ├── date.js (date module)
│   ├── translate.js (translate module)
│   └── util/ (basic JavaScript helpers polyfills, eg array.map)
└── test/ (unit and functional test files)
    ├── fixtures/ (CLDR fixture data)
    ├── functional/ (functional tests)
    ├── functional.html
    ├── functional.js
    ├── unit/ (unit tests)
    ├── unit.html
    └── unit.js

Source files

The source files are as granular as possible. When combined to generate the build file, all the excessive/overhead wrappers are cut off. It's following the same build model of jQuery and Modernizr.

Core, and all modules' public APIs are located in the src/ directory. For example: core.js, date.js, and translate.js.

Build

Install Grunt and external dependencies. First, install the grunt-cli and bower packages if you haven't before. These should be installed globally (like this: npm install -g grunt-cli bower). Then:

npm install && bower install

Build distribution files.

grunt

Tests

Tests can be run either in the browser or using Node.js (via Grunt).

Unit tests

To run the unit tests, run grunt test:unit, or open file:///.../globalize/test/unit.html in a browser. It tests the very specific functionality of each function (sometimes internal/private).

The goal of the unit tests is to make it easy to spot bugs, easy to debug.

Functional tests

To run the functional tests, create the dist files by running grunt. Then, run grunt test:functional, or open file:///.../globalize/test/functional.html in a browser. Note that grunt will automatically run unit and functional tests for you to ensure the built files are safe.

The goal of the functional tests is to ensure that everything works as expected when it is combined.

License

MIT © jQuery Foundation and other contributors.

npm loves you