{"canonical_url":"https://engineer.company/glossary/cldr/","content_markdown":"# CLDR\n\n## What it is\n\nCLDR is a body of locale data that works alongside Unicode. Unicode defines the\ncharacters a text is written in; CLDR records how readers of a given language in\na given region expect a date, a number, a price, a unit or a list to be written,\nand in what order they expect names to be sorted. The Unicode Consortium\nmaintains both. CLDR's full name is now Unicode Common Locale Data \u0026 Rules. It\nwas formerly called the Common Locale Data Repository, and its specification was\nformerly called the Locale Data Markup Language, or LDML; the specification says\nthat references under the old names remain valid.\n\nThe project's site names three parts. The first is the data itself, curated and\nstructured for software to use. The second is the specification, Unicode\nTechnical Standard #35, which documents how the data is structured and how\nalgorithms use it, with requirements for conformance. The third is the code that\ncollects the data from language specialists, checks it for validity and\nconsistency, and converts it into the formats developers use. The\nspecification's own summary of what the data covers makes a good map: the\nidentifiers used for locales, for units, for numbering systems and for\ncalendars; the formatting of dates, times, time zones, numbers, currencies and\nmeasurements; and sorting and searching. Plural rules, list patterns and the\nnames of languages and regions sit alongside them.\n\nThe data is organised by locale: a language, which can be narrowed by a script\nand a region. Each locale holds only what differs from its parent. The\nspecification's example is English: `en` holds the bulk of the data, and\n`en_IE`, English as used in Ireland, holds only a few items such as currency.\nAbove every language sits a locale called root, and the locale for a language's\nprimary region holds no data of its own, because its parent already holds\neverything it needs. A few facts belong to the region alone, whatever the\nlanguage: the currency, the measurement system and the conventions of the week.\nSo if no bundle exists for French as used in the United States, a request for it\ngets its formats from `fr` and its amounts in US dollars.\n\nThe source data is published for each release as XML in the format the\nspecification defines, with tools that convert it to JSON and POSIX formats.\nReleases follow a schedule of two cycles a year, and CLDR 49 was released on 22\nOctober 2026. New data comes in through an online Survey Tool, which usually\nopens once a year, both to collect data for newly added structures and to fix\ndata in earlier releases, and native speakers and linguistic experts vet what\ngoes in.\n\n## Why it matters\n\nThe project's site states the problem plainly: writing out a date, a number, a\nsum of money or a measurement correctly is \"far more complicated across\ndifferent languages and regions than most people recognize.\" CLDR exists so that\nno team has to learn that complexity one language at a time. It supports over\n100 languages, and its data is vetted by native speakers and linguistic experts,\nwhich is more review than any product team can give the date format of a market\nit has just entered.\n\nMost teams never touch CLDR directly, and that is by design. The project counts\nevery modern operating system and browser among those that use its data, along\nwith languages such as Java, C#, .NET, Swift and JavaScript. The use is often\nindirect: an application asks an operating system service to format a date, the\nservice calls ICU, Unicode's production library for C, C++, Java and Rust, and\nICU reads CLDR. Node.js builds its `Intl` objects on ICU and ships the full ICU\ndata by default; Python programs reach the same data through Babel, and Ruby\nprograms through TwitterCLDR. When a team calls a locale-aware formatter, the\nanswer almost always comes from CLDR. What the team still decides is which\nlocale to ask for, and which release it is running.\n\nThe alternative is a table written by hand: twelve month names per language, a\ndecimal separator, a thousands separator, an order for the alphabet. At best\nsuch a table is right on the day it is written, and it stays frozen from then\non, while CLDR's Survey Tool reopens every year to correct data already\nreleased. It is also usually written by someone who speaks only some of the\nlanguages in it. The orders in which Danish and Swedish sort the same six place\nnames, shown below, are not something a developer outside those languages would\nguess.\n\n## What it looks like in practice\n\nAsk the runtime which CLDR release it carries, then let that data sort six\nDanish and Swedish place names, join three Danish city names into a list and\nlook up the week of four locales:\n\n```js\nconsole.log(\"CLDR\", process.versions.cldr);\n\nconst towns = [\"Ørsted\", \"Odense\", \"Åsa\", \"Aabenraa\", \"Ærø\", \"Ängelholm\"];\nconsole.log(\"code point\", [...towns].sort().join(\", \"));\nfor (const tag of [\"en\", \"da\", \"sv\"]) {\n  const sorted = [...towns].sort(new Intl.Collator(tag).compare);\n  console.log(tag.padEnd(10), sorted.join(\", \"));\n}\n\nconst three = [\"Aarhus\", \"Odense\", \"Aalborg\"];\nfor (const tag of [\"en-GB\", \"en-US\", \"da\", \"uk\"]) {\n  console.log(tag.padEnd(10), new Intl.ListFormat(tag).format(three));\n}\n\nfor (const tag of [\"en\", \"en-GB\", \"en-DK\", \"da\"]) {\n  const locale = new Intl.Locale(tag);\n  const { firstDay } = locale.getWeekInfo();\n  console.log(tag.padEnd(10), locale.maximize().toString(), firstDay);\n}\n```\n\nNode 25.2.1 prints:\n\n```text\nCLDR 47.0\ncode point Aabenraa, Odense, Ängelholm, Åsa, Ærø, Ørsted\nen         Aabenraa, Ærø, Ängelholm, Åsa, Odense, Ørsted\nda         Odense, Ängelholm, Ærø, Ørsted, Aabenraa, Åsa\nsv         Aabenraa, Odense, Åsa, Ängelholm, Ærø, Ørsted\nen-GB      Aarhus, Odense and Aalborg\nen-US      Aarhus, Odense, and Aalborg\nda         Aarhus, Odense og Aalborg\nuk         Aarhus, Odense і Aalborg\nen         en-Latn-US 7\nen-GB      en-Latn-GB 1\nen-DK      en-Latn-DK 1\nda         da-Latn-DK 1\n```\n\nThe first line is the release this runtime was built with. It is 47.0, although\nCLDR 49 is out: a runtime carries the data of its own build, not the newest data\nthere is.\n\nA plain `sort()` with no comparator puts Ä, Å, Æ and Ø after every unmarked\nletter, in the order of their character codes, which matches none of the three\nlanguages. English sorts each name by its base letter, so the four names that\nbegin with an A come first and Ørsted follows Odense. Danish ends its alphabet\nwith Æ, Ø and Å, treats Ä as a variant of Æ, and sorts Aabenraa, spelled with\nthe older double a, among the Å names; the collation part of the specification\ncalls this the Danish contraction \"aa\". Swedish ends its alphabet with Å, Ä and\nÖ, treats Æ as a variant of Ä and Ø as a variant of Ö, and sorts Aabenraa as a\nname that starts with two a's. Norwegian Bokmål, `nb`, returns the Danish order.\nNone of this is in the code; each order comes from CLDR's collation rules for\nthat language.\n\nThe lists work the same way. Each locale has a list pattern with separate pieces\nfor the start, the middle and the end of a list, and for a list of two. British\nEnglish puts no comma before \"and\" and American English does, Danish joins with\n\"og\" and Ukrainian with \"і\", from one call that contains no word of any of these\nlanguages.\n\nThe last four lines show data that belongs to a region rather than a language.\nEach gives the tag, the full form that `maximize()` fills in from CLDR's likely\nsubtags, and the first day of the week as an ISO 8601 number, where 1 is Monday\nand 7 is Sunday. The runtime reads a bare `en` as English in the Latin script as\nused in the United States, so its week starts on Sunday. English as used in\nBritain or in Denmark starts the week on Monday, as Danish does: the week comes\nfrom the region, whatever the language.\n\nThe conventions CLDR records are also the ones a translated text has to get\nright by hand. One of this site's projects,\n[a cross-language figure check](/portfolio/built-a-cross-language-figure-check/),\nextracts every number, percentage, multiplier and unit from an English string\nand requires each of them in every translation. It also checks each language\nagainst the conventions it must use and must not, including decimal separators,\nthousands grouping and quotation marks.\n\n## Where it goes wrong\n\n**Formatted text is compared as a fixed string.** A test that expects `\"1 500\"`\nfrom `new Intl.NumberFormat(\"sv\").format(1500)` fails although the output looks\nexactly like that, because Swedish, Norwegian and Ukrainian separate thousands\nwith U+00A0 NO-BREAK SPACE, which an editor shows as an ordinary space. The same\ntest can also break on an upgrade, because a new CLDR release can correct data\nthat an older one shipped. Compare formatted output with the output of the same\nformatter, check its structure with `formatToParts`, which labels each piece as\ninteger, group, decimal or fraction, and never parse formatted text back into a\nnumber. The specification's advice is to store and exchange language-neutral\ndata and format it for the reader.\n\n**Two runtimes carry two releases.** Node 25.2.1 carries CLDR 47.0 while the\nproject has released 49, and a browser carries whatever its own build shipped. A\npage that formats a date on the server and again in the browser can show two\nstrings for one value, and a snapshot recorded on one machine can fail on\nanother. Format each value in one place, record `process.versions.cldr` beside\nthe test snapshots, and upgrade the runtime deliberately.\n\n**A missing locale falls back without an error.** `new Intl.NumberFormat(\"tlh\")`\nformats as American English and throws nothing, because the runtime has no data\nfor Klingon and falls back to its default locale. Node's documentation describes\na quieter case: a binary built with the small-icu option typically carries only\nEnglish data, and there a Spanish month name prints \"M01\" or \"January\" instead\nof \"enero\". Check `resolvedOptions().locale` or `supportedLocalesOf` before\ntrusting a locale, and run builds with the full ICU data, which is Node's\ndefault and what its official binaries use.\n\n**A tag without a region gets the likeliest one.** The runtime reads `en` as\n`en-Latn-US`, so a reader in Ireland, Britain or Denmark who is served `en` gets\na week that starts on Sunday and dates written as 10/27/2026, month first. The\nspecification describes the likely-subtags data behind this as heuristically\nderived and says it may change over time. Pass the reader's region along with\nthe language whenever it is known, and where only a language is known, call\n`maximize()` to see which region the runtime will assume.\n\n**CLDR's identifiers are passed to a BCP 47 API.** CLDR's files and examples\nwrite locales with underscores, such as `en_IE`, and the specification treats\n`_` and `-` as equivalent. JavaScript's `Intl` does not:\n`new Intl.NumberFormat(\"da_DK\")` throws\n`RangeError: Invalid language tag: da_DK`. Convert at the boundary as the\nspecification's own conversion to BCP 47 does, by replacing each `_` with `-`,\nand pass the result through `Intl.getCanonicalLocales`, which returns `da-DK`.\n\n## Further reading\n\n- [Unicode CLDR Project](https://cldr.unicode.org/) — what CLDR is, its three\n  components, who uses it and how, and the release schedule.\n- [UTS #35, Part 1: Core](https://www.unicode.org/reports/tr35/) — the\n  specification: locale identifiers, the former names, inheritance between\n  locales, likely subtags and the advice to keep data language-neutral.\n- [UTS #35, Part 2: General](https://www.unicode.org/reports/tr35/tr35-general.html)\n  — display names, measurement systems and the list patterns used above.\n- [UTS #35, Part 5: Collation](https://www.unicode.org/reports/tr35/tr35-collation.html)\n  — how CLDR tailors the default sort order for each language, with Danish as an\n  example.\n- [Node.js: Internationalization support](https://nodejs.org/api/intl.html) —\n  how Node builds its `Intl` objects on ICU, the build options and how to detect\n  what a binary supports.\n- [ECMAScript Internationalization API Specification](https://tc39.es/ecma402/)\n  — the standard behind `Intl`, including the `Locale` methods used above and\n  the CLDR week data and likely subtags they rely on.\n\n\u003chttps://engineer.company/glossary/cldr/\u003e\n","date_modified":"2026-10-29T11:17:41Z","description":"What the Unicode CLDR holds, how its locales inherit data, how runtimes ship it, and five ways formatted values and locale tags go wrong.","formats":{"gemtext":"https://engineer.company/glossary/cldr/index.gmi","gopher":"https://engineer.company/glossary/cldr/gophermap","html":"https://engineer.company/glossary/cldr/","json":"https://engineer.company/glossary/cldr/index.json","markdown":"https://engineer.company/glossary/cldr/index.md","pdf":"https://engineer.company/glossary/cldr/index.pdf"},"kind":"page","language":"en","title":"What is CLDR?","url":"https://engineer.company/glossary/cldr/","version":1}