Skip to main content

Localization

Locale, direction, and translatable component text through MoraineProvider.

View as Markdown

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.

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.

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:

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

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

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