Localisation

Every word the library ships is English by default, and every one can be replaced.

Call setLocale once to say what language the page speaks and registerLocale to give it the words. An element reads the registry on every render, so the order of the calls and the mounting does not matter.

The package ships a pack for eight languages. Each one holds a word for every key in the table below.

Import the pack, register it and set the locale. If <html lang> already names the language, skip setLocale. A tag with a region falls back to its language, so a page in fr-CA reads the fr pack. Register a pack under the tag your page uses.

To change one word, register the element's own key after the pack. A pack names every key, so a common key does not override it; the element's key comes first.

Dates, times and numbers need no pack. The elements format them with Intl in the element's locale or the page's locale.

Money needs no pack either. A chart with money prints in its currency, USD unless you set another ISO code, and the page's locale places the symbol and sets the grouping. currency="EUR" on a German page reads 1,2 Mio. € on the axis and 121.695 € in the tooltip, and the axis widens to fit. An English page keeps the short form the charts were designed with: $120k, $1.5k, $1.1M.

The packs were drafted without a review by native speakers. Have a native speaker read the pack for your language before you release.

Keys read <element family>.<name>. A key with no word of its own falls back to the same name under common, so one line translates every control called Close. A word set as a prop on the element wins over both, and anything nobody registered stays English rather than blank.

Some keys are sentences with values in them. Their English carries placeholders such as {item}, {n}, {count} and {list}, shown in the table below. A translation keeps the placeholders it needs, in any order, and may repeat one; a misspelt placeholder shows as written.

Every key the elements read, with its English and the elements that use it.

Set dir="rtl" on html or on any ancestor. Every element reads it from there: the reading order mirrors, the horizontal arrow keys follow it, and a glyph that means forward or back turns around. A dir="rtl" region inside an English page mirrors on its own, panels and menus included.

Two kinds of prop. One names a side of the screen and keeps naming it in either direction: position on sui-tooltip, sui-popover, sui-drawer and sui-toast-host, align on sui-popover, menu-align on sui-split-button, direction on sui-speed-dial, and a column's align on sui-data-table. The other names reading order with start and end, and follows it: icon-pos on sui-button, label-pos on sui-toggle-switch, end-icon on sui-icon-field, align on sui-timeline, a chart series' axis, the start, end and header-end slots, and everything with no prop at all: a leading icon, a trailing chevron, the sort arrow after a header, the box before a checkbox label, the rail of sui-side-nav. A 2D color field, a chart's x axis and an image compare's handle stay on the physical axis; their labels mirror.

In a tab bar, a menubar, a radio group, a select button, a stepper, a carousel, a tree, a tiered menu and a splitter, the arrow that points along the reading direction moves forward and the other moves back; Home, End and the vertical pair never change. A horizontal slider mirrors like the native range.

Flip the direction below. The controls mirror with their labels, the popups open toward the inline-end, the money column keeps its digits and moves its alignment, and the sort arrow stays after its header.