API reference

(translations: LocaleTranslations, locale: LocaleCode, options?: {onWarning?, onError?, onMissingKey?}) => TranslateFunction. Pure. A miss returns the raw key and calls onMissingKey({key, locale}); invalid path, invalid value and failed plural selection call onWarning(message, {key, locale}); an exception calls onError(message, {key, locale, error}). Every failure returns the raw key

(missing: MissingTranslationKey) => void: the optional observer of a key the tree does not carry. It observes; the result stays the raw key

{readonly key: string; readonly locale: LocaleCode}

TranslationCapability<PlainKey extends string = string, Params = Record<string, variables | undefined>>: (key: PlainKey): string and <K extends keyof Params & string>(key: K, variables): string, where variables must satisfy EVERY key in K (the intersection of their variables, so a key union cannot compile with the variables of one member). The canonical translation contract; a host instantiates it with its own key types

TranslationCapability with its defaults: any string key, optionally with a variables bag {count?: number; [name: string]: string | number | undefined}

Record<string, Record<string, unknown>>: the translation tree keyed by namespace

{code: string; label: string; flag?: string; direction?: 'ltr' | 'rtl'}: one entry of the provider's supportedLanguages. Nothing in this package reads flag, and no language UI may show a flag

(requested: string, supportedLocales: readonly string[]) => string | undefined. The request is canonicalised (malformed: undefined); the exact canonical tag wins, then the request is truncated one subtag at a time (zh-Hant-TW → zh-Hant → zh). Never more specific: pt does not reach pt-BR. The set must be canonical

(requested: readonly string[], supportedLocales: readonly string[]) => string | undefined. The first request of a priority list that lookupSupportedLocale answers; each request is truncated before the next is tried (['de-CH', 'fr'] against de, fr gives de). undefined for an empty list or no hit

(languageCode: LocaleCode, displayLocale: LocaleCode, knownLabels?: KnownLanguageLabels) => string. The in-sentence name from Intl.DisplayNames in the display language; where Intl gives no name (it cannot be constructed, or answers with the code), the host's label for that code from knownLabels, then the upper-case code. Never empty (D28)

Same signature. The standalone-label form: the first grapheme cluster upper-cased with the display language's casing rules, for a list of names from different languages

readonly Pick<LanguageConfig, 'code' | 'label'>[]: host labels, used only when Intl gives no name

(source: string) => I18nLogger. The host's logger factory: the runtime asks it once per part for active-i18n/client, /server, /loader or /metadata. A factory such as active-logging's createLogger fits as it is (D7, D28)

{warn(message, meta?), error(message, meta?)}: stable English messages, context in meta

(currencyCode: string, displayLocale: LocaleCode) => string. The currency name from Intl.DisplayNames (type: 'currency') in the display language; falls back to the code itself. Never empty

(regionCode: string, displayLocale: LocaleCode) => string. The region (country) name from Intl.DisplayNames (type: 'region') in the display language; falls back to the code itself. Never empty for a non-empty code

Same signature. The choice label CODE - name (hyphen, never an em-dash), or the bare code when the runtime does not know the name. Resolve it on the server for any server-rendered text: server and browser ICU data may differ

(codes: readonly string[], displayLocale: LocaleCode, config?: CurrencyOptionsConfig) => CurrencyOption[]. The options of a currency picker in display order: config.priorityCodes first, as given and unpruned (deduplicated), then every other code of codes sorted by its name with Intl.Collator(displayLocale). config.current ({code, name?}, the value a record carries) is kept at the front when it is in neither list, and its name, resolved on the server, replaces the local one. Names come from getCurrencyName (the code when unknown). The universe of codes is the caller's; nothing is derived from a language or a country and no default is chosen. Fits CurrencyCombobox.options in active-ui

{code, name}; {priorityCodes?, current?: {code, name?}}

(source: TranslationSource, options: ServerTranslatorOptions) => ServerTranslations. Binds the server runtime to one host source and the host's values. Call once per source at module scope; the loader cache belongs to the returned instance and is on when NODE_ENV is production at creation. Throws for an empty language set, an entry that is not a well-formed and canonical BCP 47 tag or that is listed twice, and a fallback that is not spelled as one of the entries (D29). options.onMissingKey is the host's one server installation of missing-key observability

{getServerTranslations, getServerTranslator, createServerTranslator, getTranslatedMetadata}, described below

{readonly supportedLocales: readonly string[]; readonly fallbackLocale: string; readonly onMissingKey?: MissingKeyCallback; readonly logger?: I18nLoggerFactory}. The language set and fallback are required (D28); every entry is a canonical BCP 47 tag (en-GB, pt-BR, zh-Hant), and the fallback is one of them (D29); without onMissingKey a miss is not reported, without logger nothing is

{readonly namespaces: readonly string[]; importNamespace(locale, namespace): Promise<{readonly default: unknown}>}. Every namespace is imported per locale; MODULE_NOT_FOUND is skipped silently, any other failure with a warning; an empty bundle is left out

{preferredLocale: string; descriptionKey?: string; additionalMetadata?: Partial<Metadata>}

From @workspace/active-i18n/server/get-locale, not from the barrel: it reads the request (next/headers), and the barrel is the runtime a request-free worker may load. () => Promise<string[]>. The Accept-Language request header as canonical BCP 47 tags with region and script kept (pt-BR, zh-Hant-TW), quality descending and header order for equal quality, unfiltered against any language set and never truncated (D33). Whitespace around ; and = is allowed and only q counts; dropped are an invalid qvalue (outside 0 to 1 or more than three decimals), q=0, * and a tag Intl refuses (en_US); a repeated tag keeps its highest quality; at most 32 entries are read. A list of positive preferences only: it carries no exclusion and no default. For anonymous surfaces only; the host matches it, for example with lookupFirstSupportedLocale

