123 lines
8.2 KiB
Markdown
123 lines
8.2 KiB
Markdown
# @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"` |
|
|
|