# 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