cldr.js - Simple CLDR API

CLDR (unicode.org) provides locale content for I18n software. The data is provided in two formats: LDML (XML format), and JSON. Our goal is to provide a simple layer to facilitate I18n softwares to access and use the official CLDR JSON data.

File	Minified size	Summary
cldr.js	3.2KB	Core library
cldr/unresolved.js	+1.1KB	Provides inheritance support for unresolved data
cldr/supplemental.js	+1.2KB	Provides supplemental helper methods

Getting Started

Quick jump:

About cldr.js?
How to get CLDR JSON data?
Usage and installation
API
Development / Contributing

About cldr.js?

Who uses cldr.js?

Organization	Project
	https://github.com/jquery/globalize

Where to use it?

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

See Usage and installation.

Load only the CLDR portion you need

// Load the appropriate portion of CLDR JSON data
Cldr.load( likelySubtagsData );
Cldr.load( enData );
Cldr.load( ptBrData );

See How to get CLDR JSON data? below for more information on how to get that data.

Instantiate a locale and get it normalized

var en = new Cldr( "en" );
en.attributes;
// {
//   "languageId": "en",
//   "maxLanguageId": "en_Latn_US",
//   "language": "en",
//   "script": "Latn",
//   "territory": "US",
//   "region": "US"
// }

language, script, territory (also aliased as region), and maxLanguageId are computed by adding likely subtags according to the specification.
languageId is always in the succinct form, obtained by removing the likely subtags from maxLanguageId according to the specification.

Comparison between different locales.

locale	languageId	maxLanguageId	language	script	region
en	`"en"`	`"en_Latn_US"`	`"en"`	`"Latn"`	`"US"`
en_US	`"en"`	`"en_Latn_US"`	`"en"`	`"Latn"`	`"US"`
de	`"de"`	`"de_Latn_DE"`	`"de"`	`"Latn"`	`"DE"`
zh	`"zh"`	`"zh_Hans_CN"`	`"zh"`	`"Hans"`	`"CN"`
zh_TW	`"zh_TW"`	`"zh_Hant_TW"`	`"zh"`	`"Hant"`	`"TW"`
ar	`"ar"`	`"ar_Arab_EG"`	`"ar"`	`"Arab"`	`"EG"`
pt	`"pt"`	`"pt_Latn_BR"`	`"pt"`	`"Latn"`	`"BR"`
pt_BR	`"pt"`	`"pt_Latn_BR"`	`"pt"`	`"Latn"`	`"BR"`
pt_PT	`"pt_PT"`	`"pt_Latn_PT"`	`"pt"`	`"Latn"`	`"PT"`
es	`"es"`	`"es_Latn_ES"`	`"es"`	`"Latn"`	`"ES"`
es_AR	`"es_AR"`	`"es_Latn_AR"`	`"es"`	`"Latn"`	`"AR"`

Get item given its path

en.main( "numbers/symbols-numberSystem-latn/decimal" );
// ➡ "."
// Equivalent to:
// .get( "main/{languageId}/numbers/symbols-numberSystem-latn/decimal" );
 
ptBr.main( "numbers/symbols-numberSystem-latn/decimal" );
// ➡ ","
// Equivalent to:
// .get( "main/{languageId}/numbers/symbols-numberSystem-latn/decimal" );

Have any locale attributes replaced with their corresponding values by embracing it with {}. In the example below, {language} is replaced with "en", and {territory} with "US".

var enGender = en.get( "supplemental/gender/personList/{language}" );
// ➡ "neutral"
// Notice the more complete way to get this data is:
// cldr.get( "supplemental/gender/personList/{language}" ) ||
// cldr.get( "supplemental/gender/personList/001" );
 
var USCurrencies = en.get( "supplemental/currencyData/region/{territory}" );
// ➡
// [ { USD: { _from: "1792-01-01" } },
//   { USN: { _tender: "false" } },
//   { USS: { _tender: "false" } } ]
 
var enMeasurementSystem = en.get( "supplemental/measurementData/measurementSystem/{territory}" );
// ➡ "US"
// Notice the more complete way to get this data is:
// cldr.get( "supplemental/measurementData/measurementSystem/{territory}" ) ||
// cldr.get( "supplemental/measurementData/measurementSystem/001" );

Get undefined for non-existent data.

en.get( "/crazy/invalid/path" );
// ➡ undefined
 
// Avoid this
enData && enData.crazy && enData.crazy.invalid && enData.crazy.invalid.path;

Resolve CLDR inheritances

