A comprehensive TypeScript library providing ISO standards for handling countries, languages, dialects, and currencies. This package offers full type safety using Zod validation with support for ISO 3166 country codes, ISO 639 language codes, BCP-47 dialects, and ISO 4217 currency codes.
- 🌍 Complete ISO 3166-1 Support: All official country codes (Alpha-2, Alpha-3, and Numeric)
- 🗺️ Regional Classifications: Business regions (EMEA, APAC, AMER, LATAM, NA, SA, MEA)
- 🌎 Continental Classifications: Geographic continents (Africa, Antarctica, Asia, Europe, North America, Oceania, South America)
- 🌐 ISO 639 Language Support: Complete language codes (ISO 639-1 and ISO 639-3)
- 🗣️ BCP-47 Dialect Support: Regional language variants with native names
- 💰 ISO 4217 Currency Support: Currency codes, symbols, and fractional units
- 🔒 Type Safety: Built with TypeScript and Zod for runtime validation
- 📦 Tree-shakable: Only import what you need
- 🚀 Zero Dependencies: Minimal footprint (only Zod for validation)
- ✅ Fully Tested: Comprehensive test coverage
pnpm add @reacture-io/iso-locale
Note: This package requires pnpm as the package manager. Please use pnpm instead of npm or yarn.
import { countries, getCountryByAlpha2, getCountryByAlpha3 } from '@reacture-io/iso-locale/countries';
// Find by Alpha-2 code (2-letter country code)
const usa = getCountryByAlpha2('US');
console.log(usa);
// {
// name: "United States of America",
// alpha2: "US",
// alpha3: "USA",
// numeric: "840",
// continents: ["North America"],
// regions: ["AMER", "NA"],
// dialects: ["en-US"],
// currency: "USD"
// }
// Find by Alpha-3 code (3-letter country code)
const canada = getCountryByAlpha3('CAN');
console.log(canada);
// {
// name: "Canada",
// alpha2: "CA",
// alpha3: "CAN",
// numeric: "124",
// continents: ["North America"],
// regions: ["AMER", "NA"],
// dialects: ["en-CA", "fr-CA"],
// currency: "CAD"
// }
// Find by numeric code
const germany = getCountryByNumeric('276');
console.log(germany);
// {
// name: "Germany",
// alpha2: "DE",
// alpha3: "DEU",
// numeric: "276",
// continents: ["Europe"],
// regions: ["EMEA"],
// dialects: ["de-DE"],
// currency: "EUR"
// }
// Find by country name
const france = getCountryByName('France');
console.log(france);
// {
// name: "France",
// alpha2: "FR",
// alpha3: "FRA",
// numeric: "250",
// continents: ["Europe"],
// regions: ["EMEA"],
// dialects: ["fr-FR"],
// currency: "EUR"
// }
import { getCountriesByRegion, isPartOfRegion } from '@reacture-io/iso-locale/countries';
// Get all countries in a specific region
const emeaCountries = getCountriesByRegion('EMEA');
console.log(emeaCountries.length); // Number of EMEA countries
// Check if a country belongs to a region
const usa = getCountryByAlpha2('US');
if (usa) {
console.log(isPartOfRegion(usa, 'AMER')); // true
console.log(isPartOfRegion(usa, 'EMEA')); // false
}
import { getCountriesByContinent } from '@reacture-io/iso-locale/countries';
// Get all countries in a specific continent
const europeanCountries = getCountriesByContinent('Europe');
console.log(europeanCountries.length); // Number of European countries
// Some countries span multiple continents
const russia = getCountryByAlpha2('RU');
console.log(russia?.continents); // ["Asia", "Europe"]
import { isValidAlpha2, isValidAlpha3, isValidCountry, isValidRegion, isValidContinent } from '@reacture-io/iso-locale/countries';
// Validate Alpha-2 codes
console.log(isValidAlpha2('US')); // true
console.log(isValidAlpha2('XX')); // false
// Validate Alpha-3 codes
console.log(isValidAlpha3('USA')); // true
console.log(isValidAlpha3('XXX')); // false
// Validate country names
console.log(isValidCountry('United States of America')); // true
console.log(isValidCountry('Wonderland')); // false
// Validate regions
console.log(isValidRegion('EMEA')); // true
console.log(isValidRegion('INVALID')); // false
// Validate continents
console.log(isValidContinent('Europe')); // true
console.log(isValidContinent('Invalid')); // false
import { languages, getLanguageByCode } from '@reacture-io/iso-locale/languages';
// Find by ISO 639-1 code (2-letter language code)
const english = getLanguageByCode('en');
console.log(english);
// {
// language: "English",
// native: "English",
// iso639_1: "en",
// iso639_3: "eng"
// }
// Find by ISO 639-3 code (3-letter language code)
const french = getLanguageByCode('fra');
console.log(french);
// {
// language: "French",
// native: "Français",
// iso639_1: "fr",
// iso639_3: "fra"
// }
// Access all languages
console.log(languages.length); // Number of supported languages
import { isValidISO639_1, isValidISO639_3, isValidLanguage } from '@reacture-io/iso-locale/languages';
// Validate ISO 639-1 codes
console.log(isValidISO639_1('en')); // true
console.log(isValidISO639_1('xx')); // false
// Validate ISO 639-3 codes
console.log(isValidISO639_3('eng')); // true
console.log(isValidISO639_3('xxx')); // false
console.log(isValidBCP47("en-US")); // true
console.log(isValidBCP47("en-XX")); // false
// Validate language objects
console.log(isValidLanguage({ language: "English", native: "English", iso639_1: "en", iso639_3: "eng" })); // true
import { dialects, getDialectByCode, getDialectsByCode } from '@reacture-io/iso-locale/languages';
// Find by BCP-47 code (language-region code)
const usEnglish = getDialectByCode('en-US');
console.log(usEnglish);
// {
// dialect: "English (United States)",
// native: "English (United States)",
// iso639_1: "en",
// iso639_3: "eng",
// bcp47: "en-US"
// }
// Find all dialects for a language
const englishDialects = getDialectsByCode('en');
console.log(englishDialects.length); // Number of English dialects
// Access all dialects
console.log(dialects.length); // Number of supported dialects
import { isValidBCP47, isValidDialect } from '@reacture-io/iso-locale/languages';
// Validate BCP-47 codes
console.log(isValidBCP47('en-US')); // true
console.log(isValidBCP47('en-XX')); // false
// Validate dialect objects
console.log(isValidDialect({ dialect: "English (United States)", native: "English (United States)", iso639_1: "en", iso639_3: "eng", bcp47: "en-US" })); // true
import { currencies, getCurrencyByISO4217, getCurrenciesBySymbol } from '@reacture-io/iso-locale/currencies';
// Find by ISO 4217 code (3-letter currency code)
const usd = getCurrencyByISO4217('USD');
console.log(usd);
// {
// name: "United States dollar",
// symbol: "$",
// iso4217: "USD",
// factionalUnit: "Cent"
// }
// Find currencies by symbol
const dollarCurrencies = getCurrenciesBySymbol('$');
console.log(dollarCurrencies.length); // Number of currencies using $ symbol
// Find currencies by name
const euroCurrencies = getCurrenciesByName('Euro');
console.log(euroCurrencies);
// [{
// name: "Euro",
// symbol: "€",
// iso4217: "EUR",
// factionalUnit: "Cent"
// }]
// Access all currencies
console.log(currencies.length); // Number of supported currencies
import { isValidISO4217, isValidSymbol, isValidCurrency } from '@reacture-io/iso-locale/currencies';
// Validate ISO 4217 codes
console.log(isValidISO4217('USD')); // true
console.log(isValidISO4217('XXX')); // false
// Validate currency symbols
console.log(isValidSymbol('$')); // true
console.log(isValidSymbol('INVALID')); // false
// Validate currency objects
console.log(isValidCurrency({ name: "United States dollar", symbol: "$", iso4217: "USD", factionalUnit: "Cent" })); // true
The main country object type containing all country information:
type Country = {
name: CountryName;
alpha2: Alpha2;
alpha3: Alpha3;
numeric: Numeric;
continents: Continent[];
regions: Region[];
dialects: string[];
currency: string;
}
Type for valid country names (e.g., "United States of America", "Canada")
Type for 2-letter country codes (e.g., "US", "CA", "DE")
Type for 3-letter country codes (e.g., "USA", "CAN", "DEU")
Type for 3-digit numeric country codes (e.g., "840", "124", "276")
Type for business regions: "EMEA" | "APAC" | "AMER" | "LATAM" | "NA" | "SA" | "MEA"
Type for geographic continents: "Africa" | "Antarctica" | "Asia" | "Europe" | "North America" | "Oceania" | "South America"
Finds a country by its Alpha-2 code.
Finds a country by its Alpha-3 code.
Finds a country by its numeric code.
Finds a country by its official name.
Returns all countries that belong to the specified region.
Returns all countries that belong to the specified continent.
Checks if a country belongs to the specified region.
Validates if a value is a valid Alpha-2 country code.
Validates if a value is a valid Alpha-3 country code.
Validates if a value is a valid country name.
Validates if a value is a valid region.
Validates if a value is a valid continent.
The main language object type:
type Language = {
language: LanguageName;
native: string;
iso639_1: ISO639_1;
iso639_3: ISO639_3;
}
Type for valid language names (e.g., "English", "French", "German")
Type for 2-letter language codes (e.g., "en", "fr", "de")
Type for 3-letter language codes (e.g., "eng", "fra", "deu")
Finds a language by its ISO 639-1 or ISO 639-3 code.
Validates if a value is a valid ISO 639-1 language code.
Validates if a value is a valid ISO 639-3 language code.
Validates if a value is a valid language object.
The main dialect object type:
type Dialect = {
dialect: string;
native: string;
iso639_1?: ISO639_1;
iso639_3?: ISO639_3;
bcp47: BCP47;
}
Type for BCP-47 language-region codes (e.g., "en-US", "fr-FR", "de-DE")
Finds a dialect by its BCP-47 code.
Returns all dialects for a specific language.
Validates if a value is a valid BCP-47 code.
Validates if a value is a valid dialect object.
The main currency object type:
type Currency = {
name: CurrencyName;
symbol?: Symbol;
iso4217?: ISO4217;
factionalUnit?: FactionalUnit;
}
Type for valid currency names (e.g., "United States dollar", "Euro")
Type for currency symbols (e.g., "$", "€", "£")
Type for 3-letter currency codes (e.g., "USD", "EUR", "GBP")
Type for fractional unit names (e.g., "Cent", "Pence", "Centime")
Finds a currency by its ISO 4217 code.
Returns all currencies that use the specified symbol.
Returns all currencies with the specified name.
Validates if a value is a valid ISO 4217 currency code.
Validates if a value is a valid currency symbol.
Validates if a value is a valid currency object.
Array containing all 249 ISO 3166-1 countries with their complete information including regions and continents.
Array containing all supported languages with their ISO 639-1 and ISO 639-3 codes.
Array containing all supported language dialects with their BCP-47 codes.
Array containing all supported currencies with their ISO 4217 codes and symbols.
This package implements multiple ISO standards:
Defines country codes:
- Alpha-2 codes: Two-letter country codes (e.g., "US", "CA")
- Alpha-3 codes: Three-letter country codes (e.g., "USA", "CAN")
- Numeric codes: Three-digit numeric codes (e.g., "840", "124")
Defines language codes:
- ISO 639-1: Two-letter language codes (e.g., "en", "fr")
- ISO 639-3: Three-letter language codes (e.g., "eng", "fra")
Defines language-region codes for dialects and regional variants (e.g., "en-US", "fr-FR")
Defines currency codes:
- Three-letter codes: Currency identifiers (e.g., "USD", "EUR")
- Symbols: Currency symbols (e.g., "$", "€")
- Fractional units: Subdivision names (e.g., "Cent", "Pence")
The package includes business-oriented regional classifications:
- EMEA: Europe, Middle East, and Africa
- APAC: Asia-Pacific
- AMER: Americas
- LATAM: Latin America
- NA: North America
- SA: South America
- MEA: Middle East and Africa
Geographic continental classifications are also provided:
- Africa: African continent
- Antarctica: Antarctic continent
- Asia: Asian continent
- Europe: European continent
- North America: North American continent
- Oceania: Oceanian continent
- South America: South American continent
- Node.js >= 22.0.0
- pnpm >= 10.0.0
# Build the package
pnpm build
# Development mode with watch
pnpm dev
# Run tests
pnpm test
# Format code
pnpm format
# Lint code
pnpm lint
The package includes comprehensive tests for all functionality:
pnpm test
MIT © Indy Van Canegem
Contributions are welcome! Please ensure all tests pass and code is properly formatted before submitting a pull request.