i18n & RTL Guide

Locale Configuration

Pass locale and direction settings to TableProvider to enable internationalization and right-to-left layout support.

tsx

import { TableProvider } from "@your-scope/tablecraft";

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <TableProvider
      i18n={{
        locale: "ar",
        direction: "rtl",
      }}
    >
      {children}
    </TableProvider>
  );
}

Direction Modes

The direction property accepts three values that control how the table layout is rendered:

'ltr' — Forces left-to-right layout regardless of locale. Use this when you want to pin the layout direction explicitly.
'rtl' — Forces right-to-left layout regardless of locale. Use this when you want to guarantee RTL rendering.
'auto' — Detects the direction from the provided locale value. TableCraft maintains an internal list of known RTL locales (e.g. ar, he, fa, ur). If the locale matches one of those entries the direction resolves to rtl; otherwise it resolves to ltr.

What RTL Affects

Enabling RTL mode applies a coordinated set of layout and formatting changes across the entire table component tree:

Pagination arrows rotate 180° so that “previous” and “next” point in the correct visual direction.
Dropdown menus receive a dir="rtl" attribute so that their alignment and open direction follows the reading order.
Text alignment defaults to right for cells, headers, and labels.
Date formatting uses the active locale (e.g. ar) when calling Intl.DateTimeFormat, producing locale-correct numeral and month representations.
Button and icon spacing switches from mr-2 (margin-right) to me-2 (margin-end) so spacing is relative to the writing direction rather than a fixed physical side.
The column visibility dropdown label flips its flex direction to match the active reading direction.

Translation System

TableCraft ships with 60+ translation keys organised under the table namespace. Every user-visible string in the component is looked up through this namespace so you can fully localise the UI. Below is a representative sample of the available keys with their English defaults and Arabic translations:

table.edit — Edit / تعديل
table.delete — Delete / حذف
table.show — Show / عرض
table.search — Search / بحث
table.filter — Filter / تصفية
table.reset — Reset / إعادة تعيين
table.export — Export / تصدير
table.columns — Columns / الأعمدة
table.noResults — No results found / لا توجد نتائج
table.loading — Loading… / جارٍ التحميل…
table.rowsPerPage — Rows per page / صفوف في الصفحة
table.of — of / من
table.page — Page / صفحة
table.next — Next / التالي
table.previous — Previous / السابق

Custom Translation Function

If you are not using Next.js with next-intl you can supply your own translationFn callback. The function receives the full translation key (including namespace) and must return the translated string.

tsx

import { TableProvider } from "@your-scope/tablecraft";
import frTranslations from "./locales/fr.json";

// Minimal key-lookup helper — swap for i18next, lingui, or any other library.
function translationFn(key: string): string {
  // key format: "table.edit", "table.delete", etc.
  const parts = key.split(".");
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  let value: any = frTranslations;
  for (const part of parts) {
    value = value?.[part];
  }
  return typeof value === "string" ? value : key;
}

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <TableProvider
      i18n={{ locale: "fr", direction: "ltr" }}
      translationFn={translationFn}
    >
      {children}
    </TableProvider>
  );
}

When translationFn is provided, TableCraft bypasses the next-intl useTranslations hook entirely. Your callback becomes the sole source of all translated strings, giving you full control over the translation layer without any dependency on next-intl.

Mixed Direction Content

TableCraft uses CSS logical properties throughout its internal styles rather than physical directional properties. This means layout rules automatically mirror themselves when the writing direction changes without any extra overrides on your part.

Key logical property mappings used inside the component tree:

inset-inline-start / inset-inline-end (CSS) — maps to Tailwind's start-* / end-* utilities.
margin-inline-start / margin-inline-end — Tailwind ms-* / me-*.
padding-inline-start / padding-inline-end — Tailwind ps-* / pe-*.

If you extend or override table styles in your own application, prefer these logical utilities over physical ones (ml-*, mr-*, pl-*, pr-*, left-*, right-*) to ensure your customisations remain direction-agnostic and continue to work correctly in both LTR and RTL contexts.