@suaveplan/locale-data - Static ISO 3166-1 country data and ISO 639-1 language data with typed lookup functions, OTel instrumentation, and Zod schemas

Summary

Static ISO 3166-1 country data and ISO 639-1 language data with typed lookup functions, OTel instrumentation, and Zod schemas.

Documentation tree

countries — (no submodules)
- countries.data — Contains the static ISO 3166-1 alpha-2 country dataset as a single frozen TypeScript constant (COUNTRIES_DATA). This…
- countries — (no submodules)
errors — (no submodules)
- locale-data-error — (no submodules)
languages — (no submodules)
- languages.data — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: LANGUAGES_DATA (130+ language entr…
- languages — (no submodules)
types — (no submodules)
- types — (no submodules)

- [countries.data](./src/countries/countries.data.md) — Contains the static ISO 3166-1 alpha-2 country dataset as a single frozen TypeScript constant (`COUNTRIES_DATA`). This…

countries — (no submodules)- errors — (no submodules)- locale-data-error — (no submodules)- languages — (no submodules)- languages.data — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: LANGUAGES_DATA (130+ language entr…
languages — (no submodules)- types — (no submodules)- types — (no submodules)- countries.data — Contains the static ISO 3166-1 alpha-2 country dataset as a single frozen TypeScript constant (COUNTRIES_DATA). This…
countries — (no submodules)- errors — (no submodules)- locale-data-error — (no submodules)- languages — (no submodules)- languages.data — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: LANGUAGES_DATA (130+ language entr…
- languages — (no submodules)- types — (no submodules)- types — (no submodules)- countries.data — Contains the static ISO 3166-1 alpha-2 country dataset as a single frozen TypeScript constant (COUNTRIES_DATA). This…
countries — (no submodules)- errors — (no submodules)- locale-data-error — (no submodules)- languages — (no submodules)- languages.data — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: LANGUAGES_DATA (130+ language entr…
- languages — (no submodules)- types — (no submodules)- types — (no submodules)- countries.data — Contains the static ISO 3166-1 alpha-2 country dataset as a single frozen TypeScript constant (COUNTRIES_DATA). This…
countries — (no submodules)- errors — (no submodules) - locale-data-error — (no submodules)- languages — (no submodules) - languages.data — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: LANGUAGES_DATA (130+ language entr…
- languages — (no submodules)- types — (no submodules) - types — (no submodules)

Install

bun add @suaveplan/locale-data

Quick Start

import { getCountry, getLanguage, isRtlLanguage } from "@suaveplan/locale-data";

// Country lookup
const us = getCountry("US");
console.log(us.name);      // "United States"
console.log(us.phone);     // "1"
console.log(us.emoji);     // "🇺🇸"

// Language lookup
const ar = getLanguage("ar");
console.log(ar.name);      // "Arabic"
console.log(ar.native);    // "العربية"

// RTL detection
console.log(isRtlLanguage("ar"));    // true
console.log(isRtlLanguage("ar-SA")); // true (BCP-47 tag)
console.log(isRtlLanguage("en"));    // false

Modules

Subpath	Description
`@suaveplan/locale-data`	Root barrel — re-exports all public symbols
`@suaveplan/locale-data/countries`	Country lookups + Zod schemas
`@suaveplan/locale-data/languages`	Language lookups + RTL detection + Zod schemas
`@suaveplan/locale-data/errors`	`LocaleDataError` + `LOCALE_DATA_CODES`

Modules Documentation

countries.md — getCountry, getAllCountries, getCountriesByContinent, getCountriesByCurrency
countries.data.md — Static ISO 3166-1 dataset (209 entries)
languages.md — getLanguage, getLanguages, getRtlLanguages, isRtlLanguage
languages.data.md — Static ISO 639-1 dataset + RTL codes
locale-data-error.md — LocaleDataError, LOCALE_DATA_CODES
types.md — CountryItemSchema, LanguageItemSchema

API Overview

Countries

import {
  getCountry,           // O(1) lookup by ISO 3166-1 alpha-2 code
  getAllCountries,       // Returns full 209-entry Record<string, CountryItem>
  getCountriesByContinent, // Filter by continent code ("EU", "AS", "AF", etc.)
  getCountriesByCurrency,  // Filter by ISO 4217 currency code (e.g. "EUR")
} from "@suaveplan/locale-data/countries";

Languages

import {
  getLanguage,     // O(1) lookup by ISO 639-1 code
  getLanguages,    // Returns full 130+ entry Record<string, LanguageItem>
  getRtlLanguages, // Returns list of RTL language codes
  isRtlLanguage,   // BCP-47 aware RTL detection
} from "@suaveplan/locale-data/languages";

Error Handling

import { LocaleDataError, LOCALE_DATA_CODES } from "@suaveplan/locale-data/errors";

try {
  getCountry("ZZ");
} catch (err) {
  if (err instanceof LocaleDataError) {
    console.log(err.code); // "LOCALE_DATA/COUNTRY.NOT_FOUND"
  }
}

OTel Instrumentation

The package emits two OTel counters:

Metric	Attributes
`locale_data.country.lookups`	`result: "found" \| "not_found"`
`locale_data.language.lookups`	`result: "found" \| "not_found"`