feat: add localization support and deprecate old props in DataTable (jbetancur#1323)

Author: jbetancur

apps/docs/package-lock.json

@@ -11,6 +11,7 @@
   "dependencies": {
     "@astrojs/react": "^4.2.0",
     "@astrojs/tailwind": "^5.1.4",
+    "@shikijs/langs": "^4.1.0",
     "astro": "^5.7.0",
     "react": "^18.3.1",
     "react-data-table-component": "*",

apps/docs/package.json

@@ -165,6 +165,14 @@ Column-level footers live on each [`TableColumn<T>`](#tablecolumnt) as the `foot
 | `onColumnOrderChange` | `(columns: TableColumn<T>[]) => void` | - | Called after a drag-to-reorder column operation with the new column order. |
 | `onColumnGroupOrderChange` | `(groups: ColumnGroup[], columns: TableColumn<T>[]) => void` | - | Called after a group drag-reorder with the new group order and the matching updated column order. |
 
+### Localization
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `localization` | `Localization` | - | Override every user-visible string and aria-label in the table. Pass a pre-built locale or build your own. See [Localization](/docs/localization). |
+| ~~`columnFilterOptions`~~ | `ColumnFilterOptions` | - | **Deprecated.** Use `localization={{ filter: { ... } }}` instead. Will be removed in v9. |
+| ~~`expandableRowsOptions`~~ | `ExpandableRowsOptions` | - | **Deprecated.** Use `localization={{ expandable: { ... } }}` instead. Will be removed in v9. |
+
 ## ColumnGroup
 
 Defines a spanning group header above one or more columns. Pass an array to the `columnGroups` prop.

apps/docs/src/pages/docs/api.md

@@ -11,6 +11,56 @@ import CodeBlock from '../../components/CodeBlock.astro';
     <a href="https://github.com/jbetancur/react-data-table-component/commits/master" target="_blank" rel="noreferrer">repository on GitHub</a>.
   </p>
 
+  <h2>8.3.0</h2>
+
+  <h3>New features</h3>
+  <ul>
+    <li>
+      <strong>Localization</strong> — new <code>localization</code> prop on <code>DataTable</code>
+      replaces the three separate option props (<code>columnFilterOptions</code>,
+      <code>expandableRowsOptions</code>, and pagination aria-label fields on
+      <code>paginationComponentOptions</code>). Pass a single object to translate every string and
+      aria-label in the table — filter panel, pagination navigation, and expand/collapse buttons.
+      → <a href="/docs/localization">Localization docs</a>
+    </li>
+    <li>
+      <strong>Built-in locales</strong> — import pre-built translations from the
+      <code>react-data-table-component/locales</code> subpath. Ships with:
+      English (<code>en</code>), French (<code>fr</code>), Spanish (<code>es</code>),
+      German (<code>de</code>), Brazilian Portuguese (<code>ptBR</code>),
+      Arabic — Modern Standard (<code>ar</code>), Egyptian (<code>arEG</code>), Levantine (<code>arLV</code>),
+      Hebrew (<code>he</code>),
+      Chinese Simplified (<code>zhCN</code>), Chinese Traditional (<code>zhTW</code>),
+      Japanese (<code>ja</code>), Korean (<code>ko</code>), Ukrainian (<code>uk</code>).
+      Each locale is individually tree-shakeable.
+    </li>
+    <li>
+      New utility exports: <code>emptyFilterState(type)</code> and <code>isFilterActive(filter)</code>.
+      → <a href="/docs/filtering#utility-exports">Filtering docs</a>
+    </li>
+  </ul>
+
+  <h3>Deprecations</h3>
+  <p>The following will continue to work in 8.x but will be removed in v9. TypeScript will show a deprecation hint.</p>
+  <ul>
+    <li>
+      <code>columnFilterOptions</code> prop — use <code>localization</code> with a <code>filter</code> key instead.
+    </li>
+    <li>
+      <code>expandableRowsOptions</code> prop — use <code>localization</code> with an <code>expandable</code> key instead.
+    </li>
+    <li>
+      Pagination aria-label fields on <code>paginationComponentOptions</code>
+      (<code>navigationAriaLabel</code>, <code>firstPageAriaLabel</code>, <code>previousPageAriaLabel</code>,
+      <code>nextPageAriaLabel</code>, <code>lastPageAriaLabel</code>) —
+      use <code>localization</code> with a <code>pagination</code> key instead.
+    </li>
+    <li>
+      <code>ColumnFilterOptions</code> and <code>ExpandableRowsOptions</code> types —
+      use <code>Localization['filter']</code> and <code>Localization['expandable']</code> instead.
+    </li>
+  </ul>
+
   <h2>8.2.0</h2>
 
   <h3>New features</h3>

apps/docs/src/pages/docs/changelog.astro

@@ -109,7 +109,9 @@ function DataTableInner<T>(props: TableProps<T>, ref: React.ForwardedRef<DataTab
 		columnGroups,
 		filterValues: controlledFilterValues,
 		onFilterChange: onFilterChangeProp,
-		localization = {},
+		localization: localizationProp = {},
+		columnFilterOptions,
+		expandableRowsOptions,
 		resizable = false,
 		initialColumnWidths,
 		onColumnResize,
@@ -122,6 +124,12 @@ function DataTableInner<T>(props: TableProps<T>, ref: React.ForwardedRef<DataTab
 		ariaLabel,
 	} = props;
 
+	const localization = {
+		...localizationProp,
+		filter: { ...columnFilterOptions, ...localizationProp.filter },
+		expandable: { ...expandableRowsOptions, ...localizationProp.expandable },
+	};
+
 	// Intentionally reading @deprecated props for backward compat; cast prevents TS hint 6385 here
 	const {
 		sortIcon: sortIconProp,

src/components/DataTable.tsx

@@ -35,6 +35,10 @@ export type {
 	PaginationOptions,
 	PaginationServerOptions,
 	Localization,
+	/** @deprecated Use `Localization['filter']` instead. Will be removed in v9. */
+	ColumnFilterOptions,
+	/** @deprecated Use `Localization['expandable']` instead. Will be removed in v9. */
+	ExpandableRowsOptions,
 	SortFunction,
 	Selector,
 	FilterType,

src/index.ts

@@ -165,6 +165,10 @@ type ExpandableProps<T> = {
 	expandOnRowClicked?: boolean;
 	expandOnRowDoubleClicked?: boolean;
 	onRowExpandToggled?: ExpandRowToggled<T>;
+	/**
+	 * @deprecated Use the `localization` prop instead: `localization={{ expandable: { ... } }}`. Will be removed in v9.
+	 */
+	expandableRowsOptions?: ExpandableRowsOptions;
 };
 
 type SortProps<T> = {
@@ -246,6 +250,10 @@ type BaseTableProps<T> = {
 	onFilterChange?: (columnId: string | number, filter: FilterState) => void;
 	/** Override every user-visible string in DataTable. Pass a pre-built locale or build your own. */
 	localization?: Localization;
+	/**
+	 * @deprecated Use the `localization` prop instead: `localization={{ filter: { ... } }}`. Will be removed in v9.
+	 */
+	columnFilterOptions?: ColumnFilterOptions;
 	onColumnOrderChange?: (nextOrder: TableColumn<T>[]) => void;
 	/** Called after a group drag reorder with the new group order and matching column order. */
 	onColumnGroupOrderChange?: (nextGroups: ColumnGroup[], nextColumns: TableColumn<T>[]) => void;
@@ -482,6 +490,16 @@ export interface PaginationOptions {
 	selectAllRowsItemText?: string;
 }
 
+/**
+ * @deprecated Use `Localization['filter']` instead. Will be removed in v9.
+ */
+export type ColumnFilterOptions = NonNullable<Localization['filter']>;
+
+/**
+ * @deprecated Use `Localization['expandable']` instead. Will be removed in v9.
+ */
+export type ExpandableRowsOptions = NonNullable<Localization['expandable']>;
+
 /** All user-visible strings rendered by DataTable, grouped by feature area. */
 export interface Localization {
 	pagination?: {