suaveplan/openspec/archive/2026-04-20-enterprise-locale-data/proposal.md

Proposal: @suaveplan/locale-data

Summary

Add the @suaveplan/locale-data package — a static, enterprise-grade locale data library providing ISO 3166-1 country data and ISO 639-1 language data with typed lookup functions, OTel instrumentation, and Zod schema validation.

Motivation

Multiple packages across the monorepo need reliable country and language data (e.g., @suaveplan/i18n, @suaveplan/domain-normalizer, future address-validation packages). Centralising this static data eliminates duplicated definitions and guarantees a single source of truth for ISO codes, native names, continents, currencies, and RTL language detection.

Scope

• countries module: 209 ISO 3166-1 alpha-2 country entries with name, native name, phone code, continent, capital, currency, languages, and emoji. Lookup functions: getCountry, getAllCountries, getCountriesByContinent, getCountriesByCurrency.
• languages module: ~130 ISO 639-1 language entries with name and native name, plus RTL detection. Lookup functions: getLanguage, getLanguages, getRtlLanguages, isRtlLanguage.
• errors: Typed LocaleDataError extending SuaveplanError with stable code registry.
• types: Shared CountryItem and LanguageItem Zod schemas and inferred types.
• OTel: Counters on country/language lookup hits and misses.

Out of scope

• CLDR data (plural rules, formatting patterns) — covered by @suaveplan/i18n
• Flag images / SVG assets
• UN M.49 region codes