@codebender-io/i18n-currency

@codebender-io/i18n-currency

Maintained by CodeBender — website: https://codebender.io · GitHub: https://github.com/codebender-io

What is this?

@codebender-io/i18n-currency is a small, focused utility library that provides:

• base ISO-4217 currency metadata (codes, symbols, decimal digits, subunit info),
• localized currency names and subunit names for multiple locales,
• convenient lookup utilities by locale and by country.

It is intended for server and client (Node >=20 / ESM) usage and designed in TypeScript with full types.

Size & bundle behaviour

• Base package (ESM, minified + gzipped) — ~39.7 KB.
• Each locale file (JSON) — ~19–24 KB.

The library is fully modular and tree-shakeable: we expose ESM modules and ship locale files as separate JSON assets, so your bundler will include only the base code and the locale files you import. In other words — you ship what you use only.

How to keep bundles small

• Import only the locales you need (don't import the entire locales directory).
• Use a standard production build (e.g. webpack/rollup/esbuild) with tree-shaking enabled to remove any unused exports.

Install

# npm
npm install @codebender-io/i18n-currency

# pnpm
pnpm add @codebender-io/i18n-currency

# yarn
yarn add @codebender-io/i18n-currency

ESM / CJS usage

The package ships both ESM and CommonJS builds. Use import for modern projects and require() for older environments.

import { CurrencyLibrary } from "@codebender-io/i18n-currency";

const { CurrencyLibrary } = require("@codebender-io/i18n-currency");

Quick example

import { CurrencyLibrary } from "@codebender-io/i18n-currency";
// or for CJS require:
// const { CurrencyLibrary } = require("@codebender-io/i18n-currency");

import enLocales from "@codebender-io/i18n-currency/locales/en.json" assert { type: "json" };

const lib = new CurrencyLibrary({ locales: { en: enLocales }, fallbackLocale: "en" });

const usd = lib.getCurrency("en-US", "USD");
console.log(usd?.name); // "US Dollar" (for the provided locale data)

Note: This package expects you to provide localized locales when constructing CurrencyLibrary. The library includes base currency metadata bundled in src/data/base-currencies.json and country mappings in src/data/country-currencies.json. Provide locale JSON maps for translated names.

API

Types (summary)

export interface CurrencyBase {
	code: string;
	numeric_code: string;
	symbol: string;
	symbol_native: string;
	decimal_digits: number;
	rounding: number;
	subunit_to_unit: number;
	countries: string[]; // ISO 3166-1 alpha-2 codes
	name_native: string;
	subunit_name_native: string;
}

export interface CurrencyLocalized {
	name: string;
	name_plural: string;
	subunit_name: string;
	subunit_name_plural: string;
}

export type Currency = CurrencyBase & CurrencyLocalized;
export type CurrencyCode = string;
export type CurrencyBaseMap = Record<CurrencyCode, CurrencyBase>;
export type CurrencyLocalizedMap = Record<CurrencyCode, CurrencyLocalized>;
export type CurrencyMap = Record<CurrencyCode, Currency>;
export type LocaleCode = string;
export type LocaleCurrencyMap = Record<LocaleCode, CurrencyLocalizedMap>;
export type CountryCode = string;
export type CountryCurrencyMap = Record<CountryCode, CurrencyCode[]>;

new CurrencyLibrary({ locales, fallbackLocale = "en" })

• locales: LocaleCurrencyMap — mapping of locale keys (e.g., en, fr) to localized currency translations.
• fallbackLocale?: string — fallback locale root (defaults to "en"). Throws if resolved fallback is not present in locales.

Methods

• getMap(locale: string): CurrencyMap
  Returns a merged map of base currency data + localized fields for the best-match locale (root language fallback).

• getList(locale: string): Currency[]
  Returns an array of all localized currency objects for the locale.

• getCurrency(locale: string, code: string): Currency | undefined
  Returns a single localized currency object or undefined if not found.

• hasCurrency(code: string): boolean
  Returns true if the currency code exists in base data.

• getCurrenciesByCountry(countryCode: string): CurrencyCode[]
  Returns a list of currency codes used by the country (throws if country not found).

• getCountryCurrencyData(locale: string, countryCode: string): Currency[]
  Returns the localized currency objects for the currencies used by countryCode.

• getPrimaryCurrencyByCountry(countryCode: string): CurrencyCode
  The first currency code listed for the country.

• hasMultipleCurrencies(countryCode: string): boolean
true when the country uses multiple currencies.

• getSupportedCountryCodes(): CountryCode[]
  All supported country codes (upper case).

• getCountriesByCurrency(currencyCode: CurrencyCode): CountryCode[]
  Countries that use a specified currency.

• getCurrencyCodes(): CurrencyCode[]
  All available ISO 4217 codes.

• getAvailableLocales(): LocaleCode[]
  Returns locales provided in the initialization locales argument.

• getLocaleBestMatch(locale: string): string
  Returns the best matching locale from available locales, falling back to the configured fallback locale.

• isLocaleSupported(locale: string): boolean
  Checks if locale root is supported.

✅ Summary

Function	Description
getMap(locale)	Get currency map for locale
getList(locale)	List all currencies for a locale
getCurrency(locale, code)	Get localized currency info
hasCurrency(code)	Check if currency code exists
getCurrenciesByCountry(countryCode)	Get currency codes by country
getCountryCurrencyData(locale, countryCode)	Get localized currency data by country
getPrimaryCurrencyByCountry(countryCode)	Get country's main currency
hasMultipleCurrencies(countryCode)	Check if a country uses multiple currencies
getSupportedCountryCodes()	List all supported country codes
getCountriesByCurrency(code)	Get all countries using a currency
getCurrencyCodes()	List all available currency codes
getAvailableLocales()	List available locales
getLocaleBestMatch(locale)	Get best matching locale
isLocaleSupported(locale)	Verify if a locale is supported

Locale JSON shape (example)

A locale map should be an object where top-level keys are currency codes and values provide localized fields:

{
	"USD": {
		"name": "US Dollar",
		"name_plural": "US Dollars",
		"subunit_name": "cent",
		"subunit_name_plural": "cents"
	},
	"EUR": {
		"name": "Euro",
		"name_plural": "Euros",
		"subunit_name": "cent",
		"subunit_name_plural": "cents"
	}
}

You can provide multiple locale roots:

const locales = {
	en: require("@codebender-io/i18n-currency/locales/en.json"),
	fr: require("@codebender-io/i18n-currency/locales/fr.json"),
};

Usage Examples

This document demonstrates how to use the CurrencyLibrary class to access currency and localization data.

1. Importing and Initializing the Library

import { CurrencyLibrary } from "@codebender-io/i18n-currency";
import en from "@codebender-io/i18n-currency/locales/en.json" assert { type: "json" };
import fr from "@codebender-io/i18n-currency/locales/fr.json" assert { type: "json" };

// Initialize with available locales
const lib = new CurrencyLibrary({
	locales: { en, fr },
	fallbackLocale: "en",
});

2. Get Localized Currency Data

Get a Specific Currency

const usd = lib.getCurrency("en-US", "usd");
console.log(usd?.name); // "US Dollar"

Get All Currencies for a Locale

const currencies = lib.getList("fr");
console.log(currencies.length); // e.g., 180

Check if a Currency Exists

console.log(lib.hasCurrency("JPY")); // true

3. Country-Based Lookups

Get All Currencies Used by a Country

const currencies = lib.getCurrenciesByCountry("US");
console.log(currencies); // ["USD"]

Get Localized Currency Data for a Country

const countryData = lib.getCountryCurrencyData("fr", "CA");
console.log(countryData[0].name); // "Dollar canadien"

Get Primary Currency of a Country

const mainCurrency = lib.getPrimaryCurrencyByCountry("JP");
console.log(mainCurrency); // "JPY"

Check if a Country Has Multiple Currencies

console.log(lib.hasMultipleCurrencies("CH")); // true (Switzerland: CHF, EUR)

4. Supported Data Utilities

List Supported Countries

const countries = lib.getSupportedCountryCodes();
console.log(countries.slice(0, 5)); // ["US", "CA", "GB", "FR", "DE"]

List Supported Currency Codes

const codes = lib.getCurrencyCodes();
console.log(codes.length); // e.g., 180

Get Countries Using a Specific Currency

const euroCountries = lib.getCountriesByCurrency("EUR");
console.log(euroCountries); // ["FR", "DE", "IT", "ES", ...]

List Available Locales

console.log(lib.getAvailableLocales()); // ["en", "fr"]

Check Locale Support

console.log(lib.isLocaleSupported("fr-CA")); // true
console.log(lib.isLocaleSupported("xx-YY")); // false

5. Locale Matching

Get Best Match for a Locale

console.log(lib.getLocaleBestMatch("en-US")); // "en"
console.log(lib.getLocaleBestMatch("fr-CA")); // "fr"
console.log(lib.getLocaleBestMatch("xx-YY")); // "en" (fallback)

Contribution

Contributions welcome! Please open issues or PRs on GitHub: https://github.com/codebender-io/i18n-currency

Suggested workflow:

• Fork repository
• Create feature branch
• Run pnpm install
• Run pnpm build
• Run pnpm test (if available)
• Open PR and describe changes

License

Apache-2.0 — see LICENSE file.

Contact & Links

• Website: https://codebender.io
• GitHub: https://github.com/codebender-io
• npm org: https://www.npmjs.com/org/codebender-io
• LinkedIn: https://www.linkedin.com/company/codebender-io

Publishing notes

• Scoped packages default to private on npm. To publish publicly use:

  npm publish --access public
  

• Ensure you are logged into an npm user that has publish access to @codebender-io.

Copyright © 2025 CodeBender. Licensed under Apache-2.0. See LICENSE for details.