---
title: "Locale formatting and direction"
description: "Format values locally and use locale-correct plural rules and text direction."
canonical_url: "https://docs.linguana.dev/docs/reference/formatting"
markdown_url: "https://docs.linguana.dev/docs/reference/formatting.md"
x_farming_labs_generated_preamble: true
agent:
  task: "Add locale-bound Intl formatting and root direction."
  outcome: "Values, direction, and hydration follow the active locale."
  prerequisites:
    - "An existing Linguana provider or core client."
  files:
    - "The application locale integration and selected public API field allowlist."
  verification:
    - "German currency, Arabic plurals, UTC hydration, and missing catalog fallback render correctly."
  rollback:
    - "Keep the current release and use original source fallback."
  failureModes:
    - symptom: "A translation is missing."
      resolution: "Inspect the saved version and release; keep source text visible. Do not publish without explicit authorization."
---

# Locale formatting and direction
URL: /docs/reference/formatting
LLM index: /llms.txt
Description: Format values locally and use locale-correct plural rules and text direction.

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Add locale-bound Intl formatting and root direction.
Outcome: Values, direction, and hydration follow the active locale.

### Prerequisites

- An existing Linguana provider or core client.

### Files

- `The application locale integration and selected public API field allowlist.`

### Verification

- German currency, Arabic plurals, UTC hydration, and missing catalog fallback render correctly.

### Rollback

- Keep the current release and use original source fallback.

### Failure Modes

- A translation is missing. — Recovery: Inspect the saved version and release; keep source text visible. Do not publish without explicit authorization.
<!-- farming-labs:agent-contract:end -->

# Locale formatting and direction

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

```ts
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.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).