If you are using unresolved JSON data, you can resolve them dynamically during runtime by loading the cldr/unresolved.js extension module. Currently, we support bundle inheritance.

Cldr.load( unresolvedEnData );
Cldr.load( unresolvedEnGbData );
Cldr.load( unresolvedEnInData );
Cldr.load( parentLocalesData ); // supplemental
Cldr.load( likelySubtagsData ); // supplemental
 
var enIn = new Cldr( "en_IN" );
 
enIn.main( "dates/calendars/gregorian/dateTimeFormats/availableFormats/yMd" );
// ➡ "dd/MM/y"
// 1st time retrieved by resolving: en_IN ➡ en_GB (parent locale lookup).
// Further times retrieved straight from the resolved cache.
 
enIn.main( "numbers/symbols-numberSystem-latn/decimal" );
// ➡ "."
// 1st time retrieved by resolving: en_IN ➡ en_GB (parent locale lookup) ➡ en (truncate lookup)
// Further times retrieved straight from the resolved cache.

Helpers

We offer some convenient helpers.

var usFirstDay = en.supplemental.weekData.firstDay();
// ➡ sun
// Equivalent to:
// en.get( "supplemental/weekData/firstDay/{territory}" ) ||
// en.get( "supplemental/weekData/firstDay/001" );
 
var brFirstDay = ptBr.supplemental.weekData.firstDay();
// ➡ mon
// Equivalent to:
// ptBr.get( "supplemental/weekData/firstDay/{territory}" ) ||
// ptBr.get( "supplemental/weekData/firstDay/001" );

Browser support

We officially support:

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

Sniff tests show cldr.js 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 and installation

cldr.js has no external dependencies. You can include it in the script tag of your page, as shown in Getting Started above, and you're ready to go.

<script src="cldr.js"></script>

// Load the appropriate portion of CLDR JSON data.
// See "How to get CLDR JSON data?" below for more information on how to get that data.
Cldr.load( cldrJsonData );
 
// Instantiate it by passing a locale.
var ptBr = new Cldr( "pt_BR" );
 
// Get CLDR item data given its path.
ptBr.main( "numbers/symbols-numberSystem-latn/decimal" );
// ➡ ","
// Equivalent to:
// .get( "main/{languageId}/numbers/symbols-numberSystem-latn/decimal" );

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

Example of usage on AMD:

bower install cldr.js

require.config({
  paths: {
    "cldr": "bower_components/cldr.js/dist/cldr"
  }
});
 
require( [ "cldr", "cldr/supplemental", "cldr/unresolved" ], function( Cldr ) {
  ...
});

Example of usage with Node.js:

npm install cldr.js

var Cldr = require( "cldr.js" );

How to get CLDR JSON data?

The Unicode CLDR is available for download as JSON (json.zip). This file contains the complete data of what the Unicode CLDR Project considers the top 20 languages (at the time of this writing).

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 choose to generate unresolved data to save space or bandwidth (-r false option of the conversion tool), and instead have it resolve at runtime.

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>
// Embedded (hard-coded) CLDR JSON data.
Cldr.load({
  supplemental: {
    likelySubtags: {
      ...
    }
  }
});
</script>

Example of loading it dynamically:

<script src="jquery.js"></script>
<script>
$.get( "cldr/supplemental/likelySubtags.json", Cldr.load );
</script>

Example using AMD (also see our functional tests):

define([
  "cldr",
  "json!cldr/supplemental/likelySubtags.json"
], function( Cldr, likelySubtags ) {
 
  Cldr.load( likelySubtags );
 
});

Example using Node.js:

var Cldr = require( "cldr.js" );
Cldr.load( require( "./cldr/supplemental/likelySubtags.json" ) );

Atention: library owners, do not embed data

It's NOT recommended that libraries embed data into its code logic for some reasons: avoid forcing a certain data version on users, avoid maintaining locale changes, avoid duplicating data among different i18n libraries.

We recommend loading CLDR data must be performed by end user code.

Which CLDR portion to load?

It depends on the used modules.

File	Required CLDR JSON data
cldr.js	`cldr/supplemental/likelySubtags.json`
cldr/unresolved.js	-
cldr/supplemental.js	`cldr/supplemental/{timeData, weekData}.json`

You must also load any portion of the CLDR data you plan to use in your library or your end-application.

API

Cldr.load( json )

json Object with resolved or unresolved [1] CLDR JSON data.

Load resolved or unresolved [1] JSON data.

Cldr.load({
    "main": {
        "pt_BR": {
            "numbers": {
                "symbols-numberSystem-latn": {
                    "decimal": ","
                }
            }
        }
    }
});

