Locale Provider
June 2026
- Apple
- Fig
- Pear
Sets the locale, writing direction, and message overrides for everything
inside it. Components read their default labels and their formatting locale
from this context, so you localize once instead of passing a prop to every
component. The wrapper carries both lang and dir: assistive technologies
get the right language rules, and the CSS logical properties flip for RTL.
Import
Section titled “Import”<script> import LocaleProvider from "@invisible-ui/svelte/LocaleProvider.svelte";</script><script setup> import { LocaleProvider } from "@invisible-ui/vue";</script>import { LocaleProvider } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-locale-provider></ds-locale-provider>| Prop | Type | Default | Description |
|---|---|---|---|
locale | string | undefined | undefined | BCP-47 locale tag. Defaults to the locale around the provider: an outer provider's, else the page's lang, else the international default. |
dir | Dir | undefined | undefined | Explicit writing direction; when omitted it derives from the locale. |
messages | Messages | {} | Overrides merged over the English catalog. |
inline | boolean | false | Render without the wrapping element (you manage dir). |
| Prop | Type | Default | Description |
|---|---|---|---|
locale | string | undefined | BCP-47 locale tag. Defaults to "en". |
dir | Dir | undefined | Writing direction. Defaults to "ltr"; rendered as a dir attribute. |
messages | Messages | undefined | Message overrides, merged over the English catalog. |
Slots: default.
| Prop | Type | Default | Description |
|---|---|---|---|
locale | string | — | BCP-47 locale tag. Defaults to "en". |
dir | Dir | — | Writing direction. Defaults to "ltr"; rendered as a dir attribute. |
messages | Messages | — | Message overrides, merged over the English catalog. |
children | ReactNode | — |
| Attribute | Reactive | Description |
|---|---|---|
locale | yes | BCP-47 tag; without it, the language around the provider, then English |
dir | yes | ltr or rtl; derived from the locale when omitted |
Reactive attributes re-render the element when they change after the first render.
Properties: locale (the resolved tag), messages (overrides keyed by catalog key: plain strings, or plural objects for count messages).
Any label prop you pass to a component still wins over the catalog. Default
strings live in the English catalog (en); see MessageKey for the keys.
Behavior
Section titled “Behavior”-
Precedence: an explicit component prop (for example Calendar’s
locale) wins over the provider; the provider wins over the page’slang; the page’slangwins over the international default (see Default locale). A provider withoutlocaletakes the locale around it: an outer provider’s, else the page’s. The library never formats with the browser’s own language. -
Locale tags are canonicalized (
IT-itbecomesit-IT). A malformed tag logs a warning and falls back to the default. -
Direction: pass
dirto force it; without it, the direction derives from the locale (ar,he,fa, … becomertl). Overlays that render in a portal keep the scope’slang, and take the direction of the control that opens them, so adiron a plain wrapper around the control counts too. -
Plural messages: a count message can be overridden with an object of CLDR plural categories, selected by the locale —
otheris required:<LocaleProviderlocale="ru"messages={{"searchDialog.results": {one: "{count} результат",few: "{count} результата",other: "{count} результатов",},}}><SearchDialog items={people} /></LocaleProvider> -
Nesting: a nested provider overrides only its subtree.
-
Changing the locale after mount updates labels and formatting in place: no remount, and no loss of focus, drafts, or values.
Default locale
Section titled “Default locale”When the app gives no locale (no provider, or a provider without locale),
the components read the page:
- The page’s language: the
langattribute of the closest ancestor (Elements) or of the document element (<html lang>, Svelte, Vue and React). Without a provider, the direction is the page’sdirattribute, elseltr, the direction the browser renders. A change of<html lang>or<html dir>at runtime applies in place. - Otherwise, the international conventions of ISO 8601 and of CLDR’s
world region (
001): the week starts on Monday, time uses the 24-hour clock, and a numeric date (dateStyle: "short") reads year-month-day,2026-01-05. The locale tag isen-001-u-hc-h23(DEFAULT_LOCALEin core). It changes conventions, not language: messages stay in the catalog’s English.
Each adapter resolves the locale with the same core functions
(resolveLocale, pageLocale), and the shared vectors in
core/src/i18n/__vectors__/default-locale.json hold the cases that Flutter
answers too.
Server rendering. The server cannot read the page, so it renders with the
international default. To render the page’s language on the server, pass the
same value to the provider’s locale that the page carries in <html lang>;
server and browser then agree from the first render. Without it, the browser
renders the first pass with the international default, exactly as the server
did, so hydration never meets a mismatch; once the component is mounted it
switches to the page’s lang and renders again. React reads the page through
useSyncExternalStore, which renders the server value during hydration and
the page’s right after, and reads the page at once in an app without server
rendering. Svelte and Vue apply the page when each component mounts, with or
without server rendering. Elements render in the browser only and read the
page at once.
Installation presets or setup wizards that preselect a country or a skin are outside the base design system. They could live in a separate, optional preset package.
Supported scope
Section titled “Supported scope”- Dates format on the Gregorian calendar in every locale; other calendar systems are not supported.
- Calendar’s week start follows the resolved locale’s first day of the week
(CLDR, language and region) unless you set
weekStartsOn. - Time Field’s hour cycle follows the resolved locale unless you set
hourCycle. - The library ships English defaults only: translations are yours via
messages. Component search filters match case-insensitively without locale-specific case rules; pass your ownfilterwhere you need them.
Example
Section titled “Example”<LocaleProvider locale="it" messages={{ "calendar.today": "Oggi" }}> <Calendar /></LocaleProvider>In Elements:
<ds-locale-provider locale="it"> <ds-search-field label="Cerca"></ds-search-field> <ds-dialog heading="Impostazioni"></ds-dialog></ds-locale-provider>
<script type="module"> document.querySelector("ds-locale-provider").messages = { "searchField.clear": "Cancella la ricerca", "searchField.submit": "Cerca", "dialog.close": "Chiudi", };</script>locale and dir are attributes; messages is a property. The provider
writes lang and dir on itself. An element reads the closest
ds-locale-provider; without one, it reads the closest lang attribute, then
the international default. Changing locale, dir or messages renders the labels of every
element inside again. A label attribute on an element, such as clear-label,
still wins over the catalog.