Skip to main content

Localization

Components ship English text only: button names, role descriptions, live-region announcements, and default labels. Each resolves that text per key, in this order:

  1. The element's messages property (reorderMessages on rc-list).
  2. Text registered with registerMessages() from @rcarls/rc-common for the element's locale: the exact tag, then its base language (de-CH, then de).
  3. The English default.
import { registerMessages } from '@rcarls/rc-common';

registerMessages('de', {
  'rc-carousel': {
    previous: 'Vorherige Folie',
    next: 'Nächste Folie',
    goToSlide: (position) => `Zu Folie ${position}`,
  },
  'rc-search-bar': { clear: 'Suche löschen' },
});

Register before components connect so English never flashes. Registering later, or changing a lang or dir attribute, re-renders the affected components, so a language switch needs no reload.

Which locale​

The locale is the element's own lang attribute, else <html lang>. An explicit lang="" means the language is unknown and does not inherit the page locale. An ancestor's lang is skipped on purpose: it usually marks content, such as a German recipe on an English page, while component chrome stays in the interface language. Changes inside shadow roots and other documents are observed when the component is connected there.

<html lang="en">
  <article lang="de">
    <!-- Buttons read "Previous slide": the article's lang is content. -->
    <rc-carousel aria-label="Fotos">…</rc-carousel>
  </article>
</html>

Keys and numbers​

Each component page lists its keys under Localization. Interpolating entries are functions, such as goToSlide: (position, count, locale?) => string. Numbers arrive as numbers so translations can choose their own wording. Built-in messages format the numbers with Intl.NumberFormat for the interface locale. Translation functions can use the optional locale argument with numberFormat(locale) from @rcarls/rc-common. Numbers a component writes itself, such as rc-progress's percentage and rc-splitter's value text, use the same locale.

When a message places consumer text of unknown direction inside a sentence, isolate that text with bidiIsolate(text) from @rcarls/rc-common. Built-in messages do this for dynamic names and option labels. This keeps the surrounding punctuation and word order stable in mixed left-to-right and right-to-left text.

RcMessageCatalog types registerMessages(): each package adds its scope when you import it, so a misspelled scope or key fails to compile.

Per-instance names​

A name a consumer usually sets per instance stays an attribute: label on rc-adaptive-menu, rc-chip-group, rc-menubar, and rc-splitter; available-label and selected-label on rc-transfer-list; low-label and high-label on rc-range-slider. Unset, it falls back to a message.