(locale: string) => Promise<{translations, locale}>. Loads every namespace in the entry of the host's supportedLocales that answers the given locale (D29: the request is canonicalised; the exact tag wins; only then the same tag with subtags removed from the end, so en-US reaches en but never en-GB, and pt never reaches pt-BR), otherwise in the host's fallbackLocale with a warning. A malformed locale takes the fallback path too. The returned locale is the entry as the host spelled it. A load failure yields an empty tree and an error report

(locale: string) => Promise<{t, locale, translations}>. Same loading; t comes from createServerTranslator

(translations, locale) => TranslateFunction. The one server translator constructor of the instance: server-side onWarning/onError logging and the host's onMissingKey. A host binding that types keys binds to it

(titleKey: string, options: TranslatedMetadataOptions) => Promise<Metadata>. Translated title, optional description, then additionalMetadata merged last. A missing key renders as the raw key, like every translation, and is reported through onMissingKey only; a load failure logs an error

Props I18nProviderProps. Distributes the translator for one server-resolved locale, wired to the active-i18n/client logger of the host's factory when given

{children; locale; translations: LocaleTranslations; supportedLanguages: readonly LanguageConfig[]; allowLocaleSwitching?: boolean (default true); persistLocale?: (locale) => void | PromiseLike<void>; confirmLocaleSwitch?: (locale) => boolean | PromiseLike<boolean>; logger?: I18nLoggerFactory}. Without persistLocale the provider touches no storage; it never builds a cookie itself (D28). persistLocale may be synchronous or return any PromiseLike (native promise, object or callable thenable, assimilated like Promise.resolve); the switch navigates only after it returned or its promise fulfilled (D31, D32). confirmLocaleSwitch is the host's guard for leaving the page, asked before anything is stored; anything other than true, a throw or a rejection resolves 'declined' (D32). A logger that throws never changes an outcome (D32)

{locale; t; translations; setLocale(newLocale): Promise<LocaleSwitchOutcome>; availableLocales; availableLanguages; allowLocaleSwitching; getLanguage(code); currentLanguage}. Public as the return type of useI18n, so a caller can name what the hook returns; no workspace consumer uses either today (I18N-FINAL-015)

() => I18nContextValue. Throws outside <I18nProvider>

() => TranslateFunction. Throws outside the provider

() => LocaleCode. Throws outside the provider

() => {locale, setLocale, availableLocales, availableLanguages, allowLocaleSwitching, currentLanguage, getLanguage}. setLocale matches the request canonically against the offered codes and resolves to a LocaleSwitchOutcome; it never throws and the promise never rejects (D32). Order: confirmLocaleSwitch (when given), persistLocale (when given), then <html lang> and a full navigation; the outcome of the navigation comes from the browser's beforeunload ('switched' without an objection, 'navigation-guarded' with one, 'navigation-failed' when starting it threw). Every outcome except 'switched' and 'pending' leaves the page consistent and accepts a new choice. One switch at a time per provider: a further valid choice while one is being decided, stored or navigated resolves 'pending' (D31)

'switched' | 'disabled' | 'unchanged' | 'unavailable' | 'pending' | 'declined' | 'persist-failed' | 'navigation-failed' | 'navigation-guarded': how a setLocale() call ended. Only 'switched' leaves the page. 'navigation-failed' and 'navigation-guarded' mean the choice IS stored but this page stays, with <html lang> on its own language; choosing the shown language again stores it again (D31, D32)

Props {profile: PresentationProfileConfig | null; children}. Distributes the owner's profile; null means "no configured profile"

() => PresentationContext. Composes provider locale, profile and time zone; pass it as the presentation argument of any formatter. Without profile and zone it behaves like the bare locale. The surface's zone is its timeZone field

Props {value; children}, where value is a state built with fixedTimeZone or viewerTimeZone. Distributes the surface's time-zone state

() => IanaTimeZone. The surface's resolved zone, for a calendar-day question (todayIsoDate, calendarDayOf); throws when the surface has no resolved zone (D15)

(timeZone: IanaTimeZone): the state of a surface whose host determined the zone. Pure; callable from a Server Component

(timeZone: IanaTimeZone | null | undefined): the state of a viewer-owned surface, resolved or unresolved. Pure

() => IanaTimeZone | null. The browser's reported zone, or null

() => {currency(value: MonetaryAmount, options?); number(value, format?: NumberFormat); fractionAsPercent(value, preset?: PercentFormat); percentagePoints(value, preset?: PercentFormat); date(value, preset?: DatePreset); dateOnly(value, preset?: DateOnlyPreset); dateTime(value, preset?: DatePreset)}. The formatters bound to usePresentation(); no relative-time helper (D18)

Props {value: Date | string | number | null | undefined; fallback: string; absoluteLabel?: (absoluteText: string) => string; options?: {absolutePreset?; now?; thresholdDays?}; phrase?: (recency: string) => string; className?: string}. Relative text within the recency threshold, absolute beyond it, with the canonical instant in <time dateTime> and a reachable absolute reading. The server and the hydrating render show the absolute reading; the policy applies once mounted (D18). The absolute reading uses the surface zone: mount it under a resolved <TimeZoneProvider>, because without one the server and the browser each read their own zone and the hydrating text can differ. phrase embeds the <time> in a translated sentence: it receives a stand-in and returns the translation with that stand-in interpolated exactly once (it throws otherwise). Not for the displayed value of a sortable or filterable date column

Props {value: string; preset?: DatePreset; fallback: string; className?: string}. An instant on a viewer-owned surface, read in the viewer's zone; renders directly when the provider's viewer zone is resolved, otherwise after browser detection. Never on a surface with an administration or system owner