107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# @suaveplan/i18n-formatter-display-name - Intl.DisplayNames wrapper for the @suaveplan/i18n family — locale-aware language/region/script/currency/calendar display names. Per-(locale, type, style, fallback) cache, Zod-validated options, OTel histogram + cache-hit counter, structured I18nError mapping. Universal leaf package.
|
|
|
|
## Summary
|
|
|
|
Wrapper around `Intl.DisplayNames` for the `@suaveplan/i18n` family —
|
|
locale-aware language, region, script, currency, and calendar display
|
|
names. Universal leaf package; depends only on
|
|
`@suaveplan/i18n-shared`, `@suaveplan/types`, `@suaveplan/error`,
|
|
`@opentelemetry/api`, and `zod`.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [formatter](./src/formatter/formatter.md) — `DisplayNameFormatter` and the `formatDisplayName` standalone helper expose `Intl.DisplayNames` for the `@suaveplan/i18…
|
|
- [formatter](./src/formatter/formatter.md) — `DisplayNameFormatter` and the `formatDisplayName` standalone helper expose `Intl.DisplayNames` for the `@suaveplan/i18…
|
|
- [helpers](./src/helpers/helpers.md) — The five ergonomic helpers (`formatLanguageName`, `formatRegionName`, `formatCurrencyName`, `formatScriptName`, `format…
|
|
- [helpers](./src/helpers/helpers.md) — The five ergonomic helpers (`formatLanguageName`, `formatRegionName`, `formatCurrencyName`, `formatScriptName`, `format…
|
|
- [observability](./src/observability/observability.md) — The DisplayName formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance te…
|
|
- [observability](./src/observability/observability.md) — The DisplayName formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance te…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Why this exists
|
|
|
|
The 14-package i18n modular split (cross-cutting design
|
|
`2026-05-05-i18n-modular-split.md`) lifts each `Intl.*` wrapper out of
|
|
the monolith into its own sibling package. Lifting the display-name
|
|
helper out of `@suaveplan/i18n` lets consumers that only need
|
|
country-name / currency-name rendering pull a single small package
|
|
instead of the entire i18n core.
|
|
|
|
The package adds the canonical Wave-3 formatter shape on top of the
|
|
monolith's standalone helper: Zod-validated options, a per-(locale,
|
|
type, style, fallback) cache, OTel histogram + cache-hit counter, the
|
|
class wrapper for symmetry with `NumberFormatter` /
|
|
`RelativeTimeFormatter` / `ListFormatter` / `DateFormatter`, and five
|
|
ergonomic helpers that pre-bind `formatDisplayName` with each
|
|
canonical `type` value.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/i18n-formatter-display-name
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```ts
|
|
import {
|
|
DisplayNameFormatter,
|
|
formatDisplayName,
|
|
formatLanguageName,
|
|
formatRegionName,
|
|
formatCurrencyName,
|
|
} from "@suaveplan/i18n-formatter-display-name";
|
|
|
|
formatDisplayName("GB", "en-GB", { type: "region" }); // "United Kingdom"
|
|
formatLanguageName("fr", "en-GB"); // "French"
|
|
formatRegionName("US", "en-GB"); // "United States"
|
|
formatCurrencyName("USD", "en-GB"); // "US Dollar"
|
|
|
|
const f = new DisplayNameFormatter({ type: "region", style: "short" });
|
|
f.format("DE", "en-GB"); // "Germany"
|
|
```
|
|
|
|
## Modules
|
|
|
|
| Subpath | Description |
|
|
|---|---|
|
|
| `@suaveplan/i18n-formatter-display-name` | Root barrel — class + standalones + helpers + observability |
|
|
| `@suaveplan/i18n-formatter-display-name/formatter` | `DisplayNameFormatter`, `formatDisplayName`, types, schema |
|
|
| `@suaveplan/i18n-formatter-display-name/helpers` | Five ergonomic helpers — `formatLanguageName`, `formatRegionName`, `formatCurrencyName`, `formatScriptName`, `formatCalendarName` |
|
|
|
|
## Modules Documentation
|
|
|
|
- [formatter.md](src/formatter.md) — `DisplayNameFormatter` class, `formatDisplayName`, `clearDisplayNameCache`
|
|
- [helpers.md](src/helpers.md) — five ergonomic helpers
|
|
- [observability.md](src/observability.md) — OTel histogram + cache-hit counter
|
|
|
|
## Public Surface (snapshot)
|
|
|
|
| Export | Kind | Origin |
|
|
|---|---|---|
|
|
| `DisplayNameFormatter` | class | `formatter.ts` |
|
|
| `formatDisplayName` | function | `formatter.ts` |
|
|
| `clearDisplayNameCache` | function | `formatter.ts` |
|
|
| `DisplayNameFormatterOptionsSchema` | Zod schema | `formatter.schemas.ts` |
|
|
| `DisplayNameFormatterOptions` | type | `formatter.types.ts` |
|
|
| `DisplayNameType` | type | `formatter.types.ts` |
|
|
| `DisplayNameStyle` | type | `formatter.types.ts` |
|
|
| `DisplayNameFallback` | type | `formatter.types.ts` |
|
|
| `DisplayNameFormatterCacheKey` | type | `formatter.types.ts` |
|
|
| `formatLanguageName` | function | `helpers.ts` |
|
|
| `formatRegionName` | function | `helpers.ts` |
|
|
| `formatCurrencyName` | function | `helpers.ts` |
|
|
| `formatScriptName` | function | `helpers.ts` |
|
|
| `formatCalendarName` | function | `helpers.ts` |
|
|
| `recordDisplayNameFormat` | function | `observability.ts` |
|
|
| `recordDisplayNameCacheHit` | function | `observability.ts` |
|
|
| `getDisplayNameMetricsState` | function | `observability.ts` |
|
|
| `resetDisplayNameMetricsState` | function | `observability.ts` |
|
|
|
|
## Versioning
|
|
|
|
Part of the 14-package i18n modular-split rollout. Stays at `0.1.0`
|
|
until the slim core (Wave 6) cuts the family `1.0.0` release.
|
|
|