Locale formatting and direction

Formatting uses native Intl APIs locally. It makes no network requests, needs no translation catalog, and incurs no translation charge.

import { createFormatters, getLocaleAttributes } from "@linguanahq/core";

const de = createFormatters({ locale: "de-DE", timeZone: "UTC" });
de.formatNumber(1234.5);
de.formatCurrency(1234.5, "EUR");
de.formatDateTime(new Date("2026-10-04T12:00:00Z"));
de.formatRelativeTime(-1, "day", { numeric: "auto" });
de.formatList(["Ada", "Lin", "Sam"]);
de.selectPlural(3);
getLocaleAttributes("ar"); // { lang: "ar", dir: "rtl" }

Numbers and currencies accept number or bigint, plus native Intl.NumberFormatOptions. Currency is mandatory and never inferred or converted. Dates accept a Date or epoch milliseconds, plus Intl.DateTimeFormatOptions. Relative times accept a value, unit, and Intl.RelativeTimeFormatOptions. Lists accept string arrays and Intl.ListFormatOptions. Plural selection accepts a number and Intl.PluralRulesOptions, including ordinal rules.

formatNumberToParts, formatCurrencyToParts, formatDateTimeToParts, formatRelativeTimeToParts, and formatListToParts expose native parts. Invalid locale, time-zone, or formatting configuration throws FormattingError with code INVALID_FORMAT_OPTIONS.

Framework helpers

React exposes useFormatters(). Vue and Solid expose a reactive computed ref/accessor from useFormatters(). Svelte exposes a readable store from getFormatters(). Framework-neutral clients expose getFormatters().

Time zone defaults to UTC. Configure timeZone on the locale provider/client. Hydration state preserves it; server and browser must use the same locale and time zone on the first render. Date strings are deliberately not parsed by the formatter.

Framework providers manage document lang and dir by default. Set manageDocumentLocale: false when the host owns those attributes, or provide localeRoot for a scoped subtree. Nested providers do not take ownership from the document provider. On the server, use getLocaleAttributes(locale) when rendering the root element.

Changing to an enabled language updates formatting and direction even if its catalog cannot be loaded. Source text remains the translation fallback.

ICU sentences

Keep full sentences in t() or compiler-extracted ICU messages. Variables remain local. Translation validation preserves variable roles, named slots, select branches, plural offsets, explicit numeric selectors, and meaning-bearing number formats. Target languages may use different plural categories: Arabic can add zero, two, few, and many; other remains required.

Glossary violations and structural failures block publication. Extreme length expansion is a visible advisory warning.