# ilib-localedata > Load and cache iLib locale data Latest version **1.5.6** (published 2026-08-27) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install ilib-localedata pnpm add ilib-localedata yarn add ilib-localedata bun add ilib-localedata ``` ## Health **Score 65/100 (B)** — status: active. Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score. Warnings: low downloads; no types. ## Facts | | | |---|---| | Version | 1.5.6 | | Published | 2026-08-27 | | First published | 2022-04-14 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | none | | Module format | ESM + CommonJS | | Node | >=12 <23 | | Dependencies | 7 | | Unpacked size | 505.6 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 7 | | Author | Edwin Hoogerbeets | | Maintainers | ehoogerbeets | | Keywords | internationalization, i18n, localization, l10n, globalization, g11n, date, time, format, locale, translation, localedata | ## Links - npm: https://www.npmjs.com/package/ilib-localedata - Repository: https://github.com/iLib-js/ilib-mono - Homepage: https://github.com/iLib-js/ilib-mono/blob/main/packages/ilib-localedata - Issues: https://github.com/iLib-js/ilib-mono/issues - npm.io page: https://npm.io/package/ilib-localedata ## Dependencies (7) - [json5](https://npm.io/package/json5.md) ^2.2.1 - [ilib-env](https://npm.io/package/ilib-env.md) ^1.4.3 - [ilib-common](https://npm.io/package/ilib-common.md) ^1.1.7 - [ilib-loader](https://npm.io/package/ilib-loader.md) ^1.4.1 - [ilib-locale](https://npm.io/package/ilib-locale.md) ^1.4.0 - [ilib-localematcher](https://npm.io/package/ilib-localematcher.md) ^1.3.4 - [@log4js-node/log4js-api](https://npm.io/package/@log4js-node/log4js-api.md) ^1.0.2 ## Alternatives - [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads - [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads - [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads - [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads - [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads ## Recent versions - 1.5.6 (latest) — 2026-08-27 - 1.5.5 — 2026-07-13 - 1.5.4 — 2026-04-17 - 1.5.3 — 2025-06-07 - 1.5.2 — 2024-12-19 - 1.5.1 — 2024-12-10 - 1.5.0 — 2022-10-20 - 1.4.1 — 2022-09-14 - 1.4.0 — 2022-09-07 - 1.3.3 — 2022-09-01 - 1.3.2 — 2022-08-03 - 1.3.1 — 2022-07-11 - 1.3.0 — 2022-07-07 - 1.1.0 — 2022-04-18 - 1.0.0 — 2022-04-14 ## README # ilib-localedata **ilib-localedata** loads iLib locale data in a way that **avoids race conditions** and **avoids reloading** the same files repeatedly. It merges locale fallback chains, caches aggressively (including sharing in-flight loads so concurrent callers do not duplicate work), and performs I/O through **[ilib-loader](https://www.npmjs.com/package/ilib-loader)** so the same code can run on Node, in browsers, with bundlers, and other environments. Supported locale data styles -------------------- iLib has evolved on several platforms, so this package understands more than one on-disk shape. All of them can be used with **synchronous** or **asynchronous** loading, depending on the loader and how the data is packaged. - **Individual raw JSON files** — Typical for Node.js apps: many small files (per locale part and **basename**, or equivalent layouts), loaded sync or async through the loader. - **Assembled JSON files, one per locale** — A single file per locale contains the locale data your app was configured to need. **Which** basenames and **which** locales are included is decided when you run **[ilib-assemble](https://github.com/iLib-js/ilib-mono/blob/main/packages/ilib-assemble/README.md)**; at runtime you load one file per locale instead of many fragments. See that package’s documentation in this monorepo for how assembly works. - **Assembled JS files, one per locale** — Same idea as assembled JSON, but each locale is a **JavaScript module** (modern ES modules). That fits **webpack** and many websites, where JSON often cannot be `import`’d the same way as `.js`. These styles are **historical and practical**: they cover the different ways iLib has been deployed while still supporting both sync and async loading paths. Overview -------------------- **Application code** usually does not call the low-level `loadData` API. The package exists primarily for **other iLib libraries** (date formatting, locale info, and so on) to share one loading and caching implementation. The common **exception** is startup **preloading**: apps that depend on those libraries often import **`LocaleData`** once and call **`LocaleData.ensureLocale()`** so that all later iLib usage can run **synchronously** without threading `async` through the whole app (see [below](#preloading-locale-data-for-app-developers)). It is **possible** to use ilib-localedata for **non–iLib** locale data if you adopt compatible file layout and conventions, but that is entirely up to the application developer; the design targets iLib data and packages. Do **not** rely on loading another package’s raw locale files as a stable API—each package should expose its own documented surface; on-disk basenames and layout are not a contract between packages. Preloading locale data for app developers -------------------- If your app uses iLib libraries, you have two broad options: **await** each library call that loads data asynchronously (which pushes async through your own APIs), or **preload** everything once at startup. Preloading uses **`LocaleData.ensureLocale()`**. It loads the same assembled locale files as the rest of the stack (the per-locale `[locale].js` / `[locale].json` bundles), in the same way as `loadData()`, but does it **once**, asynchronously. After that, data lives in the shared cache, so subsequent iLib calls can use **synchronous** code paths—as if the whole stack were sync. ```javascript import { LocaleData } from 'ilib-localedata'; import { getLocale } from 'ilib-env'; // start of app const locale = getLocale(); await LocaleData.ensureLocale(locale); // now you can use ilib libraries as if they were sync-loaded: const df = new DateFormat({ date: 'long', locale }); const formattedDate = df.format(date); ``` For parameters, failure behavior, and how assembled files are structured, see the **`ensureLocale`** documentation in the [API reference](./docs/ilib-localedata.md). Installation -------------------- ```bash npm install ilib-localedata ``` You also need **ilib-loader** (and its peers such as **ilib-env**, **ilib-locale**) so file loading works in your environment (Node, browser, bundler, etc.). Those are declared as dependencies of this package; configure the loader as described in the ilib-loader documentation. Basic usage -------------------- The following pattern is what **iLib libraries** use internally. If you are maintaining such a package, get a **singleton** per locale root with the default export `getLocaleData` (do not `new LocaleData()` yourself). Pass the filesystem path to **your** package’s locale directory. Then call `loadData` with a locale and basename; use `sync: true` only where the loader supports synchronous reads (for example Node). ```javascript import getLocaleData, { LocaleData } from 'ilib-localedata'; // Optional: search additional roots first (e.g. app or OS overrides) LocaleData.addGlobalRoot('/path/to/custom/locale'); const localeData = getLocaleData({ path: '/path/to/your-package/locale' }); // Async (works everywhere) const data = await localeData.loadData({ locale: 'de-DE', basename: 'info' }); // Sync, when the loader supports it and data is available const syncData = localeData.loadData({ locale: 'de-DE', basename: 'info', sync: true }); ``` For merge options, roots, `cacheData`, and edge cases, see the [architecture document](./docs/Architecture.md) and [API reference](./docs/ilib-localedata.md). Architecture -------------------- For how locale data loading, caching, and packaging fit together, see [Architecture](./docs/Architecture.md). Full JS Docs -------------------- To see a full explanation of the LocaleData class, please see the [full API documentation](./docs/ilib-localedata.md). Logging -------------------- Use the name "ilib-localedata" to configure a log4js appender in your app to see logging output from this library. ## License Copyright © 2022, 2025-2026 JEDLSoft This package is released under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). The full license text is available in the [LICENSE](https://github.com/iLib-js/ilib-mono/blob/main/packages/ilib-localedata/LICENSE) file in the ilib-mono repository on GitHub. ## Release Notes See [CHANGELOG.md](https://github.com/iLib-js/ilib-mono/blob/main/packages/ilib-localedata/CHANGELOG.md). --- _Source: https://npm.io/package/ilib-localedata · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._