Initial Commit

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

@@ -0,0 +1,31 @@
+# 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