cldr-json: the CLDR locale data set in JSON rather than XML

The JSON is generated from the XML, not authored

cldr-json is described as the JSON distribution of CLDR locale data for internationalization. The critical sentence for anyone deciding whether to depend on it is the second one in the README: although XML, not JSON, is the official format for all CLDR data, this data is programmatically generated from the corresponding XML, using the CLDR tooling.

That single fact determines almost everything else. There is no JSON in this repository that a human wrote by hand, so there is no way for the JSON and the XML to disagree, and there is no question of which one is authoritative. The CLDR XML is the source and the JSON is a projection of it.

The repository root makes the pipeline visible as a set of shell scripts. There is cldr-config.sh, cldr-generate-json.sh, cldr-generate-zip.sh, cldr-identify.sh and cldr-jsonlint.sh, plus a cldr-json/ directory holding the output. The primary language of the repository is recorded as Shell, which is consistent: this is tooling plus generated data.

So the decision to use cldr-json is really a decision about the CLDR tooling and the XML behind it. If your project already consumes CLDR, this is a format change. If it does not, this is a way in to the locale data without a native dependency.

For the audience, think of a team writing a date, number or currency formatter in JavaScript or TypeScript that currently hard codes locale rules, or a server that needs to render localised names and formats without shipping ICU.

The last push was on 2026-10-13 and the current release line is 49.0.0, with BETA4 tagged on that date and 48.2.3 from 2026-09-30 sitting as the newest non-beta.

Only contributed and approved data makes it into the output

CLDR's data moves through a review process, with each piece marked as a draft at some level, and cldr-json applies a filter to what it emits. The JSON is generated using only data that has achieved draft="contributed" or draft="approved" status, and the documentation is explicit that this is the same threshold used by ICU, the International Components for Unicode.

Aligning with ICU is the right call and it has a direct practical consequence. ICU is the reference implementation that most platforms ship, so if your JavaScript data agrees with ICU, a value that differs from what the operating system does is a bug in your code rather than a version skew between two data sets.

The consequence to plan for is that data which has not reached that threshold is simply absent. A new locale, a newly added currency, a recently revised pattern will not be in the JSON until it clears review, even if it exists in the CLDR working data. If your product needs to track the very latest locale additions, the answer is the CLDR XML and the tooling, not this distribution.

For most products this is invisible, because the review threshold is where data becomes safe to ship, and shipping unreviewed locale data is a bug factory. But it does mean there is a lag between the CLDR working data and what your application sees, and it means the release cadence of this repository follows the CLDR release cycle rather than yours.

The documentation points at UPDATING.md for details on building or customising the data yourself, which is the escape hatch for anyone who needs something the standard packages do not carry.

One repository, many packages, and the split by v38 is the thing to know

Because the CLDR is so large and contains so many different types of information, the JSON data here is grouped into packages by functionality. The full package list and details of each package live in PACKAGES.md, and that file is the first thing to read when you are evaluating this.

The packaging history matters too. The documentation says that as of v38, all JSON data is contained in this single repository. Before that, the data was spread across separate repositories, so an older reference or an older lockfile may point at a package that no longer lives here.

Installation goes through npm, and the package names come from the package list rather than from a single monorepo name.

$ npm install cldr-dates-full

The README shows the general form as npm install with the package name, and gives that dates example as the concrete case. The note that bower is deprecated and npm should be used is a leftover from the era when this data shipped through both package managers, and it tells you the packages are published to the npm registry individually rather than bundled.

That is the practical benefit of the package split. An application that only needs number formatting should not download the currency, calendar and time zone data to get it. Each package is a separate install, and each is separately versioned.

The repository also carries a USERS.md file listing the libraries which use this data, which is a genuinely useful file for an adopter: it tells you which libraries have already made the same decision, and reading how they consume the data is a faster path to a working integration than the package list alone.

Tagged releases, zip archives and a repository that is not where bugs go

There are two distribution routes, and they serve different needs.

The first is tagged releases. The releases page lists the cldr-json releases, and the GitHub release page also contains zip files, so you can download all full or modern data in a single zip. For a build environment that prefers a tarball or zip over a package manager, or for a vendored copy inside a container image, that is the route.

The second is the npm packages described earlier, which are the right choice for a JavaScript project with a package manager.

