Skip to content

DriverPackSolution/globalize

BranchesTags
 
 

Repository files navigation

Globalize

Build Status devDependency Status

A JavaScript library for globalization and localization that leverage the official Unicode CLDR JSON data. Run in browsers and node.js.

Heads Up!

We're working the migration to CLDR. This is an alpha version of Globalize: 1.0.0-pre.

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

Getting Started

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.

What about Globalize?

Where to use it?

It's designed to work both in the browser, or in node.js. It supports AMD, and CommonJs;

Where does I18n 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. Although, we make it realy easy to use. Read below How to get and load CLDR JSON data for more information on its usage.

Load and use only what you need

Globalize is split in modules: core, number (coming soon), date, and translate. We're evaluating other modules, eg. plural, ordinals, etc.

The core implements Globalize.load( cldrData ), and Globalize.locale( locale ).

The date module extends core Globalize, and adds Globalize.format( value, pattern, locale ), and Globalize.parseDate( value, patterns, locale ).

The translate module extends core Globalize, and adds Globalize.loadTranslations( locale, json ), and Globalize.translate( path , locale ).

More to come...

Browser Support

We officially support:

  • Firefox (latest - 1)+
  • Chrome (latest - 1)+
  • Safari 5.1+
  • IE 8+
  • Opera (latest - 1)+

Dry tests show Globalize also works on the following browsers:

  • Firefox 4+
  • Safari 5+
  • Chrome 14+
  • IE 6+
  • Opera 11.1+

If you find any bugs, please just let us know. We'll be glad to fix them for the officially supported browsers, or at least update the documentation for the unsupported ones.

Usage

All distributables are UMD wrapped. So, it supports AMD, CommonJS, or global variables (in case neither AMD nor CommonJS have been detected).

Example of usage with script tags:

<script src="./external/cldr/dist/cldr.js"></script>
<script src="./dist/globalize.js"></script>
<script src="./dist/globalize.date.js"></script>

Example of usage on AMD:

bower install cldr.js globalize
require.config({
  paths: {
    cldr: "bower_components/cldr.js/dist/cldr.runtime",
    globalize: "bower_components/globalize/dist/globalize"
  }
});
require( [ "globalize", "globalize/date" ], function( Globalize ) {
  ...
});

Example of usage on node.js:

npm install cldr.js globalize
var Globalize = require( "globalize" );
...

How to get and load CLDR JSON data

CLDR makes available a file for download (json.zip) with the data of the top 20 (by the time of this writting) languages they consider to be the "most used" languages. It contains the complete amount of data per language.

You can generate the JSON representation of the languages not available in the ZIP file by using the official conversion tool (tools.zip). This ZIP contains a README with instructions on how to build the data.

You can opt to generate unresolved data to save space (or bandwidth) (-r false option of the conversion tool), and have it resolved during execution time.

For the examples below, first fetch CLDR JSON data:

wget http://www.unicode.org/Public/cldr/latest/json.zip
unzip json.zip -d cldr

Example of embedding CLDR JSON data:

<script>
Globalize.load({
  main: {
    en: {
      ...
    }
  },
  supplemental: {
    likelySubtags: {
      ...
    },
    timeDate: {
      ...
    },
    weekData: {
      ...
    }
  }
});
</script>

Example of loading it dynamically:

<script src="jquery.js"></script>
<script>
$.get( "cldr/en/ca-gregorian.json", Globalize.load );
$.get( "cldr/supplemental/likelySubtags.json", Globalize.load );
$.get( "cldr/supplemental/timeData.json", Globalize.load );
$.get( "cldr/supplemental/weekData.json", Globalize.load );
</script>

Example on AMD: (also see our functional tests)

define([
  "globalize",
  "json!fixtures/cldr/main/en/ca-gregorian.json",
  "json!fixtures/cldr/supplemental/likelySubtags.json",
  "json!fixtures/cldr/supplemental/timeData.json",
  "json!fixtures/cldr/supplemental/weekData.json",
  "globalize/date"
], function( Globalize, enCaGregorian, likelySubtags, timeData, weekData ) {

  Globalize.load( enCaGregorian );
  Globalize.load( likelySubtags );
  Globalize.load( timeData );
  Globalize.load( weekData );

});

Example on node.js:

var Globalize = require( "globalize" );
Globalize.load( require("./cldr/supplemental/likelySubtags.json") );
Globalize.load( require("./cldr/supplemental/timeData.json") );
Globalize.load( require("./cldr/supplemental/weekData.json") );
Globalize.load( require("./cldr/en/ca-gregorian.json") );

API

Core module

