suaveplan/openspec/specs/locale-data/spec.md

Spec: @suaveplan/locale-data

Package: @suaveplan/locale-data
Domain: universal/i18n/locale-data
Version: 0.1.0
Status: Published

Overview

Static ISO 3166-1 country data (209 entries) and ISO 639-1 language data (130+ entries) with typed lookup functions, OTel instrumentation, and Zod schemas.

Requirements

Countries

• getCountry(code: string): CountryItem — O(1) lookup; throws LocaleDataError(COUNTRY.NOT_FOUND) for unknown codes.
• getAllCountries(): Record<string, CountryItem> — returns same reference each call.
• getCountriesByContinent(continent: string): CountryItem[] — filters by 2-letter continent code.
• getCountriesByCurrency(currency: string): CountryItem[] — splits comma-separated currency fields.
• OTel counter: locale_data.country.lookups with result: "found" | "not_found".

Languages

• getLanguages(): Record<string, LanguageItem> — returns same reference each call.
• getLanguage(code: string): LanguageItem — O(1) lookup; throws LocaleDataError(LANGUAGE.NOT_FOUND).
• getRtlLanguages(): readonly string[] — returns RTL language code list.
• isRtlLanguage(code: string): boolean — BCP-47 aware; strips subtags before checking.
• OTel counter: locale_data.language.lookups with result: "found" | "not_found".

Errors

• LOCALE_DATA_CODES — defineCodes("LOCALE_DATA", ["COUNTRY.NOT_FOUND", "LANGUAGE.NOT_FOUND"]).
• LocaleDataError extends SuaveplanError<LocaleDataCode>.

Types / Schemas

• CountryItemSchema (Zod) — 9 fields: name, native, phone, continent, capital, currency, languages[], emoji, emojiU.
• LanguageItemSchema (Zod) — 2 fields: name, native.
• CountryCodeSchema — z.string().length(2).toUpperCase().
• LanguageCodeSchema — z.string().min(2).max(3).toLowerCase().

Data Coverage

• Countries: 209 ISO 3166-1 alpha-2 entries, 7 continent codes.
• Languages: 130+ ISO 639-1 entries, 15 RTL codes (ar, az, ba, dv, fa, he, iu, ks, ku, ps, sd, sr, tg, ur, yi).

Quality Gates

• 100% Istanbul coverage (all 4 thresholds)
• 100% docs coverage (6/6 implementation files)
• Biome lint clean
• TypeScript clean