Localization Provider

Provides translations for Base UI components.

Déplacez-moi

Utilisez Espace et les touches fléchées.

'use client';
import { Draggable } from '@base-ui/react/draggable';
import { LocalizationProvider } from '@base-ui/react/localization-provider';
import { frFR } from '@base-ui/react/locale-frFR';
import styles from './index.module.css';

const cardKind = Draggable.createKind('card');

export default function LocalizationProviderHero() {
  return (
    <LocalizationProvider translations={frFR}>
      <div className={styles.Root} lang="fr">
        <Draggable.Root className={styles.Card} kind={cardKind} label="la carte">
          Déplacez-moi
          <Draggable.ClonedPreview />
        </Draggable.Root>
        <p className={styles.Hint}>Utilisez Espace et les touches fléchées.</p>
      </div>
    </LocalizationProvider>
  );
}

Anatomy

Import the provider and a locale pack, then wrap the part of your application that should use it:

Anatomy

import { LocalizationProvider } from '@base-ui/react/localization-provider';
import { frFR } from '@base-ui/react/locale-frFR';

<LocalizationProvider translations={frFR}>
  {/* Your app or a group of components */}
</LocalizationProvider>

Without a provider, Base UI uses the English translations exported from @base-ui/react/locale-enUS.

The provider currently translates the accessibility text owned by the drag-and-drop components: the draggable role description, keyboard instructions, handle labels, and live-region announcements. Visible content and consumer-provided labels remain under your control.

Custom translations

Pass a partial translation object to override only the strings you need. It is usually best to start from a locale pack so the intent stays clear when new translations are added:

Custom translations

import { LocalizationProvider } from '@base-ui/react/localization-provider';
import { enUS } from '@base-ui/react/locale-enUS';

const translations = {
  ...enUS,
  dragRoleDescription: 'movable',
};

<LocalizationProvider translations={translations}>
  {/* Your drag-and-drop interface */}
</LocalizationProvider>

Nesting providers

Providers can be nested. An inner provider inherits the outer translations and replaces only the keys it defines:

Nested providers

<LocalizationProvider translations={frFR}>
  <FrenchBoard />
  <LocalizationProvider translations={{ dragRoleDescription: 'movable' }}>
    <EnglishTerminologyBoard />
  </LocalizationProvider>
</LocalizationProvider>

useTranslations is an internal hook for Base UI components and is not part of the public package API.

API reference

translationsPartial<LocalizationProvider.Translations>enUS

Name: translations
Description: Translations for Base UI-owned labels, instructions, and announcements. Partial objects are merged with the inherited translations.
Type: Partial<LocalizationProvider.Translations> | undefined
Default: enUS

childrenReact.ReactNode—

Name: children
Type: React.ReactNode | undefined

LocalizationProvider.PropsHide

Re-Export of LocalizationProvider props as LocalizationProviderProps

LocalizationProvider.StateHide

type LocalizationProviderState = {}

LocalizationProvider.TranslationsHide

type LocalizationProviderTranslations = {
  /** Value for `aria-roledescription` on a drag handle. */
  dragRoleDescription: string;
  /** Keyboard-drag instructions read when a drag handle is focused. */
  dragKeyboardInstructions: string;
  /** Accessible name for a drag handle that has none of its own. */
  dragHandleLabel: (params: { label?: string }) => string;
  /** Label for a dragged element in keyboard-drag announcements. */
  dragDefaultItemLabel: (params: { label?: string }) => string;
  /** Label for a multi-item keyboard drag. */
  dragMultipleItemsLabel: (params: { count: number }) => string;
  /** Phrase describing where the dragged item lands relative to a target. */
  dragDropPositionPhrase: (params: {
    position: 'before' | 'after' | 'on';
    target: string;
  }) => string;
  /** Announced when a keyboard drag picks up one or more items. */
  dragAnnouncementPickedUp: (params: { label: string; count: number }) => string | null;
  /** Announced as a keyboard drag moves. */
  dragAnnouncementMoved: (params: {
    label: string;
    count: number;
    positionPhrase: string | null;
  }) => string | null;
  /** Announced when a keyboard drag drops one or more items. */
  dragAnnouncementDropped: (params: {
    label: string;
    count: number;
    positionPhrase: string | null;
    hasDropTarget: boolean;
  }) => string | null;
  /** Announced when a keyboard drag is canceled. */
  dragAnnouncementCanceled: (params: { label: string; count: number }) => string | null;
}