@spree/docs 0.1.122 → 0.1.124

package/dist/developer/dashboard/customization/quickstart.md

@@ -0,0 +1,100 @@
+---
+title: Quickstart
+sidebarTitle: Quickstart
+description: Add your first customization to the Spree dashboard in under 5 minutes — no npm publishing, no build configuration, just one file in your dashboard app.
+---
+
+This guide assumes two things are running:
+
+1. A Spree API server (your Spree store's backend).
+2. Your dashboard app — the small Vite project that renders the admin. In a `create-spree-app` project it lives at `apps/dashboard/`; add it to an existing project with `npx spree add dashboard`, or scaffold it anywhere with `npx spree add dashboard --template` pointing at your own copy. Start it with `pnpm dev`.
+
+All customizations in this guide are edits to your dashboard app's own code. **You don't need to scaffold a plugin** — plugins are for [distributing features to other stores](../plugins/overview.md).
+
+## The 30-second example
+
+Add an "Analytics" item to the dashboard sidebar.
+
+**Step 1.** Open `src/plugins.ts` — the starter ships this file already wired up — and register a nav entry:
+
+```tsx
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { BarChartIcon } from 'lucide-react'
+
+defineDashboardPlugin({
+  nav: [{
+    key: 'analytics',
+    label: 'Analytics',
+    path: '/analytics',
+    icon: BarChartIcon,
+    // Built-in entries use positions 100–600 (Home … Reports).
+    // 650 places Analytics after Reports, at the end.
+    position: 650,
+  }],
+})
+```
+
+**Step 2.** Save. The dev server hot-reloads and the sidebar now shows "Analytics".
+
+Clicking it lands on a "Page not found" screen — we registered the nav entry but no page. Let's fix that.
+
+## Add the page
+
+**Step 3.** Create the page component at `src/pages/analytics.tsx`:
+
+```tsx
+import { PageHeader } from '@spree/dashboard-core'
+import { ResourceLayout } from '@spree/dashboard-ui'
+
+export function AnalyticsPage() {
+  return (
+    <ResourceLayout
+      header={<PageHeader title="Analytics" subtitle="Store performance over time" />}
+      main={<p>Coming soon.</p>}
+    />
+  )
+}
+```
+
+**Step 4.** Register the route in `src/plugins.ts`:
+
+```tsx
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { BarChartIcon } from 'lucide-react'
+import { AnalyticsPage } from './pages/analytics'
+
+defineDashboardPlugin({
+  nav: [{
+    key: 'analytics',
+    label: 'Analytics',
+    path: '/analytics',
+    icon: BarChartIcon,
+    position: 650,
+  }],
+  routes: [{
+    key: 'analytics',
+    path: '/analytics',
+    component: AnalyticsPage,
+  }],
+})
+```
+
+Save. Click "Analytics" — your page renders inside the dashboard chrome, at `/<store id>/analytics`.
+
+> **WARNING:** Every `key` must be unique, including against the built-ins (`getting-started`, `home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.
+
+## What just happened
+
+`defineDashboardPlugin` registers extensions against the dashboard's shared registries: `nav`, `routes`, `slots`, `tables`, `settingsNav`, `formFields`, and `customFieldComponents`. Your `src/plugins.ts` runs when the app boots (the starter's `main.tsx` imports it), so everything is registered before the first render. These are the exact same APIs distributable plugins use — the only difference is packaging.
+
+The custom route mounts under `/<store id>/analytics`. Routes registered this way are matched at navigation time, so they can even be registered lazily after boot.
+
+Building a **distributable plugin** rather than customizing your own app? Ship pages as [file routes](routes.md) instead — they compile into the app's route tree, so links to them are type-checked. The registry form shown here is for in-app customization.
+
+## Next steps
+
+- [Navigation](navigation.md) — sidebar entries, nesting under built-in menus, settings sub-nav, permission gating
+- [Routes](routes.md) — path patterns, params, permission fallback
+- [Slots](slots.md) — inject widgets into built-in pages without forking them
+- [Tables](tables.md) — define your own list page or extend built-in tables
+- [Translations](translations.md) — add i18n keys without colliding with the framework

package/dist/developer/dashboard/customization/routes.md

@@ -0,0 +1,187 @@
+---
+title: Routes
+sidebarTitle: Routes
+description: Mount custom pages under your dashboard's `/$storeId/...` path. Supports path params, permission gating, and works alongside the dashboard's built-in routes.
+---
+
+The dashboard's first-party routes (`customers/`, `orders/`, `products/`, …) are file-based via TanStack Router and live in `@spree/dashboard/src/routes/`. Custom pages have two mechanisms:
+
+1. **File routes** (packaged plugins — preferred): the plugin ships ordinary TanStack route files, and the host build compiles them into its typed route tree. Typed `<Link>`s with no casts, route-level code splitting, `validateSearch`, loaders — full router citizenship.
+2. **Route registry** (in-app & dynamic): `defineDashboardPlugin({ routes })` entries matched at navigation time by a catch-all dispatcher at `/_authenticated/$storeId/$`. Use for host-app customizations (`plugins.ts`) and anything registered conditionally at runtime. File routes always win over the registry — the catch-all is the lowest-priority match.
+
+## File routes (packaged plugins)
+
+Declare a routes directory in your plugin's marker and put TanStack route files in it:
+
+```jsonc
+// package.json
+"spree": { "dashboard": { "plugin": true, "routes": "./src/routes" } }
+```
+
+```
+src/
+├── pages/                     # page components
+└── routes/
+    ├── brands.index.tsx       # → /$storeId/brands
+    └── brands.$brandId.tsx    # → /$storeId/brands/br_123
+```
+
+```tsx
+// src/routes/brands.index.tsx
+import { resourceSearchSchema } from '@spree/dashboard-core'
+import { createFileRoute } from '@tanstack/react-router'
+import { BrandsListPage } from '../pages/brands-list'
+
+export const Route = createFileRoute('/_authenticated/$storeId/brands/')({
+  validateSearch: resourceSearchSchema,
+  component: () => <BrandsListPage searchParams={Route.useSearch()} />,
+})
+```
+
+Rules that make this work:
+
+- **Commit the final composed path literal.** Plugin routes mount under the dashboard's `_authenticated/$storeId` layout; the route generator verifies the literal (and would rewrite a wrong one).
+- **The host regenerates its `routeTree.gen.ts` on every dev start and build** from installed package versions — updating your plugin picks up new routes automatically (dev servers need a restart, same as installing a plugin).
+- **Exclude `src/routes` from your package's standalone `tsc`** — `createFileRoute` paths only type-check against a generated tree, which exists in host programs. Develop against a dashboard host (the scaffold's tsconfig ships this exclusion).
+
+Links to file routes are fully typed — no casts:
+
+```tsx
+<Link to="/$storeId/brands/$brandId" params={{ brandId: brand.id }}>view</Link>
+```
+
+### Route collisions
+
+Two packages can't own the same route path. If a plugin declares a path that another plugin — or a built-in dashboard page — already claims, the build fails before generating the tree with an error naming both **packages**, the path, and each file:
+
+```
+Dashboard route collision.
+Route "/_authenticated/$storeId/brands/" is declared by more than one package:
+  - @acme/brands (…/node_modules/@acme/brands/src/routes/brands.index.tsx)
+  - @other/brands (…/node_modules/@other/brands/src/routes/brands.index.tsx)
+```
+
+Rename one of the routes, or drop the plugin that shouldn't own it. (Duplicate paths *within* a single package are reported by the TanStack generator instead — that's an authoring bug in one package.)
+
+> **WARNING:** The collision check only sees **file routes**. If a runtime-registry route (below) uses the same URL as a compiled file route, there's no build error — the file route silently wins on every navigation, because the registry's catch-all is the lowest-priority match. If a page you registered at runtime never renders, check whether an installed plugin claims the same path.
+
+## Runtime route registry (in-app & dynamic)
+
+Register from your host app's `plugins.ts` (or a plugin that genuinely needs runtime registration):
+
+```tsx
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { ReportsPage } from './pages/reports'
+
+defineDashboardPlugin({
+  routes: [{
+    key: 'reports',
+    path: '/reports',
+    component: ReportsPage,
+  }],
+})
+```
+
+`path` is **relative** to `/$storeId` — the dispatcher prepends the prefix at match time. So `/reports` matches the URL `/store_xyz/reports`. The leading `/` is required.
+
+## Path parameters
+
+TanStack-Router-style `$name` tokens match a single non-empty segment:
+
+```tsx
+routes: [
+  { key: 'report-detail', path: '/reports/$reportId', component: ReportDetailPage },
+  { key: 'report-export', path: '/reports/$reportId/export', component: ReportExportPage },
+],
+```
+
+## Receiving params
+
+Your component receives three props from the dispatcher:
+
+```tsx
+interface PluginRouteProps {
+  /** Path params extracted from the URL. Keys match the `$name` tokens in your path. */
+  params: Record<string, string>
+  /** Always set — every route is scoped to a store. */
+  storeId: string
+  /** URL search-state. Pass to `<ResourceTable searchParams={searchParams} />` so filters
+   *  round-trip through the URL. */
+  searchParams: Record<string, unknown>
+}
+
+function ReportDetailPage({ params, storeId, searchParams }: PluginRouteProps) {
+  const reportId = params.reportId
+  // ...
+}
+```
+
+`searchParams` is typed as `Record<string, unknown>` because the dispatcher can't statically know your page's shape. If you're handing it to `<ResourceTable>`, cast to `ResourceSearch`:
+
+```tsx
+import type { ResourceSearch } from '@spree/dashboard-core'
+
+<ResourceTable searchParams={searchParams as ResourceSearch} ... />
+```
+
+## Permission gating
+
+A `subject` on the route entry renders a 403 fallback (instead of the page) when the user lacks `read` permission:
+
+```tsx
+routes: [{
+  key: 'reports',
+  path: '/reports',
+  component: ReportsPage,
+  subject: 'Spree::Order',
+}],
+```
+
+Always pair this with a matching `subject` on the **nav entry** so users without permission never see the link in the first place. The route subject is the defensive layer for direct URLs.
+
+`subject` is a **registry-route** feature — the dispatcher applies it before rendering. File routes don't pass through the dispatcher, so they gate themselves: check permissions inside the component with `<Can>` or `usePermissions()` from `@spree/dashboard-core` and render a fallback. Either way, this is UX only — the backend still authorizes every API call.
+
+## Layout
+
+Custom routes inherit the dashboard's `_authenticated` + `$storeId` layout (auth guard, sidebar, top bar, etc.) — your component renders inside the `<Outlet />`. Use `<ResourceLayout>` from `@spree/dashboard-ui` to get the same header/main/sidebar grid as core pages:
+
+```tsx
+import { PageHeader } from '@spree/dashboard-core'
+import { ResourceLayout } from '@spree/dashboard-ui'
+
+function ReportsPage() {
+  return (
+    <ResourceLayout
+      header={<PageHeader title="Reports" backTo="dashboard" />}
+      main={<ReportsList />}
+      sidebar={<ReportsFilters />}
+    />
+  )
+}
+```
+
+## Linking to a registry route
+
+Registry routes aren't in the generated route tree, so links to them bypass static checking:
+
+```tsx
+import { Link } from '@tanstack/react-router'
+
+<Link
+  to={'/$storeId/reports/$reportId' as string}
+  params={{ storeId, reportId } as never}
+>
+  View report
+</Link>
+```
+
+The casts bypass TanStack Router's static type-checking (custom routes aren't in the generated route tree, so neither the path nor its params exist as types). Params are passed as a keyed object — each key fills the matching `$name` token.
+
+## Order of operations
+
+Routes register at module-load time. The dispatcher reads from the registry on **every navigation**, so route registration is much more forgiving than nav: even a route registered after first render works as soon as the user navigates to it. The only ordering rule is the usual i18n one — register your translation bundle above any registration that calls `i18n.t(...)` (see [Translations](translations.md)).
+
+## Reference
+
+- [`RouteEntry`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/route-registry.ts) — full type
+- [Catch-all dispatcher source](https://github.com/spree/spree/blob/main/packages/dashboard/src/routes/_authenticated/$storeId/$.tsx) — see how matching works

package/dist/developer/dashboard/customization/slots.md

@@ -0,0 +1,114 @@
+---
+title: Slots
+sidebarTitle: Slots
+description: Inject your own widgets into existing dashboard pages without forking them. Slots are named injection points the dashboard exposes on built-in pages.
+---
+
+A slot is a named injection point in a built-in page. Components registered against a slot render inside it, sorted by `position`, gated by an optional `if` predicate. The host page knows nothing about your widget — it just renders `<Slot name="..." context={...} />` and the slot registry handles the rest.
+
+## Quick example
+
+Render a card with the current user's email in every page's actions dropdown:
+
+```tsx
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { DropdownMenuItem } from '@spree/dashboard-ui'
+
+function UserBadge({ user }: { user?: { email: string } }) {
+  if (!user) return null
+  return <DropdownMenuItem>{user.email}</DropdownMenuItem>
+}
+
+defineDashboardPlugin({
+  slots: {
+    'page.actions_dropdown': [{
+      id: 'my-user-badge',
+      component: UserBadge as never,
+      position: 50,
+    }],
+  },
+})
+```
+
+`page.actions_dropdown` is one of the slots exposed by `<PageHeader>`. See the [Slots catalog](../slots-catalog.md) for the full list and the context shape each slot provides.
+
+## Slot context
+
+The component receives the **slot-specific context** as props — whatever the host page passes via `<Slot name="..." context={{ product, /* etc */ }} />`. The shape varies per slot: `page.actions_dropdown` passes `{ resource }`, `product.form_sidebar` passes `{ product }`, and so on. Each slot's shape is documented in the [Slots catalog](../slots-catalog.md).
+
+For anything beyond the slot's own context — permissions, the current store, the signed-in user — call the hooks inside your component: `usePermissions()`, `useStore()`, `useAuth()` from `@spree/dashboard-core`. (A future release may inject these as ambient props, but today the hooks are the way.)
+
+### Why `as never`?
+
+`defineDashboardPlugin`'s `slots` field is typed as a generic-erased `Record<string, SlotEntry[]>` — the facade can't statically know your slot's context shape, only the host page does. Cast your component to `as never` to satisfy the registry's signature. Your component still receives the right props at runtime; the cast only suppresses the type-system noise.
+
+If you'd rather have full type safety, call `registerSlot` directly with the explicit type parameter:
+
+```tsx
+import { registerSlot } from '@spree/dashboard-core'
+
+interface ProductSlotContext {
+  product: { id: string; brand_id?: string | null }
+}
+
+registerSlot<ProductSlotContext>('product.form_sidebar', {
+  id: 'brand-card',
+  component: ({ product }) => <BrandCard productId={product.id} brandId={product.brand_id} />,
+  position: 50,
+})
+```
+
+## Permission gating
+
+Gate inside the component with `usePermissions()` — return `null` when the user lacks access:
+
+```tsx
+import { usePermissions } from '@spree/dashboard-core'
+
+function AdminOnlyMenuItem() {
+  const { permissions } = usePermissions()
+  if (!permissions.can('manage', 'Spree::User')) return null
+  return <DropdownMenuItem>…</DropdownMenuItem>
+}
+```
+
+The entry-level `if` predicate also exists, but it only receives the slot's own context (the same props your component gets) — use it to skip an entry based on the host page's data, e.g. `if: ({ product }) => !!product.brand_id`. When it returns `false`, the entry is skipped entirely (no DOM nodes mounted).
+
+## Binding to the host form
+
+Slots on form pages (product, category, store settings — see the [slots catalog](../slots-catalog.md#detail-page-form-slots) for which) render **inside the page's `<form>`** and expose its react-hook-form instance. A widget can register inputs against it with `useHostForm()` — they hydrate from the API, flip the Save button on change, and persist in the page's own save, with no save logic in the widget:
+
+```tsx
+import { useHostForm } from '@spree/dashboard-core'
+
+function TechSpecsCard() {
+  const form = useHostForm<{ tech_specs: string }>()
+  return <Textarea {...form.register('tech_specs')} />
+}
+```
+
+Pair it with a `formFields` registration so the field hydrates and ships in the payload — the full walkthrough is the [custom form field recipe](../recipes/custom-form-field.md). Never render your own `<form>` inside a slot on these pages: HTML forbids nested forms, and the host form already owns submission. On pages without a host form (orders, customers), `useHostForm()` throws — use `useOptionalHostForm()` and fall back to your own state + API save.
+
+## Position
+
+`position` controls render order within the slot. Built-in entries (when the dashboard ships any) use 100/200/300 to leave gaps. Default is 100, so two entries with no explicit position render in registration order.
+
+## Removing or updating an entry
+
+```ts
+import { removeSlot, updateSlot } from '@spree/dashboard-core'
+
+removeSlot('product.form_sidebar', 'brand-card')
+updateSlot('product.form_sidebar', 'brand-card', { position: 999 })
+```
+
+These mirror the registry's mutator pattern — useful for development-mode toggles, or for unregistering a third-party slot entry from your host.
+
+## Order of operations
+
+Like nav, slot entries register at module-load time and the `<Slot>` consumer re-renders via `useSyncExternalStore` when entries change. Late registration works; the slot just lights up the next render.
+
+## Reference
+
+- [Slots catalog](../slots-catalog.md) — every named slot the dashboard exposes
+- [`SlotEntry`, `SlotAmbientContext`, `registerSlot`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/slot-registry.ts) — full registry source

package/dist/developer/dashboard/customization/tables.md

@@ -0,0 +1,167 @@
+---
+title: Tables
+sidebarTitle: Tables
+description: Add, change, or remove columns on built-in list tables (products, orders, customers, …), or define a table for your own resource.
+---
+
+Every list page in the dashboard renders through `<ResourceTable>`, which reads its column definitions from a **table registry** keyed by table name (`products`, `orders`, `customers`, …). That gives you two levers:
+
+1. **Extend a built-in table** — add, patch, or remove columns (including their filters) without forking the page.
+2. **Define your own table** — declare columns once with `defineTable`, then render them with `<ResourceTable>` on your own page.
+
+## Add a column to a built-in table
+
+Imperatively, from `src/plugins.ts` (or a plugin entry):
+
+```tsx
+import { tables } from '@spree/dashboard-core'
+
+tables.products.addColumn({
+  key: 'brand',
+  label: 'Brand',
+  default: true,                          // visible out of the box
+  render: (product) => product.brand?.name ?? '—',
+})
+```
+
+Or declaratively through `defineDashboardPlugin` — same effect, grouped with your other extensions:
+
+```tsx
+defineDashboardPlugin({
+  tables: {
+    products: {
+      add: [{ key: 'brand', label: 'Brand', default: true, render: (p) => p.brand?.name ?? '—' }],
+    },
+  },
+})
+```
+
+New columns append after the existing ones. Column keys must be unique per table — adding a duplicate throws with a message telling you to use `updateColumn` instead.
+
+> **NOTE:** **Timing is taken care of.** Built-in tables register when their page first loads, which may be after your code runs. Mutations against a table that isn't registered yet are queued and replayed the moment it appears — and mutations against a table that never registers simply never fire. That means extending an optional feature's table is safe even when that feature isn't installed.
+
+## Modify or remove built-in columns
+
+```tsx
+tables.products.updateColumn('price', { label: 'Retail price' })
+tables.products.removeColumn('cost_price')
+```
+
+Declaratively:
+
+```tsx
+defineDashboardPlugin({
+  tables: {
+    products: {
+      update: { price: { label: 'Retail price' } },
+      remove: ['cost_price'],
+    },
+  },
+})
+```
+
+`updateColumn` patches shallowly — pass only the fields you want to change. `removeColumn` of an unknown key is a no-op.
+
+## Column definition
+
+```ts
+interface ColumnDef<T> {
+  key: string                       // unique per table; also the default Ransack sort/filter attribute
+  label: string                     // header text — use i18n.t(...) for translated labels
+  render?: (row: T) => ReactNode    // cell renderer; defaults to rendering row[key] as text
+  className?: string                // cell class (e.g. 'text-right tabular-nums')
+  default?: boolean                 // part of the visible column set out of the box
+  sortable?: boolean                // header toggles Ransack sort on the attribute
+  filterable?: boolean              // appears in the filter panel
+  ransackAttribute?: string         // backend attribute when it differs from key
+  displayable?: boolean             // set false for filter-only entries (no column rendered)
+}
+```
+
+### Filter types
+
+When a column is `filterable`, `filterType` decides which filter UI it gets:
+
+| `filterType` | Filter UI | Extra fields |
+|---|---|---|
+| `'string'` (default) | Text input with contains/equals operators | — |
+| `'boolean'` | Yes/no toggle | — |
+| `'number'`, `'currency'` | Numeric comparisons | — |
+| `'date'` | Date range picker (store-timezone aware) | — |
+| `'enum'` | Fixed option list | `filterOptions: [{ value, label }]` (required) |
+| `'resource'` | Multi-select autocomplete against another resource | `filterResource` (required) — `queryKey`, `search`, `hydrate`, `getOptionLabel` |
+| `'tags'` | Tag autocomplete | `taggableType` (required), e.g. `'Spree::Product'` |
+
+A `'resource'` filter searches as the admin types and resolves already-selected IDs back to labels on page reload:
+
+```tsx
+tables.products.addColumn({
+  key: 'brand_id',
+  label: 'Brand',
+  displayable: false,          // filter only — no column in the table
+  filterable: true,
+  filterType: 'resource',
+  filterResource: {
+    queryKey: 'brands',
+    search: (query) => brandsClient.list({ q: { name_cont: query } }),
+    hydrate: (ids) => brandsClient.list({ q: { id_in: ids } }),
+    getOptionLabel: (brand) => brand.name,
+  },
+})
+```
+
+Filtering and sorting are executed by the Admin API (Ransack), not in the browser — `key` (or `ransackAttribute`) must be a filterable/sortable attribute the API allows.
+
+## Define your own table
+
+For your own list page, declare the table once — typically right next to your `defineDashboardPlugin` call:
+
+```tsx
+import { defineTable } from '@spree/dashboard-core'
+
+defineTable<Brand>('brands', {
+  title: 'Brands',
+  searchParam: 'search',
+  searchPlaceholder: 'Search by name…',
+  defaultSort: { field: 'name', direction: 'asc' },
+  emptyMessage: 'No brands yet',
+  columns: [
+    { key: 'name', label: 'Name', sortable: true, filterable: true, default: true },
+    { key: 'products_count', label: 'Products', default: true, className: 'text-right tabular-nums' },
+    { key: 'created_at', label: 'Created', sortable: true, default: false },
+  ],
+})
+```
+
+Then render it from your page component:
+
+```tsx
+<ResourceTable<Brand>
+  tableKey="brands"          // which table definition to read
+  queryKey="brands"          // TanStack Query cache key
+  queryFn={(params) => brandsClient.list(params)}
+  searchParams={searchParams}
+/>
+```
+
+`<ResourceTable>` handles pagination, sorting, the filter panel, column visibility, and URL round-tripping of all of it. See [Routes](routes.md) for the page around it — the [example Brands plugin](https://github.com/spree/spree/tree/main/packages/dashboard-plugin-example) shows the complete wiring.
+
+## Bulk actions, row actions, reordering
+
+These are **props on `<ResourceTable>`**, composed by the page that renders the table:
+
+```tsx
+<ResourceTable<Brand>
+  // …
+  bulkActions={[{ key: 'archive', label: 'Archive selected', onSelect: async (rows) => { /* … */ } }]}
+  rowActions={(row) => <BrandRowMenu brand={row} />}
+/>
+```
+
+Use them freely on your own pages. They are **not registry-driven** — a plugin can't inject bulk or row actions into a built-in page's table today. If a built-in page needs an injection point, that's what [slots](slots.md) are for.
+
+## Reference
+
+- [`table-registry.ts`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/table-registry.ts) — `defineTable`, `tables`, the full `ColumnDef` union
+- [`<ResourceTable>`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/components/resource-table.tsx) — props for bulk actions, row actions, drag-reordering
+- [Example Brands plugin](https://github.com/spree/spree/tree/main/packages/dashboard-plugin-example) — a real `defineTable` + `<ResourceTable>` + products-column extension

package/dist/developer/dashboard/customization/translations.md

@@ -0,0 +1,96 @@
+---
+title: Translations
+sidebarTitle: Translations
+description: Add your own i18n strings to the dashboard so labels, validation messages, and notifications respect the admin's chosen locale.
+---
+
+The dashboard uses [i18next](https://www.i18next.com/) with the `react-i18next` bindings. All strings live in i18next's default `translation` namespace, with every key under a top-level `admin.` prefix (`admin.nav.orders`, `admin.fields.<resource>.<attribute>.label`, …). You register your strings into the same namespace with the same prefix so they look and feel native.
+
+## Add translations
+
+```ts
+import { i18n } from '@spree/dashboard-core'
+
+i18n.addResourceBundle('en', 'translation', {
+  admin: {
+    reports: {
+      title: 'Reports',
+      empty: 'No reports yet.',
+    },
+    fields: {
+      report: {
+        name: { label: 'Report name', placeholder: 'e.g. Q4 sales by region' },
+      },
+    },
+  },
+}, /* deep */ true, /* overwrite */ true)
+```
+
+With `deep: true` your keys merge into the existing tree instead of replacing it; `overwrite: true` lets your bundle win where a key genuinely collides (this is what the framework and the official plugins use). Note the `admin` wrapper is part of the **bundle contents** — the namespace argument stays `'translation'`.
+
+Repeat per locale:
+
+```ts
+
+
+
+for (const [locale, bundle] of Object.entries({ en, fr, de })) {
+  i18n.addResourceBundle(locale, 'translation', bundle, true, true)
+}
+```
+
+## Use them
+
+```tsx
+import { useTranslation } from 'react-i18next'
+
+function ReportsHeader() {
+  const { t } = useTranslation()
+  return <h1>{t('admin.reports.title')}</h1>
+}
+```
+
+In a registry entry, pass the key directly:
+
+```ts
+nav.add({
+  key: 'reports',
+  label: i18n.t('admin.reports.title'),
+  path: '/reports',
+})
+```
+
+Note: `i18n.t` resolves at the call site, so the label is a snapshot taken at registration time. Registry entries store plain strings — if the user switches language without a reload, registered labels keep their old language until re-registered. Components that call `useTranslation()` re-render on locale change; registry labels don't. If that matters for your entry, re-register it on the i18n `languageChanged` event.
+
+## Field-key convention
+
+Form labels, placeholders, and help text follow a two-level key convention:
+
+1. `admin.fields.<resource>.<attribute>.<facet>` — resource-specific, e.g. `admin.fields.report.name.label`
+2. `admin.fields.<attribute>.<facet>` — cross-resource defaults, e.g. `admin.fields.name.label`
+
+Components call `t()` with these keys explicitly — pick the resource-scoped form for labels that differ per resource, and reuse the shared `admin.fields.<attribute>.<facet>` keys the framework already ships for common attributes (`name`, `email`, `created_at`, `storefront_visible`, …).
+
+In dev mode, missing keys log to the console (in production a missing key falls back to a humanized version of the attribute name).
+
+## Server-side error messages
+
+The `mapSpreeErrorsToForm` helper routes 422 responses onto `form.formState.errors`, but the messages themselves are the **server's strings, verbatim** — `{ "name": ["can't be blank"] }` becomes a field error reading "can't be blank". To localize validation messages, configure the locale on the backend (Rails i18n translates ActiveRecord error messages); the dashboard displays whatever the API returns.
+
+## Order of operations
+
+Register translations **before** any code that calls `i18n.t()` at module-load time (registry labels, table titles, etc.). The framework's own bundles are loaded before your code runs, so the pattern is simply — top of the file:
+
+```tsx
+// src/plugins.ts (same pattern in a plugin package's entry module)
+import { defineDashboardPlugin, i18n } from '@spree/dashboard-core'
+
+i18n.addResourceBundle('en', 'translation', en, true, true)  // ① translations first
+
+defineDashboardPlugin({ /* ② registrations may now use i18n.t(...) */ })
+```
+
+## Reference
+
+- [i18next docs](https://www.i18next.com/) — full API
+- The dashboard's own bundle: [`packages/dashboard/src/locales/en.json`](https://github.com/spree/spree/blob/main/packages/dashboard/src/locales/en.json) — copy keys for forms, status badges, validation messages, etc.