Skip to Content

Accessibility

Build localized controls and content with native semantics, scoped language metadata, and safe rich-text rendering.

The React bindings prefer native controls and browser semantics. The LocaleSwitcher renders a labeled select and supports id, name, disabled, required, class names, and aria-describedby. Keep its label visible and ensure the referenced description exists.

import { useState } from "react";
import { createI18nReact } from "@puzzle-ui/i18n/react";
import { i18n } from "./i18n";

const { LocaleSwitcher, Provider, useLocaleAttributes } =
  createI18nReact(i18n);

function LocalizedContent({
  onLocaleChange,
}: {
  onLocaleChange: (locale: string) => void;
}) {
  const { lang, dir } = useLocaleAttributes();

  return (
    <main lang={lang} dir={dir}>
      <label htmlFor="language">Language</label>
      <LocaleSwitcher
        id="language"
        aria-describedby="language-help"
        onLocaleChange={onLocaleChange}
      />
      <p id="language-help">Choose the language for this page.</p>
    </main>
  );
}

function LocalizedPage() {
  const [locale, setLocale] = useState("ar");

  return (
    <Provider locale={locale}>
      <LocalizedContent onLocaleChange={setLocale} />
    </Provider>
  );
}

useLocaleAttributes returns the canonical lang and resolved dir for the current provider. Apply them to the relevant page or content region; the library does not mutate document-global attributes, which could conflict with other localized regions or concurrent rendering. Locale options include language metadata so native controls can expose each option's language and direction.

Use Translation for plain text and RichTranslation only with explicit component mappings for ICU tags. This preserves React's escaping and keeps untrusted catalog text from becoming markup. Prefer semantic headings, landmarks, and form labels in the surrounding application.

The browser fixture checks the select's accessible name and description, keyboard focus and switching, locale lang/dir, literal untrusted text, forced-colors mode, and reduced-motion preference. Run it with bun run --filter @puzzle-ui/i18n test:browser. Automated browser checks do not replace testing with the screen readers and input methods supported by your application.