locale-currency

locale-currency

A map of locale codes to ISO 4217 currency codes. Supports BCP 47, i18n, and ISO 3166-1 alpha-2 locale formats.

Supported Formats

• BCP 47 language tags (e.g., zh-Hant-TW, en-US, pt-BR)
• i18n locale codes with underscores (e.g., en_US, zh_TW)
• ISO 3166-1 alpha-2 country codes (e.g., US, GB, TW)

The library intelligently extracts the country/region code from complex locale strings to determine the appropriate currency.

Installation

npm install locale-currency

Usage

ES Modules (recommended)

import { getCurrency, getLocales } from 'locale-currency';

// Get currency for a locale
getCurrency('US');           // 'USD'
getCurrency('en-US');        // 'USD'
getCurrency('en_US');        // 'USD'
getCurrency('zh-Hant-TW');   // 'TWD' - BCP 47 format
getCurrency('GB');           // 'GBP'
getCurrency('ES');           // 'EUR'

// Get all countries that use a currency
const euroCountries = getLocales('EUR');
// ['AD', 'AT', 'BE', 'CY', 'DE', 'EE', 'ES', 'FI', 'FR', 'GR', ...]

CommonJS

const { getCurrency, getLocales } = require('locale-currency');

getCurrency('en-US'); // 'USD'

API

getCurrency(locale: string): string | null

Returns the ISO 4217 currency code for a given locale, or null if not found.

• Parameters:
  • locale - BCP 47, i18n, or ISO 3166-1 alpha-2 code
• Returns: Currency code (e.g., 'USD', 'EUR') or null

getLocales(currencyCode: string): string[]

Returns an array of ISO 3166-1 alpha-2 country codes that use the given currency.

• Parameters:
  • currencyCode - ISO 4217 currency code (e.g., 'USD', 'EUR')
• Returns: Array of country codes

Examples

import { getCurrency, getLocales } from 'locale-currency';

// Case insensitive
getCurrency('us');   // 'USD'
getCurrency('US');   // 'USD'
getCurrency('Us');   // 'USD'

// i18n format with underscores
getCurrency('EN_US');  // 'USD'
getCurrency('en_us');  // 'USD'

// BCP 47 format with hyphens
getCurrency('EN-US');  // 'USD'
getCurrency('en-us');  // 'USD'

// Complex BCP 47 with script code
getCurrency('zh-Hant-TW');  // 'TWD' (Traditional Chinese in Taiwan)
getCurrency('zh-Hans-CN');  // 'CNY' (Simplified Chinese in China)

// Direct country codes
getCurrency('GB');  // 'GBP'
getCurrency('ES');  // 'EUR'
getCurrency('GR');  // 'EUR'

// Find countries using Euro
const euroCountries = getLocales('EUR');
console.log(euroCountries.includes('GR'));  // true (Greece)
console.log(euroCountries.includes('FR'));  // true (France)
console.log(euroCountries.includes('ES'));  // true (Spain)