Skip to content

Latest commit

 

History

History
562 lines (381 loc) · 16.1 KB

README.md

File metadata and controls

562 lines (381 loc) · 16.1 KB
Raw

cldr.js - Simple CLDR traverser

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
cldr/supplemental.js +0.5KB Provides supplemental helper methods
cldr/unresolved.js +0.7KB Provides inheritance support for unresolved data

Quick jump:

About cldr.js?

Who uses cldr.js?

Organization Project
jQuery https://github.com/globalize/globalize
Angular https://github.com/angular/angular

Where to use it?

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

See Usage and installation.

What changed from 0.3.x to 0.4.x?

See our changelogs.

Load only the CLDR portion you need

// Load the appropriate portion of CLDR JSON data
Cldr.load(
  likelySubtagsData,
  enData,
  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;
// > {
//   "bundle": "en",
//   "minLanguageId": "en",
//   "maxLanguageId": "en-Latn-US",
//   "language": "en",
//   "script": "Latn",
//   "territory": "US",
//   "region": "US"
// }

var zh = new Cldr( "zh-u-nu-finance-cu-cny" );
zh.attributes;
// > {
//   "bundle": "zh-Hant",
//   "minLanguageId": "zh",
//   "maxLanguageId": "zh-Hans-CN",
//   "language": "zh",
//   "script": "Hans",
//   "territory": "CN",
//   "region": "CN",
//   "u-nu": "finance",
//   "u-cu": "cny"
// }

Comparison between different locales.

locale minLanguageId 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

// Equivalent to:
// .get( "main/{bundle}/numbers/symbols-numberSystem-latn/decimal" );
en.main( "numbers/symbols-numberSystem-latn/decimal" );
// > "."

// Equivalent to:
// .get( "main/{bundle}/numbers/symbols-numberSystem-latn/decimal" );
ptBr.main( "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".

// 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"

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
  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" );
// > "."

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.

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).

Example of usage on AMD:

bower install cldrjs
require.config({
  paths: {
    "cldr": "bower_components/cldrjs/dist/cldr"
  }
});

require( [ "cldr", "cldr/supplemental", "cldr/unresolved" ], function( Cldr ) {
  ...
});

Example of usage with Node.js:

npm install cldrjs
var Cldr = require( "cldrjs" );

How to get CLDR JSON data?

By downloading the JSON packages individually...

Unicode CLDR is available as JSON at https://github.com/unicode-cldr/ (after this json-packaging proposal took place). Please, read https://github.com/unicode-cldr/cldr-json for more information about package organization.

By using a package manager...

cldr-data can be used for convenience. It always downloads from the correct source.

Use bower bower install cldr-data (detailed instructions) or npm npm install cldr-data. For more information, see:

By generating the JSON mappings yourself...

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:

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( "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.

API

Core

  • Cldr.load( json, ... )

Load resolved or unresolved [1] JSON data.

Read more...

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

  • new Cldr( locale )

Create a new instance of Cldr.

Read more...

  • .attributes

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

Read more...

  • .get( path )

Get the item data given its path, or undefined if missing.

Read more...

  • .main( path )

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

Read more...

cldr/event.js

  • Cldr.on( event, listener )

Add a listener function to the specified event globally (for all instances).

Read more...

  • Cldr.once( event, listener )

Add a listener function to the specified event globally (for all instances). It will be automatically removed after it's first execution.

Read more...

  • Cldr.off( event, listener )

Remove a listener function from the specified event globally (for all instances).

Read more...

  • .on( event, listener )

Add a listener function to the specified event for this instance.

Read more...

  • .once( event, listener )

Add a listener function to the specified event for this instance. It will be automatically removed after it's first execution.

Read more...

  • .off( event, listener )

Remove a listener function from the specified event for this instance.

Read more...

Events

  • get ➡ ( path, value )

Triggered before a .get() (or any alias) return. The triggered listener receives the normalized path and the value found.

Read more...

cldr/supplemental.js

  • .supplemental( path )

It's an alias for .get([ "supplemental", ... ]).

Read more...

  • .supplemental.timeData.allowed()

Helper function. Return the supplemental timeData allowed of locale's territory.

Read more...

  • .supplemental.timeData.preferred()

Helper function. Return the supplemental timeData preferred of locale's territory.

Read more...

  • .supplemental.weekData.firstDay()

Helper function. Return the supplemental weekData firstDay of locale's territory.

Read more...

  • .supplemental.weekData.minDays()

Helper function. Return the supplemental weekData minDays of locale's territory as a Number.

Read more...

cldr/unresolved.js

  • .get( 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.

Read more...

Error reference

CLDR Errors

E_MISSING_BUNDLE

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

To run the tests and build, you can run npm scripts. You will need to install all dependencies before:

npm install

Run tests

npm run test:unit
npm run test:functional

Build distribution file.

npm run build

Release

On MacOS, use gnu-sed (brew install gnu-sed)

./chore/release <version> # where version is for example 0.5.2

License

MIT © Rafael Xavier de Souza