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 software to access and use the official CLDR JSON data.
File
Minified + gzipped size
Summary
cldr.js
2.1KB
Core library
cldr/event.js
+1.4KB
Provides methods to allow listening to events, eg. get
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".
// Notice the more complete way to get this data is:// cldr.get( "supplemental/gender/personList/{language}" ) ||// cldr.get( "supplemental/gender/personList/001" );var enGender = en.get( "supplemental/gender/personList/{language}" );// > "neutral"var USCurrencies = en.get( "supplemental/currencyData/region/{territory}" );// > [// { USD: { _from: "1792-01-01" } },// { USN: { _tender: "false" } },// { USS: { _tender: "false" } }// ]// Notice the more complete way to get this data is:// cldr.get( "supplemental/measurementData/measurementSystem/{territory}" ) ||// cldr.get( "supplemental/measurementData/measurementSystem/001" );var enMeasurementSystem = en.get( "supplemental/measurementData/measurementSystem/{territory}" );// > "US"
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 unresolvedEnGbData, unresolvedEnInData, parentLocalesData, // supplemental likelySubtagsData // supplemental);var enIn = new Cldr( "en-IN" );// 1st time retrieved by resolving: en-IN ➡ en-GB (parent locale lookup).// Further times retrieved straight from the resolved cache.enIn.main( "dates/calendars/gregorian/dateTimeFormats/availableFormats/yMd" );// > "dd/MM/y"// 1st time retrieved by resolving: en-IN ➡ en-GB (parent locale lookup) ➡ en (truncate lookup)// Further times retrieved straight from the resolved cache.enIn.main( "numbers/symbols-numberSystem-latn/decimal" );// > "."
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.
Getting Started
Usage and installation
cldr.js has no external dependencies. You can include it in the script tag of your page and you're ready to go. Download it by clicking here.
<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.// Equivalent to:// .get( "main/{bundle}/numbers/symbols-numberSystem-latn/decimal" );ptBr.main( "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).
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.
How do I load CLDR data into Cldrjs?
The short answer is by using Cldr.load() and passing the JSON data as the first argument. Below, follow several examples on how this could be accomplished.
For the examples below, first fetch CLDR JSON data:
var Cldr = require( "cldrjs" );Cldr.load( require( "./cldr/supplemental/likelySubtags.json" ) );
Attention: library owners, do not embed data
It's NOT recommended that libraries embed data into their code logic for several 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/parentLocales.json
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.
Attributes is an Object created during instance initialization (construction) and are used internally by .get() to replace dynamic parts of an item path.
Overload (extend) .get() to 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.
Thrown when none of the loaded CLDR data can be used as a bundle for the corresponding locale. See more information on Bundle Lookup Matcher.
Error object:
Attribute
Value
code
E_MISSING_BUNDLE
locale
Locale whose bundle could not be found
Parameter Errors
E_MISSING_PARAMETER
Thrown when a required parameter is missing on any static or instance methods.
Error object:
Attribute
Value
code
E_MISSING_PARAMETER
name
Name of the missing parameter
E_INVALID_PAR_TYPE
Thrown when a parameter has an invalid type on any static or instance methods.
Error object:
Attribute
Value
code
E_INVALID_PAR_TYPE
name
Name of the invalid parameter
value
Invalid value
expected
Expected type
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
Release
On MacOS, use gnu-sed (brew install gnu-sed)
./chore/release <version> # where version is for example 0.5.2