Labels and i18n
Translate every grid string with one typed labels object, wire it to your i18n library, and switch the grid to right-to-left layout.
Every user-facing string lives in one typed DataGridLabels object with English defaults, except the text of the lookup editor and the comments popover. Pass a partial labels object to translate it. Lookup columns take their own labels, listed under Coverage by group. The direction prop flips the layout for right-to-left languages. The grid has no i18n dependency.
The labels prop
Pass labels to DataGridProvider or DataGrid. The grid deep-merges it over DEFAULT_LABELS. Only the keys you set change, and the rest stay English:
import {
DataGrid,
type DeepPartialLabels,
} from "@/components/data-grid/data-grid";
const labels: DeepPartialLabels = {
toolbar: { searchPlaceholder: "Rechercher…" },
contextMenu: { copy: "Copier", paste: "Coller" },
grid: { emptyState: "Aucune ligne" },
};
export function FrenchGrid() {
return (
<DataGrid className="h-80" defaultData={[]} columns={[]} labels={labels} />
);
}A label that contains a value, such as a count, is a function. The grid calls it with the values:
import type { DeepPartialLabels } from "@/components/data-grid/data-grid";
const labels: DeepPartialLabels = {
toolbar: { searchMatches: (current, total) => `${current}/${total}` },
};Deep merging (DeepPartialLabels)
The merge goes through plain objects key by key. A function, an array, or a string that you set replaces the default as a whole. The grid does not merge a function with the default function.
Setting toolbar.searchPlaceholder leaves every other toolbar string and every other group in English. A key that you set to undefined keeps the default.
Reading effective labels
Call useDataGridLabels() under DataGridProvider to read the merged labels. Your own controls then use the same copy as the grid:
import { useDataGridLabels } from "@/components/data-grid/data-grid";
function ClearFiltersButton() {
const labels = useDataGridLabels();
return <button>{labels.toolbar.clearFilters}</button>;
}Coverage by group
DataGridLabels groups strings by the surface that owns them. Leave a group out and it stays in English.
| Group | Covers | Owner |
|---|---|---|
toolbar | search, filter menu, header filter, columns menu | data-grid-toolbar |
sort | sort button, sort list, announcements | data-grid-sort-list |
filterOperators | operator names such as contains and gt | data-grid-toolbar |
contextMenu | cut, copy, paste, row items, sort, pin, hide, autosize | data-grid-context-menu |
keybindings | shortcuts dialog and action names | data-grid-keybindings |
markers | select-all, row checkboxes, reorder handle and announcements | core |
grouping | group row text, toggle names, menu items, announcements | core |
grid | empty-state, progress, and error messages, date editor, announcements | core |
io | export, import dialog, print | data-grid-io |
pagination | page buttons, page size, range text | data-grid-pagination |
statusBar | count, sum, average, minimum, maximum, selection text | data-grid-status-bar |
views | the saved views button and menu | data-grid-views |
findReplace | panel fields, buttons, status lines | data-grid-find-replace |
options.labels of a lookup column | the lookup editor | data-grid-lookup, lookup cell |
labels of useDataGridComments | the comments popover, its menu item, and its announcements | data-grid-comments, Comments labels |
Labels reference lists every field of every group.
Some labels are functions of a count or a size, such as grid.saveRejected and io.emptyDropzoneCaption. statusBar.allSelected and statusBar.selectAllMatching receive null for an unknown result size.
keybindings.actions maps an action to its name. The defaults name the built-in actions. A custom action from commands that the map leaves out gets a name made from its own id.
Full German example
A representative override. Every key that it leaves out keeps its English default:
import type { DeepPartialLabels } from "@/components/data-grid/data-grid";
const de: DeepPartialLabels = {
toolbar: {
searchPlaceholder: "Suchen…",
filter: "Filter",
addFilter: "Filter hinzufügen",
clearFilters: "Alle löschen",
filterConnectorAnd: "Und",
filterConnectorOr: "Oder",
columns: "Spalten",
},
contextMenu: {
cut: "Ausschneiden",
copy: "Kopieren",
paste: "Einfügen",
duplicateRows: (n) => (n > 1 ? "Zeilen duplizieren" : "Zeile duplizieren"),
deleteRow: "Zeile löschen",
pinStart: "Am Anfang anheften",
pinEnd: "Am Ende anheften",
autosize: "Spaltenbreite anpassen",
},
grid: {
emptyState: "Keine Zeilen",
noResults: "Keine Ergebnisse",
saveRejected: (n) => `${n} nicht gespeichert`,
loading: "Wird geladen…",
rowsChecked: (n) => `${n} ${n === 1 ? "Zeile" : "Zeilen"} ausgewählt`,
},
};Wire an i18n library
labels is a plain object, so it works with any i18n library. Build it from your translate function:
import {
DataGrid,
type DeepPartialLabels,
} from "@/components/data-grid/data-grid";
export function OrdersGrid({ t }: { t: (key: string) => string }) {
const labels: DeepPartialLabels = {
toolbar: { searchPlaceholder: t("toolbar.searchPlaceholder") },
grid: { emptyState: t("grid.emptyState") },
};
return (
<DataGrid className="h-80" defaultData={[]} columns={[]} labels={labels} />
);
}t stands for the translate function of your i18n library.
The grid compares labels by content, so a literal object of strings needs no useMemo. A label that is a function, such as pasteBlocked, counts as changed unless it keeps its identity. Define such a label at module scope, or build the object with useMemo keyed on your active locale.
Locale
The locale prop of the provider is a BCP 47 tag such as "de-DE". It sets the language of the number columns that have options.format and the date columns that have options.displayFormat, the status bar, and the default labels. It also sets the sort language unless you pass sortLocale. It defaults to "en-US", so the server and the browser render the same text.
options.locale of a column and formatValue of the status bar win over locale. A column options.locale without a format groups the digits of a number cell and shows the medium date style in a date cell. A column with no format and no options.locale shows the plain number or the ISO text. See Built-in cell types.
RTL layout
labels does not flip the layout. direction flips the layout and does not translate. Most apps derive both from one active locale:
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
type DeepPartialLabels,
} from "@/components/data-grid/data-grid";
const TRANSLATIONS = {
en: {
dir: "ltr",
locale: "en-US",
labels: { toolbar: { searchPlaceholder: "Search…" } },
},
ar: {
dir: "rtl",
locale: "ar-EG",
labels: { toolbar: { searchPlaceholder: "بحث…" } },
},
} as const satisfies Record<
string,
{ dir: string; locale: string; labels: DeepPartialLabels }
>;
export function LocaleGrid({ locale }: { locale: keyof typeof TRANSLATIONS }) {
const { dir, labels, locale: tag } = TRANSLATIONS[locale];
return (
<DataGridProvider
defaultData={[]}
columns={[]}
labels={labels}
locale={tag}
>
<DataGridRoot className="h-80" direction={dir}>
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
);
}Without direction, the grid reads the direction it inherits from the page at mount, and again when a dir attribute in the document changes. A grid inside <html dir="rtl"> is right-to-left with no prop. Pass direction to force one direction. With server rendering, pass direction: the server HTML is left-to-right until the grid mounts. See Server rendering.
What mirrors
Direction mirrors the column order, pinned zones, row marker column, pin shadows, resize handles, drop indicators, and the pointer math for selection and drags.
- Arrow keys move visually. In
rtl, ArrowRight moves toward the right edge of the screen, which is the previous column. - Tab and Shift+Tab leave the grid in both directions.
- Home and End stay logical. Home goes to the first column in both directions.
- Cell values render inside
<bdi>, so each value reads in its own script. Cell editors carrydir="auto", so the caret follows the value.
Base UI chrome
DataGridRoot sets dir on the grid element and wraps its subtree in the direction provider of Base UI. Menus, popovers, and dialogs of the add-ons then place and navigate correctly. Portaled content that you render yourself, outside the grid, needs dir passed to it.
Set dir on the document too
The grid element carries its own dir. The page around it does not. Set dir="rtl" on <html> or on a layout wrapper so the rest of the page mirrors with the grid.
Related
- I18n and RTL example: a grid in two languages and two directions
- Labels reference: every field of every group
- Messages cheatsheet: the warnings and texts the grid prints
- Loading state: the texts of the loading, empty, and error states