# @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.

<!-- begin:auto-docs -->
## Documentation tree

- [countries](./src/countries/countries.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [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](./src/countries/countries.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [errors](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [locale-data-error](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [languages.data](./src/languages/languages.data.md) — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: `LANGUAGES_DATA` (130+ language entr…
  - [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [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](./src/countries/countries.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [locale-data-error](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_- [languages.data](./src/languages/languages.data.md) — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: `LANGUAGES_DATA` (130+ language entr…
  - [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(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](./src/countries/countries.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [locale-data-error](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_- [languages.data](./src/languages/languages.data.md) — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: `LANGUAGES_DATA` (130+ language entr…
  - [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(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](./src/countries/countries.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [locale-data-error](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_- [languages.data](./src/languages/languages.data.md) — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: `LANGUAGES_DATA` (130+ language entr…
  - [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(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](./src/countries/countries.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_  - [locale-data-error](./src/errors/locale-data-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_  - [languages.data](./src/languages/languages.data.md) — Contains the static ISO 639-1 language dataset as two frozen TypeScript constants: `LANGUAGES_DATA` (130+ language entr…
  - [languages](./src/languages/languages.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_
## Install

```bash
bun add @suaveplan/locale-data
```

## Quick Start

```ts
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](src/countries/countries.md) — `getCountry`, `getAllCountries`, `getCountriesByContinent`, `getCountriesByCurrency`
- [countries.data.md](src/countries/countries.data.md) — Static ISO 3166-1 dataset (209 entries)
- [languages.md](src/languages/languages.md) — `getLanguage`, `getLanguages`, `getRtlLanguages`, `isRtlLanguage`
- [languages.data.md](src/languages/languages.data.md) — Static ISO 639-1 dataset + RTL codes
- [locale-data-error.md](src/errors/locale-data-error.md) — `LocaleDataError`, `LOCALE_DATA_CODES`
- [types.md](src/types/types.md) — `CountryItemSchema`, `LanguageItemSchema`

## API Overview

### Countries

```ts
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

```ts
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

```ts
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"` |