create-brainerce-store 1.72.0 → 1.74.0

package/templates/nextjs/base/TRANSLATIONS.md

@@ -1,207 +1,207 @@
-# Multi-language storefronts
-
-Your scaffolded Brainerce store is already wired for multi-language out of the box. This doc explains the moving parts so you can customize them — you do **not** need to write per-locale fetch code; the SDK + middleware do it for you.
-
-## Status check
-
-```typescript
-const store = await client.getStoreInfo();
-store.i18n?.enabled; // → true / false
-store.i18n?.defaultLocale; // → e.g. "en"
-store.i18n?.supportedLocales; // → e.g. ["en", "he"]
-```
-
-If `i18n.enabled` is `false` or only one locale is supported, the rest of this doc is a no-op — the app behaves as a single-language store.
-
-## URL strategy: "as-needed" locale prefix
-
-This template uses the as-needed pattern (the most common approach for SEO):
-
-| URL            | Locale  | Notes                                             |
-| -------------- | ------- | ------------------------------------------------- |
-| `/`            | default | Clean URL — no `/en` prefix on the default locale |
-| `/products`    | default | Same                                              |
-| `/he`          | Hebrew  | Secondary locales get a path prefix               |
-| `/he/products` | Hebrew  | Same                                              |
-
-The middleware (`src/middleware.ts`) handles two transitions:
-
-1. `/{defaultLocale}/X` → 308 redirect to `/X` (canonicalize away the redundant prefix)
-2. `/X` → internal rewrite to `/{defaultLocale}/X` so the Next.js `[locale]` route segment still resolves
-
-Every response carries an `x-locale` header so Server Components can read the resolved locale via `headers()`.
-
-## How translated content shows up on the page
-
-You write **one** `fetch` and it works for every language.
-
-```tsx
-// src/app/[locale]/products/[slug]/page.tsx
-import { getServerClient } from '@/core/lib/server-client';
-import { headers } from 'next/headers';
-
-export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
-  const { slug } = await params;
-  const locale = (await headers()).get('x-locale') ?? undefined;
-  const client = getServerClient();
-  client.setLocale(locale);
-
-  const product = await client.getProductBySlug(slug);
-  // product.name, product.description, product.categories[].name, modifier groups,
-  // metafield labels — all already translated by the server.
-
-  return <ProductDetail product={product} />;
-}
-```
-
-The `StoreProvider` (`src/providers/store-provider.tsx`) calls `client.setLocale(locale)` on the client side, so React Server Components and Client Components both get translated content.
-
-## What's translatable (full list)
-
-| Entity                  | Fields                                                      |
-| ----------------------- | ----------------------------------------------------------- |
-| **Product**             | `name`, `description`, `slug`, `seoTitle`, `seoDescription` |
-| **ProductVariant**      | `name`                                                      |
-| **Category**            | `name`                                                      |
-| **Brand**               | `name`                                                      |
-| **Tag**                 | `name`                                                      |
-| **Attribute**           | `name` (e.g. "Color")                                       |
-| **AttributeOption**     | `name` (e.g. "Red")                                         |
-| **ModifierGroup**       | `name`, `description` (e.g. "Toppings" → "תוספות")          |
-| **Modifier**            | `name`, `description` (e.g. "Olives" → "זיתים")             |
-| **ProductMetafield**    | `value` (free-text custom field values)                     |
-| **MetafieldDefinition** | `name`, `description` (custom-field labels)                 |
-| **BundleOffer**         | `name`, `description` (bundle marketing label)              |
-| **OrderBumpConfig**     | `title`, `description` (bump headline at checkout)          |
-| **DiscountRule**        | `name`, `description` (rule label, used in banners)         |
-| **ContactForm**         | `name`, `description`, `submitButton`, `successMessage`     |
-| **ContactFormField**    | `label`, `placeholder`, `helpText`                          |
-
-You never overlay translations yourself — the SDK does it on every request.
-
-## RTL (Hebrew, Arabic, Persian, Urdu, Yiddish)
-
-`src/i18n.ts` exports `getDirection(locale)` that delegates to the SDK's `getDirectionForLocale()`. The layout uses it on `<html dir={…}>`:
-
-```tsx
-// src/app/[locale]/layout.tsx
-import { getDirection } from '@/i18n';
-
-export default async function LocaleLayout({ children, params }: Props) {
-  const { locale } = await params;
-  const dir = getDirection(locale);
-  return (
-    <html lang={locale} dir={dir}>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
-This automatically reverses flexbox row order — **do not add `flex-row-reverse`** on top, that's a double-swap. **Do** swap directional icons (chevrons, arrows) using `useDirection()` from `@radix-ui/react-direction`.
-
-Use logical Tailwind classes (`ms-*`/`me-*` for margin, `ps-*`/`pe-*` for padding, `start-*`/`end-*` for positioning) instead of physical ones (`ml-*`, `mr-*`, `left-*`, `right-*`) so the layout mirrors automatically.
-
-## Language switcher
-
-```tsx
-'use client';
-import { useStore } from '@/providers/store-provider';
-import Link from 'next/link';
-import { useParams, usePathname } from 'next/navigation';
-
-export function LanguageSwitcher() {
-  const { storeInfo } = useStore();
-  const pathname = usePathname();
-  const { locale: current } = useParams<{ locale?: string }>();
-
-  if (!storeInfo?.i18n?.enabled) return null;
-  const locales = storeInfo.i18n.supportedLocales;
-  const defaultLocale = storeInfo.i18n.defaultLocale;
-
-  return (
-    <nav className="flex gap-2">
-      {locales.map((loc) => {
-        const isCurrent = (current ?? defaultLocale) === loc;
-        const href = loc === defaultLocale ? pathname : `/${loc}${pathname}`;
-        return (
-          <Link key={loc} href={href} className={isCurrent ? 'font-bold' : ''}>
-            {loc.toUpperCase()}
-          </Link>
-        );
-      })}
-    </nav>
-  );
-}
-```
-
-The merchant configures supported locales in `Dashboard → Settings → Languages`. Your switcher reads them from `storeInfo.i18n.supportedLocales` — never hardcode a list.
-
-## SEO: per-locale slugs and hreflang
-
-When the merchant translates a product's `slug`, every locale gets its own URL (e.g. `/cheese-pizza` and `/he/פיצה-גבינה`). Pull all alternates in one call for the `<head>`:
-
-```tsx
-const alternates = await client.getProductAlternates(product.id);
-// → [{ locale: 'en', slug: 'cheese-pizza' }, { locale: 'he', slug: 'פיצה-גבינה' }]
-
-// In generateMetadata:
-return {
-  alternates: {
-    languages: Object.fromEntries(
-      alternates.map((a) => [a.locale, `/${a.locale}/products/${a.slug}`])
-    ),
-  },
-};
-```
-
-## Promotional surfaces: bundles, bumps, discount banners
-
-The same overlay applies to every promotional surface, so you don't need locale-aware code:
-
-```tsx
-// Cart bundles (cross-sell), locale-aware automatically:
-const cart = await client.getCart(cartId);
-cart.bundles[0].name; // "ארוחת צהריים" (bundle's own label)
-cart.bundles[0].offeredProducts[0].name; // "פיצה גבינה" (each offered product)
-
-// Order bumps at checkout. `getCheckoutBumps` takes a CHECKOUT id, not a cart id:
-const { bumps } = await client.getCheckoutBumps(checkoutId);
-bumps[0].title; // translated bump headline (or merchant override)
-bumps[0].bumpProduct.name; // translated product name
-
-// Adding or removing a bump takes the CART id plus the bump config id
-// (bumps[i].id). Pass a variantId when bumps[i].requiresVariantSelection:
-await client.addOrderBump(cartId, bumps[0].id, selectedVariantId);
-await client.removeOrderBump(cartId, bumps[0].id);
-
-// Discount-rule banners. The API returns ready-to-render banner text, not the
-// rule object: DiscountBanner is { ruleId, text, type }, so there is no `name`
-// and no `displayConfig` to compose yourself.
-const banners = await client.getDiscountBanners();
-banners[0].text; // translated banner copy
-```
-
-## How merchants populate translations
-
-For background — your storefront doesn't need to call these endpoints, but knowing the merchant flow helps when debugging unexpectedly-empty translations:
-
-- **Per-row overlay** on every taxonomy/product list page in the dashboard.
-- **Inside the entity create/edit modal** — a `LocaleSelector` in the header + "Translate with AI" button populates target-locale fields (Products, Attributes, Modifier Groups, Modifiers, Custom Fields).
-- **Translate icon button** on bundle / order-bump rows (`/products/.../offers`) and on discount-rule rows (`/discount-rules`) opens a standalone translation modal with one-click AI.
-- **Bulk** — select N rows on a list page → toolbar action "Translate to Hebrew" enqueues an AI translation job for everything selected (including children, e.g. all modifiers under selected groups).
-
-Translations are persisted via the dashboard-only endpoint `PUT /api/stores/:storeId/translations/:entityType/:entityId/:locale`. The storefront SDK never calls this — it only consumes the overlay on read.
-
-## Troubleshooting
-
-| Symptom                                                        | Likely cause                                        | Fix                                                                               |
-| -------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `product.name` is English even though locale is `he`           | Store doesn't have `he` in `supportedLocales`       | Add the locale in `Dashboard → Settings → Languages`                              |
-| Some fields translate, others don't                            | Merchant translated subset                          | Per-field fallback is by design — fill the rest in dashboard                      |
-| Layout broken in Hebrew                                        | Missing `<html dir="rtl">`                          | Use `getDirection(locale)` in the layout                                          |
-| Modifier names in default language but product name translates | Merchant translated `Product` only                  | Bulk translate on `/products/modifier-groups` covers groups + all their modifiers |
-| Custom-field label "Warranty" doesn't translate                | Merchant didn't translate the `MetafieldDefinition` | Per-row "Translate" on `/products/custom-fields`                                  |
-| Bundle name "Summer Sale" stays in English in Hebrew cart      | Merchant didn't translate the `BundleOffer` itself  | Click the Languages icon on the bundle row in `/products/.../offers`              |
-
-See [the Brainerce docs](https://brainerce.com/docs/concepts/translations) for the canonical reference.
+# Multi-language storefronts
+
+Your scaffolded Brainerce store is already wired for multi-language out of the box. This doc explains the moving parts so you can customize them — you do **not** need to write per-locale fetch code; the SDK + middleware do it for you.
+
+## Status check
+
+```typescript
+const store = await client.getStoreInfo();
+store.i18n?.enabled; // → true / false
+store.i18n?.defaultLocale; // → e.g. "en"
+store.i18n?.supportedLocales; // → e.g. ["en", "he"]
+```
+
+If `i18n.enabled` is `false` or only one locale is supported, the rest of this doc is a no-op — the app behaves as a single-language store.
+
+## URL strategy: "as-needed" locale prefix
+
+This template uses the as-needed pattern (the most common approach for SEO):
+
+| URL            | Locale  | Notes                                             |
+| -------------- | ------- | ------------------------------------------------- |
+| `/`            | default | Clean URL — no `/en` prefix on the default locale |
+| `/products`    | default | Same                                              |
+| `/he`          | Hebrew  | Secondary locales get a path prefix               |
+| `/he/products` | Hebrew  | Same                                              |
+
+The middleware (`src/middleware.ts`) handles two transitions:
+
+1. `/{defaultLocale}/X` → 308 redirect to `/X` (canonicalize away the redundant prefix)
+2. `/X` → internal rewrite to `/{defaultLocale}/X` so the Next.js `[locale]` route segment still resolves
+
+Every response carries an `x-locale` header so Server Components can read the resolved locale via `headers()`.
+
+## How translated content shows up on the page
+
+You write **one** `fetch` and it works for every language.
+
+```tsx
+// src/app/[locale]/products/[slug]/page.tsx
+import { getServerClient } from '@/core/lib/server-client';
+import { headers } from 'next/headers';
+
+export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const locale = (await headers()).get('x-locale') ?? undefined;
+  const client = getServerClient();
+  client.setLocale(locale);
+
+  const product = await client.getProductBySlug(slug);
+  // product.name, product.description, product.categories[].name, modifier groups,
+  // metafield labels — all already translated by the server.
+
+  return <ProductDetail product={product} />;
+}
+```
+
+The `StoreProvider` (`src/providers/store-provider.tsx`) calls `client.setLocale(locale)` on the client side, so React Server Components and Client Components both get translated content.
+
+## What's translatable (full list)
+
+| Entity                  | Fields                                                      |
+| ----------------------- | ----------------------------------------------------------- |
+| **Product**             | `name`, `description`, `slug`, `seoTitle`, `seoDescription` |
+| **ProductVariant**      | `name`                                                      |
+| **Category**            | `name`                                                      |
+| **Brand**               | `name`                                                      |
+| **Tag**                 | `name`                                                      |
+| **Attribute**           | `name` (e.g. "Color")                                       |
+| **AttributeOption**     | `name` (e.g. "Red")                                         |
+| **ModifierGroup**       | `name`, `description` (e.g. "Toppings" → "תוספות")          |
+| **Modifier**            | `name`, `description` (e.g. "Olives" → "זיתים")             |
+| **ProductMetafield**    | `value` (free-text custom field values)                     |
+| **MetafieldDefinition** | `name`, `description` (custom-field labels)                 |
+| **BundleOffer**         | `name`, `description` (bundle marketing label)              |
+| **OrderBumpConfig**     | `title`, `description` (bump headline at checkout)          |
+| **DiscountRule**        | `name`, `description` (rule label, used in banners)         |
+| **ContactForm**         | `name`, `description`, `submitButton`, `successMessage`     |
+| **ContactFormField**    | `label`, `placeholder`, `helpText`                          |
+
+You never overlay translations yourself — the SDK does it on every request.
+
+## RTL (Hebrew, Arabic, Persian, Urdu, Yiddish)
+
+`src/i18n.ts` exports `getDirection(locale)` that delegates to the SDK's `getDirectionForLocale()`. The layout uses it on `<html dir={…}>`:
+
+```tsx
+// src/app/[locale]/layout.tsx
+import { getDirection } from '@/i18n';
+
+export default async function LocaleLayout({ children, params }: Props) {
+  const { locale } = await params;
+  const dir = getDirection(locale);
+  return (
+    <html lang={locale} dir={dir}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+This automatically reverses flexbox row order — **do not add `flex-row-reverse`** on top, that's a double-swap. **Do** swap directional icons (chevrons, arrows) using `useDirection()` from `@radix-ui/react-direction`.
+
+Use logical Tailwind classes (`ms-*`/`me-*` for margin, `ps-*`/`pe-*` for padding, `start-*`/`end-*` for positioning) instead of physical ones (`ml-*`, `mr-*`, `left-*`, `right-*`) so the layout mirrors automatically.
+
+## Language switcher
+
+```tsx
+'use client';
+import { useStore } from '@/providers/store-provider';
+import Link from 'next/link';
+import { useParams, usePathname } from 'next/navigation';
+
+export function LanguageSwitcher() {
+  const { storeInfo } = useStore();
+  const pathname = usePathname();
+  const { locale: current } = useParams<{ locale?: string }>();
+
+  if (!storeInfo?.i18n?.enabled) return null;
+  const locales = storeInfo.i18n.supportedLocales;
+  const defaultLocale = storeInfo.i18n.defaultLocale;
+
+  return (
+    <nav className="flex gap-2">
+      {locales.map((loc) => {
+        const isCurrent = (current ?? defaultLocale) === loc;
+        const href = loc === defaultLocale ? pathname : `/${loc}${pathname}`;
+        return (
+          <Link key={loc} href={href} className={isCurrent ? 'font-bold' : ''}>
+            {loc.toUpperCase()}
+          </Link>
+        );
+      })}
+    </nav>
+  );
+}
+```
+
+The merchant configures supported locales in `Dashboard → Settings → Languages`. Your switcher reads them from `storeInfo.i18n.supportedLocales` — never hardcode a list.
+
+## SEO: per-locale slugs and hreflang
+
+When the merchant translates a product's `slug`, every locale gets its own URL (e.g. `/cheese-pizza` and `/he/פיצה-גבינה`). Pull all alternates in one call for the `<head>`:
+
+```tsx
+const alternates = await client.getProductAlternates(product.id);
+// → [{ locale: 'en', slug: 'cheese-pizza' }, { locale: 'he', slug: 'פיצה-גבינה' }]
+
+// In generateMetadata:
+return {
+  alternates: {
+    languages: Object.fromEntries(
+      alternates.map((a) => [a.locale, `/${a.locale}/products/${a.slug}`])
+    ),
+  },
+};
+```
+
+## Promotional surfaces: bundles, bumps, discount banners
+
+The same overlay applies to every promotional surface, so you don't need locale-aware code:
+
+```tsx
+// Cart bundles (cross-sell), locale-aware automatically:
+const cart = await client.getCart(cartId);
+cart.bundles[0].name; // "ארוחת צהריים" (bundle's own label)
+cart.bundles[0].offeredProducts[0].name; // "פיצה גבינה" (each offered product)
+
+// Order bumps at checkout. `getCheckoutBumps` takes a CHECKOUT id, not a cart id:
+const { bumps } = await client.getCheckoutBumps(checkoutId);
+bumps[0].title; // translated bump headline (or merchant override)
+bumps[0].bumpProduct.name; // translated product name
+
+// Adding or removing a bump takes the CART id plus the bump config id
+// (bumps[i].id). Pass a variantId when bumps[i].requiresVariantSelection:
+await client.addOrderBump(cartId, bumps[0].id, selectedVariantId);
+await client.removeOrderBump(cartId, bumps[0].id);
+
+// Discount-rule banners. The API returns ready-to-render banner text, not the
+// rule object: DiscountBanner is { ruleId, text, type }, so there is no `name`
+// and no `displayConfig` to compose yourself.
+const banners = await client.getDiscountBanners();
+banners[0].text; // translated banner copy
+```
+
+## How merchants populate translations
+
+For background — your storefront doesn't need to call these endpoints, but knowing the merchant flow helps when debugging unexpectedly-empty translations:
+
+- **Per-row overlay** on every taxonomy/product list page in the dashboard.
+- **Inside the entity create/edit modal** — a `LocaleSelector` in the header + "Translate with AI" button populates target-locale fields (Products, Attributes, Modifier Groups, Modifiers, Custom Fields).
+- **Translate icon button** on bundle / order-bump rows (`/products/.../offers`) and on discount-rule rows (`/discount-rules`) opens a standalone translation modal with one-click AI.
+- **Bulk** — select N rows on a list page → toolbar action "Translate to Hebrew" enqueues an AI translation job for everything selected (including children, e.g. all modifiers under selected groups).
+
+Translations are persisted via the dashboard-only endpoint `PUT /api/stores/:storeId/translations/:entityType/:entityId/:locale`. The storefront SDK never calls this — it only consumes the overlay on read.
+
+## Troubleshooting
+
+| Symptom                                                        | Likely cause                                        | Fix                                                                               |
+| -------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `product.name` is English even though locale is `he`           | Store doesn't have `he` in `supportedLocales`       | Add the locale in `Dashboard → Settings → Languages`                              |
+| Some fields translate, others don't                            | Merchant translated subset                          | Per-field fallback is by design — fill the rest in dashboard                      |
+| Layout broken in Hebrew                                        | Missing `<html dir="rtl">`                          | Use `getDirection(locale)` in the layout                                          |
+| Modifier names in default language but product name translates | Merchant translated `Product` only                  | Bulk translate on `/products/modifier-groups` covers groups + all their modifiers |
+| Custom-field label "Warranty" doesn't translate                | Merchant didn't translate the `MetafieldDefinition` | Per-row "Translate" on `/products/custom-fields`                                  |
+| Bundle name "Summer Sale" stays in English in Hebrew cart      | Merchant didn't translate the `BundleOffer` itself  | Click the Languages icon on the bundle row in `/products/.../offers`              |
+
+See [the Brainerce docs](https://brainerce.com/docs/concepts/translations) for the canonical reference.