Siteplane UI

Localization

Translate the kit's own texts once, with the messages of the locale provider, and set the locale its dates follow.

Markdown

The kit writes a few texts of its own: the Today, Cancel and Apply of a date picker, the Previous and Next of a Pagination, the error of an incomplete date, and the names that screen readers hear, such as the Remove of a tag or the name of a close button. They are English by default. SiteplaneLocaleProvider takes the locale of your application and messages, the kit's texts in its language, and every component inside reads its texts from them. A component's own prop, such as Pagination's labels or the aria-label of a close button, still changes that one instance.

Set the locale and the messages

Install the provider. Calendar, Date Field, Date Picker, Date Range Picker and Date Time Picker install it with them.

pnpm dlx shadcn@4.18.0 add @siteplane/locale

Render it once around your application, outside the kit's other providers, such as ToastProvider, so that toasts and every overlay read the same messages. This one sets German, with the German messages that the kit ships:

src/components/providers.tsx
"use client";

import { germanMessages } from "@/siteplane/system/locale/messages-de";
import { SiteplaneLocaleProvider } from "@/siteplane/system/locale/siteplane-locale-provider";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <SiteplaneLocaleProvider locale="de-DE" messages={germanMessages}>
      {children}
    </SiteplaneLocaleProvider>
  );
}

A text with values is a function, and a function cannot pass from a Server Component to a Client Component. Import the messages in the client file that renders the provider, as above, and render that file from your root layout. Messages that hold only strings can also be passed from a Server Component.

Component properties
PropTypeDefaultDescription
localestringrequiredThe locale of the components inside, such as de-DE. The date and time components write their dates in it, React Aria its own texts, such as the month names, and the parts that write numbers, such as the charts, Progress and Number Field, their numbers. It also sets React Aria's reading direction for a right-to-left language.
messagesSiteplaneMessagesEnglishThe kit's texts in your language, by component. Each group and each text is optional; a text left out keeps the one of an outer provider, or its English default.
childrenReactNode–The part of your application in this locale.

A provider inside another keeps what it leaves out: <SiteplaneLocaleProvider locale="de-AT"> keeps the outer messages, and an inner messages changes only the texts it names. The locale prop of Calendar, Date Field, Date Picker, Date Range Picker and Date Time Picker opens such a provider, so their texts stay your application's. useSiteplaneLocale() returns the locale of the nearest provider, or the browser's language without one, so your own dates can follow the kit's.

Ready-made translations

The kit ships its texts in German as an item of their own. Install it with the provider:

pnpm dlx shadcn@4.18.0 add @siteplane/locale @siteplane/messages-de

It writes system/locale/messages-de.ts, every text of the kit in German, which you pass to the provider:

<SiteplaneLocaleProvider locale="de-DE" messages={germanMessages}>

The file is source that your application owns. Change a word in it, or keep it as it is and replace a group where you render the provider:

const messages = {
  ...germanMessages,
  datePicker: { ...germanMessages.datePicker, apply: "Fertig" },
};

A later version of the kit brings its new texts in German with it; install the item again with the other items, as for any update. For another language, copy the file as a start and write it with satisfies SiteplaneMessageCatalog, so the typecheck names every text it still lacks.

Messages

The messages are grouped by component, such as datePicker, pagination or closeButton. A key is named after its text or after the prop that replaces it for one instance, such as accountCard.signOut for signOutLabel. Write your messages with satisfies SiteplaneMessages, so a mistyped key or a text of the wrong kind is a type error:

import type { SiteplaneMessages } from "@/siteplane/system/locale/siteplane-locale-provider";

export const de = {
  calendar: { today: "Heute" },
  datePicker: { apply: "Übernehmen", cancel: "Abbrechen" },
  pagination: {
    next: "Weiter",
    pageStatus: "Seite {page} von {total}",
    previous: "Zurück",
  },
  chip: {
    remove: (label) => (label ? `${label} entfernen` : "Entfernen"),
  },
} satisfies SiteplaneMessages;

A text with values, such as a name or a count, is a function that receives them, so your translation keeps its own word order and can choose a plural form. pagination.pageStatus is the one template: {page} and {total} stand where the numbers go, as Pagination's labels takes it.

Some groups belong to a part that other components render, so one translation covers all of them. closeButton.label names the close of every Dialog, Sheet, Drawer, Popover, Alert and Featured Card. chip.remove names the remove action of a Badge, a Tag, a tag of Tags Input and a chip of a multiple Combobox, with the chip's label, so ${label} entfernen reads “Design entfernen”. The calendar texts follow the Calendar into the date pickers, datePicker.cancel and datePicker.apply are the footer of every picker that waits for Apply, and the timeField texts are also the Date Time Picker's. The accountCard texts are the account menu that Account Card and Header Navigation's HeaderAccountMenu share.

A prop of one component still wins for that component, such as <Pagination labels={{ next: "Mehr" }}> inside a German provider. For a complete translation, write satisfies SiteplaneMessageCatalog instead: the typecheck then names every text that your translation lacks, also one that a later version of the kit adds. The English defaults are englishMessages in system/locale/messages.ts, whose types describe every text.

What follows the locale

The date and time components write their dates in the locale without any messages: Calendar, Date Field, Date Picker, Date Range Picker, Date Time Picker and Time Field, and the date parts of Modal Block. Their month and weekday names, the placeholders and names of their segments, such as tt.mm.jjjj, and the Calendar's arrows between months are React Aria's own texts and come in the locale's language too. Without a provider React Aria uses the browser's language once the page has hydrated, and en-US on the server and while the page hydrates, so the two agree.

Numbers follow the locale as well. The charts, Bar List, Progress, Meter, Avatar Group, Motion Number, Number Field and Slider write numbers, percentages and currencies in it, unless one of them gets a locale of its own. Without a provider the charts and the others write en-US, so the server and the browser write the same text, and Number Field and Slider keep Base UI's default, the browser's language.

What needs messages

Every other text of the kit comes from the messages: the words on buttons and links, the names that screen readers hear, placeholders, error messages and the words that a part announces, such as Copied. The messages also replace the English that Base UI gives some parts: the Increase and Decrease of a Number Field and the name of the region that toasts appear in. One text has no message: the hidden Dismiss button that a modal Combobox adds for screen readers comes from Base UI, which offers no way to change it.

For a right-to-left language, also set dir and lang on the html element yourself.