first commit
This commit is contained in:
122
docs/localization/i18n/locale-data/README.md
Normal file
122
docs/localization/i18n/locale-data/README.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# @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"` |
|
||||
|
||||
Reference in New Issue
Block a user