PackagesIso localeLocale & BCP 47

Locale & BCP 47

Working with locales, BCP 47 language tags, and currency mapping.

Last updated:

Locale & BCP 47

@visulima/iso-locale provides enhanced locale support with BCP 47 language tag parsing, generation, and currency mapping.

Currency from Locale

Get currency code from locale or country code:

import { getCurrency } from "@visulima/iso-locale";

// BCP 47 format
getCurrency("en-US"); // "USD"
getCurrency("pt-BR"); // "BRL"
getCurrency("zh-Hant-TW"); // "TWD"

// Underscore format
getCurrency("en_US"); // "USD"
getCurrency("pt_BR"); // "BRL"

// Direct country code
getCurrency("US"); // "USD"
getCurrency("GB"); // "GBP"

BCP 47 Language Tags

Parse BCP 47 Tags

import { parseBCP47Tag } from "@visulima/iso-locale";

const parsed = parseBCP47Tag("en-US");
console.log(parsed);
// { language: "en", country: "US" }

const parsed2 = parseBCP47Tag("zh-Hant-TW");
console.log(parsed2);
// { language: "zh", script: "Hant", country: "TW" }

Generate BCP 47 Tags

import { generateBCP47Tag } from "@visulima/iso-locale";

generateBCP47Tag("en", "US"); // "en-US"
generateBCP47Tag("fr", "FR"); // "fr-FR"
generateBCP47Tag("zh", "TW", "Hant"); // "zh-Hant-TW"

Get BCP 47 Tags for Country

import { getBCP47Tags } from "@visulima/iso-locale";

// Single language country
getBCP47Tags("US"); // ["en-US"]

// Multi-language country
getBCP47Tags("CA"); // ["en-CA", "fr-CA"]
getBCP47Tags("CH"); // ["de-CH", "fr-CH", "it-CH", "rm-CH"]

Validate BCP 47 Tags

import { isValidBCP47Tag } from "@visulima/iso-locale";

isValidBCP47Tag("en-US"); // true
isValidBCP47Tag("zh-Hant-TW"); // true
isValidBCP47Tag("invalid"); // false

ISO 639 Language Code Conversion

Convert between ISO 639-3 (3-letter) and ISO 639-1 (2-letter) codes:

import { iso6393To6391, convert6393To6391 } from "@visulima/iso-locale";

// Single conversion
iso6393To6391("eng"); // "en"
iso6393To6391("fra"); // "fr"
iso6393To6391("spa"); // "es"

// Array conversion
convert6393To6391(["eng", "fra", "spa"]); // ["en", "fr", "es"]

Get Locales for Currency

Find all countries using a specific currency:

import { getLocales } from "@visulima/iso-locale";

getLocales("EUR"); // ["FR", "DE", "ES", "IT", ...]
getLocales("USD"); // ["US", ...]

Examples

Build Locale-Aware Currency Formatter

import { getCurrency, getSymbol, getByCode } from "@visulima/iso-locale";

function formatCurrencyByLocale(amount: number, locale: string): string {
    const currencyCode = getCurrency(locale);
    if (!currencyCode) return `${amount}`;

    const currency = getByCode(currencyCode);
    const symbol = getSymbol(currencyCode);
    const decimals = currency?.decimals ?? 2;

    return `${symbol}${amount.toFixed(decimals)}`;
}

formatCurrencyByLocale(100, "en-US"); // "$100.00"
formatCurrencyByLocale(100, "en-GB"); // "£100.00"
formatCurrencyByLocale(100, "fr-FR"); // "€100.00"

Generate Locale Options for Select

import { getBCP47Tags, getByAlpha2 } from "@visulima/iso-locale";

function getLocaleOptions(countryCode: string) {
    const tags = getBCP47Tags(countryCode);
    const country = getByAlpha2(countryCode);

    return tags.map((tag) => ({
        value: tag,
        label: `${tag} - ${country?.name}`,
    }));
}

getLocaleOptions("CA");
// [
//   { value: "en-CA", label: "en-CA - Canada" },
//   { value: "fr-CA", label: "fr-CA - Canada" }
// ]

Parse User Locale Input

import { parseBCP47Tag, getCurrency } from "@visulima/iso-locale";

function parseUserLocale(locale: string) {
    const parsed = parseBCP47Tag(locale);
    if (!parsed) {
        throw new Error(`Invalid locale: ${locale}`);
    }

    return {
        language: parsed.language,
        country: parsed.country,
        script: parsed.script,
        currency: parsed.country ? getCurrency(locale) : undefined,
    };
}

parseUserLocale("en-US");
// { language: "en", country: "US", currency: "USD" }

Next Steps

Support

Contribute to our work and keep us going

Community is the heart of open source. The success of our packages wouldn't be possible without the incredible contributions of users, testers, and developers who collaborate with us every day.Want to get involved? Here are some tips on how you can make a meaningful impact on our open source projects.

Ready to help us out?

Be sure to check out the package's contribution guidelines first. They'll walk you through the process on how to properly submit an issue or pull request to our repositories.

Submit a pull request

Found something to improve? Fork the repo, make your changes, and open a PR. We review every contribution and provide feedback to help you get merged.

Good first issues

Simple issues suited for people new to open source development, and often a good place to start working on a package.
View good first issues