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

Documentation tree

formatter — DisplayNameFormatter and the formatDisplayName standalone helper expose Intl.DisplayNames for the `@suaveplan/i18…
- formatter — DisplayNameFormatter and the formatDisplayName standalone helper expose Intl.DisplayNames for the `@suaveplan/i18…
helpers — The five ergonomic helpers (formatLanguageName, formatRegionName, formatCurrencyName, formatScriptName, `format…
- helpers — The five ergonomic helpers (formatLanguageName, formatRegionName, formatCurrencyName, formatScriptName, `format…
observability — The DisplayName formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance te…
- observability — The DisplayName formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance te…

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

bun add @suaveplan/i18n-formatter-display-name

Quick Start

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 — DisplayNameFormatter class, formatDisplayName, clearDisplayNameCache
helpers.md — five ergonomic helpers
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.