The third thing worth knowing is where problems go. CLDR does not use GitHub's issue tracking system to track bugs. If you find an error in the data contained here, you are asked to file a new ticket at Unicode Jira. That is a deliberate choice, because the data is a projection of the CLDR proper and the CLDR has its own review process, so fixing the JSON in GitHub would be fixing the wrong artefact.

It does mean the normal expectation of a GitHub repository does not hold. There is no issue tracker here, no issue-driven maintenance, and a bug report is a ticket in an external tracker. If you are evaluating this on the grounds of responsiveness, the honest answer is that this repository is not where responsiveness happens.

There is a useful consequence in the other direction. Because the JSON is generated, a fix in the CLDR XML propagates to the next release of every affected package automatically. The bottleneck is the CLDR review process, and that is a well-known process with a published release cadence rather than something this repository improvises.

Contributing requires a CLA, and the data is governed by the Unicode terms of use

The contribution requirements are strict and stated in two lines. A CLA is required to contribute to this project, and the CONTRIBUTING.md file or a pull request is where the details are. The copyright and licensing section notes that copyright is held by Unicode, Inc., and that the Unicode and Unicode Logo are registered trademarks in the United States and other countries.

The CLA requirement is the important one for anyone who plans to fix a data error. Pulling a request to change a locale pattern in this repository is not a normal open source contribution, because the contribution needs a signed agreement. For a project that mostly consumes this data, that is irrelevant. For a project that wants to patch the data it ships, it is a real constraint on the workflow, and it pushes the fix upstream into the CLDR where it belongs anyway.

The licensing of the contents is separate from the licensing of the code that generates it. The contents of this repository are governed by the Unicode Terms of Use and are released under the LICENSE file, and the project licence is recorded as a custom notice that GitHub cannot classify. The Terms of Use are a distinct instrument from a standard open source licence, and an organisation with a strict policy on what data it can redistribute should read that document rather than assume a permissive licence from the MIT-style reading of the repository.

So there are two terms to reconcile before you ship the data inside a product: the terms covering the data itself, and the CLA requirement that governs how you contribute back.

Where cldr-json is the wrong tool

The first wrong-tool case is a project that needs the very latest locale data. Data that has not reached contributed or approved status is not in the JSON at all, so a newly introduced locale or a currency added last week is missing until the next release. If your product must reflect CLDR as it changes, you want the XML and the tooling, and UPDATING.md is the place to start.

The second case is a project that already links ICU. If a native dependency is acceptable in your environment, ICU is the reference implementation and it is what the threshold in this project is aligned to. Adding a JSON data set on top of ICU duplicates the data and introduces a second source of truth for locale rules.

The third case is a non-JavaScript runtime with no npm in the pipeline. The packages are published to npm, and the alternative is the zip archive from a release. For a JVM service or a Go service that already has a Unicode library, the JSON is a second distribution of something you already have.

The fourth case is a workflow that depends on issue-driven maintenance. There is no GitHub issue tracker for bugs, because the data is generated and the fix has to happen in the CLDR. If your dependency governance expects a repository with a visible backlog and a maintainer response to individual issues, this repository does not present that, and the versioning story confirms it: the release tags are CLDR version numbers such as 49.0.0-BETA4, 49.0.0-BETA3 and 48.2.3, which are the CLDR's own release cycle rather than a separate cadence.

One operational point to check before depending on a specific package. Because the packages are split by functionality and published independently, two packages in your dependency tree can sit at different CLDR versions if their ranges allow it, and you would then have two slightly different views of the locale data in one application. Pinning every cldr package to the same release is worth doing deliberately.

Editorial conclusion

cldr-json suits a JavaScript or TypeScript codebase that needs CLDR date, number, currency or display name data and would rather not parse XML or link ICU. It does not suit a team that needs data newer than the contributed-or-approved threshold, since excluded drafts are not in the output at all, and it does not suit a project that has to file a CLA to contribute back. Before adopting, read PACKAGES.md to find the package that matches the data you need, check USERS.md for libraries that already consume it, and pin to a specific release tag such as 48.2.3 rather than tracking the branch, because the 49.0.0 line is currently at BETA4.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. unicode-org/cldr-json on GitHub