Globalize.load( cldrJSONData )

This method allows you to load CLDR JSON locale data. Globalize.load() is a proxy to Cldr.load(). So, for more information, see https://github.com/rxaviers/cldr.

Parameters:

Globalize.locale( [locale] )

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

Parameters:

  • locale The locale string, eg. "en", "pt_BR", or "zh_Hant_TW".

An application that supports globalization and/or localization will need to have a way to determine the user's preference. Attempting to automatically determine the appropriate culture is useful, but it is good practice to always offer the user a choice, by whatever means.

Whatever your mechanism, it is likely that you will have to correlate the user's preferences with the list of locale data supported in the app. This method allows you to select the best match given the locale data that you have included and to set the Globalize locale to the one which the user prefers.

Globalize.locale( "pt" );
console.log( Globalize.locale().attributes );
// {
//    "languageId": "pt",
//    "maxLanguageId": "pt_Latn_BR",
//    "language": "pt",
//    "script": "Latn",
//    "territory": "BR",
//    "region": "BR"
// }

LanguageMatching TBD (CLDR's spec http://www.unicode.org/reports/tr35/#LanguageMatching).

Date module

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

Format a date according to the given format string and the given locale (or the current locale if not specified). See the section Date Formatting below for details on the available formats. See other modules, eg. number module, for different overloads of Globalize.format().

Parameters:

  • value Date instance to be formatted, eg. new Date();
  • format
    • String, skeleton. Eg "GyMMMd";
    • Object, accepts either one:
      • Skeleton, eg. { skeleton: "GyMMMd" }. List of all skeletons [TODO];
      • Date, eg. { date: "full" }. Possible values are full, long, medium, short;
      • Time, eg. { time: "full" }. Possible values are full, long, medium, short;
      • Datetime, eg. { datetime: "full" }. Possible values are full, long, medium, short;
      • Raw pattern, eg. { pattern: "dd/mm" }. List of all date patterns;
  • locale Optional locale string that overrides default;
Globalize.format( new Date( 2010, 10, 30, 17, 55 ), { datetime: "short" } );
// "11/30/10, 5:55 PM"

Globalize.format( new Date( 2010, 10, 30, 17, 55 ), { datetime: "short" }, "de" );
// "30.11.10 17:55"

Comparison between different locales.

locale Globalize.format( new Date( 2010, 10, 1, 17, 55 ), { datetime: "short" }
en "11/1/10, 5:55 PM"
en_GB "01/11/2010 17:55"
de "01.11.10 17:55"
zh "10/11/1 下午5:55"
ar "1‏/11‏/2010 5:55 م"
pt "01/11/10 17:55"
es "1/11/10 17:55"

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 given). As before, the current locale is used if one is not specified.

Parameters:

  • value String with date to be parsed, eg. "11/1/10, 5:55 PM";
  • formats Optional Array of formats;
  • locale Optional locale string that overrides default;
Globalize.locale( "en" );
Globalize.parseDate( "1/2/13" );
// Wed Jan 02 2013 00:00:00

Globalize.locale( "es" );
Globalize.parseDate( "1/2/13" );
// Fri Feb 01 2013 00:00:00

Translate module

Globalize.loadTranslation( locale, translationData )

Load translation data per locale.

Parameters:

  • locale Locale string;
  • translationData A JSON object with translation mappings;
Globalize.loadTranslation( "pt_BR", {
  greetings: {
    hello: "Olá",
    bye: "Tchau"
  }
});

Globalize.translate( path, [locale] )

Translate item given its path.

Parameters:

  • path Translation item path;
  • locale Optional locale string that overrides default;
Globalize.locale( "pt_BR" );
Globalize.translate( "greetings/bye" );
// ➡ "Tchau"

Development

File structure

├── bower.json (metadata file)
├── CONTRIBUTING.md (doc file)
├── dist/ (output of built bundles)
├── external/ (external dependencies, eg. cldr, 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. Although, 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 on src/ root: eg. core.js, date.js, and translate.js.

Build

Install grunt and tests external dependencies. First, install the grunt-cli and bower packages if you haven't before. These should be done as global installs. Then:

npm install && bower install

Build distribution files.

grunt

Tests

Tests can be run either on browser or node (via grunt).

Unit

To run the unit tests, run grunt test:unit, or browse at file:///.../globalize/test/unit.html. 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

To run the functional tests, create the dist files by running grunt. Then, run grunt test:functional, or browse at file:///.../globalize/test/functional.html. 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 the combining pieces work as expected.

About

JavaScript globalization and localization

Resources

Readme

License

View license
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

3 tags

Packages

No packages published