1: Unresolved processing is only available after loading cldr/unresolved.js extension module.

cldr = new Cldr( locale )

locale String eg. "en", "pt_BR". More information in the specification.

Create a new instance of Cldr.

cldr.attributes

Attributes is an Object created during instance initialization (construction), and are used internally by .get() to replace dynamic parts of an item path.

Attribute	Field
`language`	Language Subtag (spec)
`script`	Script Subtag (spec)
`region` or `territory`	Region Subtag (spec)
`languageId`	Language Id (spec)
`maxLanguageId`	Maximized Language Id (spec)

language, script, territory (also aliased as region), and maxLanguageId are computed by adding likely subtags according to the specification.
languageId is always in the succint form, obtained by removing the likely subtags from maxLanguageId according to the specification.

cldr.get( path )

path
String, eg. "/cldr/main/{languageId}/numbers/symbols-numberSystem-latn/decimal"; or
Array, eg. [ "cldr", "main", "{languageId}", "numbers", "symbols-numberSystem-latn", "decimal" ], or [ "cldr/main", "{languageId}", "numbers/symbols-numberSystem-latn/"decimal" ] (notice the subpath parts);
The leading "/cldr" can be ommited;
Locale attributes, eg. {languageId}, are replaced with their appropriate values;

Get the item data given its path, or return undefined.

If extended with cldr/unresolved.js, get the item data or lookup by following locale inheritance, set a local resolved cache if it's found (for subsequent faster access), or return undefined.

ptBr.get( "main/{languageId}/numbers/symbols-numberSystem-latn/decimal" );
// ➡ ","

cldr.main( path )

path String or Array. Same specification of cldr.get().

It's an alias for .get([ "main/{languageId}", ... ]).

ptBr.main( "numbers/symbols-numberSystem-latn/decimal" );
// ➡ ","

cldr.supplemental( path )

path String or Array. Same specification of cldr.get().

It's an alias for .get([ "supplemental", ... ]). Provided by cldr/supplemental.js.

en.supplemental( "gender/personList/{language}" );
// ➡ "neutral"

cldr.supplemental.timeData.allowed()

Helper function. Return the supplemental timeData allowed of locale's territory. Provided by cldr/supplemental.js.

en.supplemental.timeData.allowed();
// ➡ "H h"

cldr.supplemental.timeData.preferred()

Helper function. Return the supplemental timeData preferred of locale's territory. Provided by cldr/supplemental.js.

en.supplemental.timeData.preferred();
// ➡ "h"

cldr.supplemental.weekData.firstDay()

Helper function. Return the supplemental weekData firstDay of locale's territory. Provided by cldr/supplemental.js.

en.supplemental.weekData.firstDay();
// ➡ "sun"

cldr.supplemental.weekData.minDays()

Helper function. Return the supplemental weekData minDays of locale's territory as a Number. Provided by cldr/supplemental.js.

en.supplemental.weekData.minDays();
// ➡ 1

Development / Contributing

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

Run tests

grunt test

Build distribution file.

grunt

cldr.js

cldr.js - Simple CLDR API

Getting Started

About cldr.js?

Who uses cldr.js?

Where to use it?

Load only the CLDR portion you need

Instantiate a locale and get it normalized

Get item given its path

Resolve CLDR inheritances

Helpers

Browser support

Usage and installation

How to get CLDR JSON data?

Atention: library owners, do not embed data

Which CLDR portion to load?

API

Cldr.load( json )

cldr = new Cldr( locale )

cldr.attributes

cldr.get( path )

cldr.main( path )

cldr.supplemental( path )

cldr.supplemental.timeData.allowed()

cldr.supplemental.timeData.preferred()

cldr.supplemental.weekData.firstDay()

cldr.supplemental.weekData.minDays()

Development / Contributing

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Last publish

Collaborators

cldr.js

cldr.js - Simple CLDR API

Getting Started

About cldr.js?

Who uses cldr.js?

Where to use it?

Load only the CLDR portion you need

Instantiate a locale and get it normalized

Get item given its path

Resolve CLDR inheritances

Helpers

Browser support

Usage and installation

How to get CLDR JSON data?

Atention: library owners, do not embed data

Which CLDR portion to load?

API

Cldr.load( json )

cldr = new Cldr( locale )

cldr.attributes

cldr.get( path )

cldr.main( path )

cldr.supplemental( path )

cldr.supplemental.timeData.allowed()

cldr.supplemental.timeData.preferred()

cldr.supplemental.weekData.firstDay()

cldr.supplemental.weekData.minDays()

Development / Contributing

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads