---
title: Localization
description: Locale, direction, and translatable component text through MoraineProvider.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Localization

> Locale, direction, and translatable component text through MoraineProvider.

Moraine components ship with English accessible names and placeholders and parse numbers by locale. Without a `MoraineProvider`, `locale` is `en-US`. A root provider follows the browser after hydration (`detectLocale` defaults to `true`); SSR and the first client render stay `en-US`. Add a provider to replace the copy, pin a BCP 47 locale such as `zh-CN`, disable detection with `detectLocale={false}`, or override the direction. Nest a provider to override part of the tree.

## Provider props

| Prop           | Omitted                                                               | Set                                                                                                                                                                                                                                           |
| :------------- | :-------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locale`       | Inherits the parent locale, or `en-US` without a provider.            | Replaces it with a BCP 47 tag such as `de-DE` or `zh-CN`. Always wins over `detectLocale`.                                                                                                                                                    |
| `detectLocale` | `true` on the root provider; nested providers inherit the parent tag. | After hydration, follow `navigator.language` and `languagechange`. SSR and the first client render stay `en-US`. `false` disables detection: the root stays `en-US`, a nested provider inherits the parent tag. Ignored when `locale` is set. |
| `dir`          | Inherits the parent direction, or `<html dir>` / the document.        | Replaces it with `ltr` or `rtl`, or `null` to clear back to document detection.                                                                                                                                                               |
| `messages`     | Inherits parent messages.                                             | Deep-merges partial message overrides over the parent. Default copy is English.                                                                                                                                                               |

Set `lang` and `dir` on `<html>` for document language and CSS/layout. Pass the same `dir` to `MoraineProvider` when portaled overlays should copy it onto their content. A component's own `dir` attribute always wins over the provider, and the provider wins over `<html dir>`.

`locale` is shared application locale context. `NumberInput` uses it for `Intl.NumberFormat` parsing and formatting, and `Slider`, `BoldSlider`, and `Progress` use it to format displayed values. Collection search, typeahead, and `CommandPalette` filtering use `Intl.Collator`. `NumberInput` reads its own `locale` prop first, then the provider, then `en-US`. Invalid locale tags fall back to `en-US` for both `Intl.NumberFormat` and `Intl.Collator`.

In production, pass an explicit `locale` from a cookie or `Accept-Language` so formatted values do not flash from `en-US` to the browser language after hydration.

```tsx title="src/App.tsx"
import { MoraineProvider } from 'moraine'
import type { MoraineProviderProps } from 'moraine'

const zhCN = {
  dialog: { close: '关闭', ok: '确定', cancel: '取消' },
  pagination: {
    label: '分页',
    status: ({ page, total }) => `第 ${page} 页，共 ${total} 页`,
    page: ({ page, total }) => `第 ${page} 页，共 ${total} 页`,
    currentPage: ({ page, total }) => `第 ${page} 页，共 ${total} 页，当前页`,
    prev: ({ page }) => (page === undefined ? '上一页' : `上一页，第 ${page} 页`),
    next: ({ page }) => (page === undefined ? '下一页' : `下一页，第 ${page} 页`),
  },
} satisfies MoraineProviderProps['messages']

export function App(props) {
  return (
    <MoraineProvider locale="zh-CN" dir="ltr" messages={zhCN}>
      {props.children}
    </MoraineProvider>
  )
}
```

Changing `messages`, `locale`, or `dir` updates the rendered text and behavior without remounting the components. `useLocale()` returns stable `locale()` and `dir()` accessors for application code that needs the same values.

A component prop always wins over messages. `placeholder`, `aria-label`, `ariaLabel`, and `label` keep the caller's text, and messages fill only what the caller left unset.

Besides the tree-level `messages` on `MoraineProvider`, components with messages accept a `translations` prop (typed as `<Component>T.Translations`) for instance-level overrides without a nested provider. `CopyButton` is the exception: it reads its messages from the provider only.

```tsx
import { Pagination } from 'moraine'

;<Pagination
  total={50}
  translations={{
    prev: ({ page }) => (page === undefined ? 'Prev' : `Back to ${page}`),
  }}
/>
```

Component-level `translations` override `MoraineProvider messages`, while explicit component props (`aria-label`, `placeholder`, `label`) have final precedence over both.

## Messages

Each component defines its English copy next to its own source, so there is no monolithic message pack to bundle. Pass partial overrides through the `messages` prop of `MoraineProvider` (typed as `MoraineProviderProps['messages']`). The available groups are `alert`, `dialog`, `sheet`, `drawer`, `toast`, `breadcrumb`, `commandPalette`, `copyButton`, `dataTable`, `select`, `combobox`, `multiSelect`, `slider`, `pagination`, `pinInput`, `numberInput`, `fileUpload`, `tagsField`, `sidebar`, `form`, `kbd`, and `progress`.

`dialog` messages are `close`, `ok`, and `cancel`. Dialog and Alert Dialog use `close` for the corner button. Alert Dialog uses `ok` and `cancel` when an action omits `label`. `toast` messages are `close`, `cancel`, and `viewport`. Toast uses `close` for the corner button, `cancel` for the cancel button when `cancel` is `true`, and `viewport` for the live region label.

Dynamic messages that include a number or a name are functions so translations control word order:

```ts
const pagination = {
  prev: ({ page }) => (page === undefined ? '上一页' : `上一页，第 ${page} 页`),
}
```

`page` is omitted when the control is already on that edge. For plural rules, use `Intl.PluralRules`:

```ts
const rules = new Intl.PluralRules('en-US')

const pagination = {
  page: ({ page, total }) =>
    rules.select(total) === 'one'
      ? `Go to page ${page} of ${total} page`
      : `Go to page ${page} of ${total} pages`,
}
```

`kbd` is a record of accessible names for the built-in key aliases. The keycap symbol stays the same; only the announced name changes.

## Direction

`dir` on `MoraineProvider` controls direction-sensitive behavior of Moraine components, such as horizontal keyboard navigation, slider interaction direction, and portaled overlay positioning. It does not set a `dir` attribute on arbitrary descendants. Set `dir` on `<html>` for the browser's full RTL layout behavior.

Portaled popover, dialog, sheet, and drawer content receive `dir` from the provider when the component does not set `dir` itself. The attribute is omitted when neither the provider nor the component sets it, so server markup stays unchanged until you opt in, and inlined content follows `<html dir>`.

