Security News
Meet the Socket Team at RSAC and BSidesSF 2025
Join Socket for exclusive networking events, rooftop gatherings, and one-on-one meetings during BSidesSF and RSA 2025 in San Francisco.
By Sarah Gooding - Mar 27, 2025
New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
What is cldrjs?
The cldrjs npm package is a JavaScript library that provides access to the Unicode Common Locale Data Repository (CLDR). It allows developers to handle internationalization (i18n) tasks such as formatting dates, times, numbers, and currencies, as well as handling plurals and other locale-specific data.
What are cldrjs's main functionalities?
Locale Data Access
This feature allows you to access locale-specific data. In this example, we create a new CLDR instance for the English locale and retrieve the display names for languages.
const Cldr = require('cldrjs');
const en = new Cldr('en');
console.log(en.get('localeDisplayNames/languages'));Number Formatting
This feature allows you to format numbers according to locale-specific rules. In this example, we use the Globalize library along with cldrjs to format a number in the English locale.
const Cldr = require('cldrjs');
const Globalize = require('globalize');
Globalize.load(require('cldr-data/main/en/numbers.json'));
Globalize.load(require('cldr-data/supplemental/likelySubtags.json'));
Globalize.locale('en');
console.log(Globalize.numberFormatter()(1234567.89));Date and Time Formatting
This feature allows you to format dates and times according to locale-specific rules. In this example, we use the Globalize library along with cldrjs to format the current date and time in the English locale.
const Cldr = require('cldrjs');
const Globalize = require('globalize');
Globalize.load(require('cldr-data/main/en/ca-gregorian.json'));
Globalize.load(require('cldr-data/supplemental/likelySubtags.json'));
Globalize.locale('en');
console.log(Globalize.dateFormatter({ datetime: 'medium' })(new Date()));Pluralization
This feature allows you to handle pluralization according to locale-specific rules. In this example, we use the Globalize library along with cldrjs to determine the plural category for numbers in the English locale.
const Cldr = require('cldrjs');
const Globalize = require('globalize');
Globalize.load(require('cldr-data/main/en/plurals.json'));
Globalize.load(require('cldr-data/supplemental/plurals.json'));
Globalize.locale('en');
console.log(Globalize.plural(1)); // 'one'
console.log(Globalize.plural(2)); // 'other'Other packages similar to cldrjs
globalize
Globalize is a comprehensive internationalization library that leverages CLDR data for formatting and parsing dates, numbers, and currencies, as well as handling pluralization and message formatting. It is often used in conjunction with cldrjs to provide a complete i18n solution.
moment
Moment.js is a popular library for parsing, validating, manipulating, and formatting dates. While it does not directly use CLDR data, it provides extensive support for internationalization through its locale system.
date-fns
date-fns is a modern JavaScript date utility library that provides a comprehensive set of functions for working with dates. It includes support for internationalization through its locale system, although it does not use CLDR data directly.
luxon
Luxon is a modern JavaScript library for working with dates and times. It is built on top of the native JavaScript Date object and provides extensive support for internationalization, including formatting and parsing dates and times in different locales.
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 |
|---|---|
 | https://github.com/globalize/globalize |
 | 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;
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"
// }
language,script,territory(also aliased asregion),maxLanguageId(computed by adding likely subtags) andminLanguageId(computed by removing likely subtags) according to the specification.bundleholds the bundle lookup match based on the available loaded CLDR data, obtained by following Bundle Lookup Matcher.- Unicode locale extensions.
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.
1: Unresolved processing is only available after loading cldr/unresolved.js extension module.
new Cldr( locale )
Create a new instance of 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.
.get( path )
Get the item data given its path, or undefined if missing.
.main( path )
It's an alias for .get([ "main/{bundle}", ... ]).
cldr/event.js
Cldr.on( event, listener )
Add a listener function to the specified event globally (for all instances).
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.
Cldr.off( event, listener )
Remove a listener function from the specified event globally (for all instances).
.on( event, listener )
Add a listener function to the specified event for this instance.
.once( event, listener )
Add a listener function to the specified event for this instance. It will be automatically removed after it's first execution.
.off( event, listener )
Remove a listener function from the specified event for this instance.
Events
get➡( path, value )
Triggered before a .get() (or any alias) return. The triggered listener receives the normalized path and the value found.
cldr/supplemental.js
.supplemental( path )
It's an alias for .get([ "supplemental", ... ]).
.supplemental.timeData.allowed()
Helper function. Return the supplemental timeData allowed of locale's territory.
.supplemental.timeData.preferred()
Helper function. Return the supplemental timeData preferred of locale's territory.
.supplemental.weekData.firstDay()
Helper function. Return the supplemental weekData firstDay of locale's territory.
.supplemental.weekData.minDays()
Helper function. Return the supplemental weekData minDays of locale's territory as a Number.
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.
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
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
License
MIT © Rafael Xavier de Souza
FAQs
Simple CLDR traverser
We found that cldrjs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Package last updated on 22 Oct 2020
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Security News
Biome Announces v2.0 Beta with Plugin System and Type Information Support
Biome's v2.0 beta introduces custom plugins, domain-specific linting, and type-aware rules while laying groundwork for HTML support and embedded language features in 2025.
By Sarah Gooding - Mar 25, 2025
Security News
Next.js Patches Critical Middleware Vulnerability (CVE-2025-29927)
Next.js has patched a critical vulnerability (CVE-2025-29927) that allowed attackers to bypass middleware-based authorization checks in self-hosted apps.
By Sarah Gooding - Mar 24, 2025