@usequeek/theme-kit 0.1.16 → 0.1.18

package/tests/theme-strings-client.test.tsx

@@ -0,0 +1,182 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import type { JSX, ReactNode } from 'react';
+import { StorefrontProvider, useThemeStrings } from '../provider';
+import { ThemeMount } from '../theme-mount';
+import { DefaultCartShell } from '../components/cart/default-cart-shell';
+import { defaultThemeStrings, t as translate, type ThemeStringsDictionary } from '../strings/theme-strings';
+import type { CartItem } from '../types/cart';
+import type { ThemeModule } from '../types/theme';
+
+const FR_STRINGS: ThemeStringsDictionary = {
+  cart: {
+    title: 'Votre panier',
+    empty: { message: 'Votre panier est vide.', browse: 'Voir les produits' },
+    summary: { title: 'Résumé de commande' },
+  },
+};
+
+function render(
+  children: ReactNode,
+  options?: { locale?: string | null; strings?: ThemeStringsDictionary | ThemeStringsDictionary[] | null },
+): string {
+  return renderToStaticMarkup(
+    <StorefrontProvider
+      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      config={{} as never}
+      menus={[]}
+      {...(options?.locale !== undefined ? { locale: options.locale } : {})}
+      {...(options?.strings !== undefined ? { strings: options.strings } : {})}
+    >
+      {children}
+    </StorefrontProvider>,
+  );
+}
+
+function Title(): JSX.Element {
+  const t = useThemeStrings();
+  return <h1>{t('cart.title')}</h1>;
+}
+
+describe('client surface: StorefrontProvider strings + useThemeStrings (decision 4b)', () => {
+  it('renders the active locale through the hook', () => {
+    expect(render(<Title />, { locale: 'fr', strings: FR_STRINGS })).toContain('<h1>Votre panier</h1>');
+  });
+
+  it('falls back per key to the English default VALUE', () => {
+    // `cart.checkout.action` is absent from the FR pack: English value, never the key.
+    function Action(): JSX.Element {
+      const t = useThemeStrings();
+      return <span>{t('cart.checkout.action')}</span>;
+    }
+    const html = render(<Action />, { locale: 'fr', strings: FR_STRINGS });
+    expect(html).toContain('<span>Checkout</span>');
+    expect(html).not.toContain('cart.checkout.action');
+  });
+
+  it('is a no-op when the prop is absent (backward compat: English as today)', () => {
+    expect(render(<Title />)).toContain('<h1>Your cart</h1>');
+  });
+
+  it('matches explicit English defaults exactly (prop changes nothing when absent)', () => {
+    const implicit = render(<Title />);
+    const explicit = render(<Title />, { strings: defaultThemeStrings });
+    expect(implicit).toBe(explicit);
+  });
+
+  it('throws outside a provider, like every other kit hook', () => {
+    expect(() => renderToStaticMarkup(<Title />)).toThrow(
+      'useThemeStrings must be used within StorefrontProvider',
+    );
+  });
+});
+
+describe('client surface through ThemeMount', () => {
+  function Header(): JSX.Element {
+    const t = useThemeStrings();
+    return <header>{t('cart.title')}</header>;
+  }
+
+  const stubTheme = {
+    Layout: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+    Header,
+    Footer: () => <footer />,
+    blocks: {},
+    getHeader: () => Header,
+    getFooter: () => (() => <footer />),
+    getBlock: () => (() => null),
+    pages: {},
+    manifest: { name: 'stub', slug: 'stub', description: '', version: '0' },
+  } as unknown as ThemeModule;
+
+  it('reaches themes mounted by ThemeMount', () => {
+    const html = render(
+      <ThemeMount
+        theme={stubTheme}
+        headerProps={{ menu: [], announcement: null }}
+        footerProps={{}}
+      >
+        <p>page</p>
+      </ThemeMount>,
+      { locale: 'fr', strings: FR_STRINGS },
+    );
+    expect(html).toContain('<header>Votre panier</header>');
+  });
+});
+
+describe('migrated DefaultCartShell (identical English output)', () => {
+  const item: CartItem = {
+    id: 'li-1',
+    product_id: 'p-1',
+    shop_id: 's-1',
+    title: 'Egusi Soup',
+    image: null,
+    unit_price: 5000,
+    quantity: 2,
+    addons: [],
+  };
+
+  const noop = (): void => {};
+
+  it('empty state renders the legacy literals with no strings prop', () => {
+    const html = render(
+      <DefaultCartShell
+        items={[]}
+        currency="NGN"
+        total={0}
+        empty
+        onIncrease={noop}
+        onDecrease={noop}
+        onRemove={noop}
+      />,
+    );
+    expect(html).toContain('Your cart</h1>');
+    expect(html).toContain('Your cart is empty.');
+    expect(html).toContain('Browse products');
+  });
+
+  it('populated state interpolates through t() with identical text', () => {
+    const html = render(
+      <DefaultCartShell
+        items={[item]}
+        currency="NGN"
+        total={10000}
+        empty={false}
+        onIncrease={noop}
+        onDecrease={noop}
+        onRemove={noop}
+      />,
+    );
+    expect(html).toContain('each</span>');
+    expect(html).toContain('aria-label="Decrease Egusi Soup"');
+    expect(html).toContain('aria-label="Increase Egusi Soup"');
+    expect(html).toContain('aria-label="Remove Egusi Soup"');
+    expect(html).toContain('Order summary');
+    expect(html).toContain('Add order note');
+    // The note textarea (with its placeholder) renders only after the toggle
+    // opens it, so its key is asserted directly: same dictionary, same output.
+    expect(translate([defaultThemeStrings], 'cart.note.toggle')).toBe('Add order note');
+    expect(translate([defaultThemeStrings], 'cart.note.placeholder')).toBe('Order instructions (optional)');
+    expect(html).toContain('Subtotal:');
+    expect(html).toContain('terms and refund policy');
+    expect(html).toContain('Continue shopping');
+  });
+
+  it('renders French when the provider carries the active locale', () => {
+    const html = render(
+      <DefaultCartShell
+        items={[]}
+        currency="NGN"
+        total={0}
+        empty
+        onIncrease={noop}
+        onDecrease={noop}
+        onRemove={noop}
+      />,
+      { locale: 'fr', strings: FR_STRINGS },
+    );
+    expect(html).toContain('Votre panier</h1>');
+    expect(html).toContain('Votre panier est vide.');
+    expect(html).toContain('Voir les produits');
+  });
+});

package/tests/theme-strings.test.tsx

@@ -0,0 +1,396 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { JSX } from 'react';
+import enDefault from '../locales/en.default.json';
+import {
+  canonicalThemeLocale,
+  createThemeStrings,
+  defaultThemeStrings,
+  formatThemeDate,
+  formatThemeMoney,
+  formatThemeNumber,
+  interpolate,
+  resetThemeStringsWarnings,
+  t,
+  themeLocaleDir,
+  THEME_STRING_KEY_MAX_LENGTH,
+  THEME_STRING_VALUE_MAX_LENGTH,
+  type BoundThemeStrings,
+  type ThemeStringsDictionary,
+} from '../strings/theme-strings';
+
+const ROOT = resolve(__dirname, '..');
+
+beforeEach(() => {
+  resetThemeStringsWarnings();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+/** Partial French core pack — deliberately missing keys (fallback coverage). */
+const FR_CORE: ThemeStringsDictionary = {
+  cart: {
+    title: 'Votre panier',
+    empty: { message: 'Votre panier est vide.' },
+  },
+};
+
+const FR_THEME = {
+  'cart.empty.browse': 'Voir les produits',
+} as unknown as ThemeStringsDictionary;
+
+describe('t() fallback order (decision 3)', () => {
+  it('returns the first hit across override, theme, core, default', async () => {
+    const bound = await createThemeStrings({
+      locale: 'fr',
+      loaders: {
+        override: async () => ({ cart: { title: 'Override title' } }),
+        theme: async () => FR_THEME,
+        core: async () => FR_CORE,
+      },
+    });
+    // Override wins.
+    expect(bound.t('cart.title')).toBe('Override title');
+    // Theme fills what the override lacks (flat dotted key form).
+    expect(bound.t('cart.empty.browse')).toBe('Voir les produits');
+    // Core fills the rest.
+    expect(bound.t('cart.empty.message')).toBe('Votre panier est vide.');
+    // LAST fallback is the English default VALUE, never the raw key.
+    expect(bound.t('cart.summary.title')).toBe('Order summary');
+    expect(bound.dictionaries).toHaveLength(4);
+  });
+
+  it('a missing key is "" (never the dotted key, never "translation missing")', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(t([defaultThemeStrings], 'no.such.key')).toBe('');
+    expect(t([defaultThemeStrings], 'no.such.key')).toBe('');
+    // Warned once per key in development, silent in production shape.
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0]?.[0]).toContain('no.such.key');
+  });
+
+  it('an empty-string value is a real hit (renders "", does not fall through)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(t([{ hidden: { label: '' } }, defaultThemeStrings], 'hidden.label')).toBe('');
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('a throwing loader drops out of the chain (missing locale file)', async () => {
+    const bound = await createThemeStrings({
+      locale: 'fr',
+      loaders: {
+        theme: async () => {
+          throw new Error("Cannot find module './fr.json'");
+        },
+        core: async () => null,
+      },
+    });
+    expect(bound.t('cart.title')).toBe('Your cart');
+    expect(bound.locale).toBe('fr');
+  });
+
+  it('passes the validated locale code to loaders (host dynamic-imports it)', async () => {
+    const seen: string[] = [];
+    await createThemeStrings({
+      locale: 'fr',
+      loaders: { theme: async (locale) => { seen.push(locale); return null; } },
+    });
+    expect(seen).toEqual(['fr']);
+  });
+
+  it('an invalid locale code loads English', async () => {
+    const seen: string[] = [];
+    const bound = await createThemeStrings({
+      locale: 'not a locale!!',
+      loaders: { theme: async (locale) => { seen.push(locale); return null; } },
+    });
+    expect(seen).toEqual(['en']);
+    expect(bound.locale).toBe('en');
+  });
+});
+
+describe('t() plurals (CLDR via Intl.PluralRules)', () => {
+  const dict: ThemeStringsDictionary = {
+    items: {
+      count: {
+        one: '{count} item',
+        other: '{count} items',
+      },
+    },
+  };
+
+  it('selects one/other in English', () => {
+    expect(t([dict], 'items.count', { count: 1 }, 'en')).toBe('1 item');
+    expect(t([dict], 'items.count', { count: 0 }, 'en')).toBe('0 items');
+    expect(t([dict], 'items.count', { count: 2 }, 'en')).toBe('2 items');
+  });
+
+  it('follows French rules (0 and 1 are "one")', () => {
+    expect(t([dict], 'items.count', { count: 0 }, 'fr')).toBe('0 item');
+    expect(t([dict], 'items.count', { count: 1 }, 'fr')).toBe('1 item');
+    expect(t([dict], 'items.count', { count: 2 }, 'fr')).toBe('2 items');
+  });
+
+  it('follows Arabic rules ("two" exists)', () => {
+    const ar: ThemeStringsDictionary = {
+      items: { count: { zero: 'x', one: 'y', two: '{count} items-ar-two', few: 'f', many: 'm', other: 'o' } as never },
+    };
+    expect(t([ar], 'items.count', { count: 2 }, 'ar')).toBe('2 items-ar-two');
+  });
+
+  it('supports the flat "key.one / key.other" suffix convention', () => {
+    const flat = {
+      'basket.lines.one': '{count} line',
+      'basket.lines.other': '{count} lines',
+    } as unknown as ThemeStringsDictionary;
+    expect(t([flat], 'basket.lines', { count: 1 }, 'en')).toBe('1 line');
+    expect(t([flat], 'basket.lines', { count: 5 }, 'en')).toBe('5 lines');
+  });
+
+  it('missing/non-numeric count falls back to "other"', () => {
+    expect(t([dict], 'items.count', {}, 'en')).toBe('{count} items');
+    // Plural selection needs a finite numeric count; interpolation still applies.
+    expect(t([dict], 'items.count', { count: 'many' }, 'en')).toBe('many items');
+  });
+});
+
+describe('t() interpolation edge cases', () => {
+  it('keeps a missing var as its {placeholder}', () => {
+    expect(t([{ hi: 'Hello {name}!' }], 'hi', {}, 'en')).toBe('Hello {name}!');
+    expect(t([{ hi: 'Hello {name}!' }], 'hi', { name: null }, 'en')).toBe('Hello {name}!');
+  });
+
+  it('`{{` / `}}` escape to literal braces', () => {
+    expect(interpolate('{{{x}}}', { x: 1 })).toBe('{1}');
+    expect(interpolate('a {{b}} c', {})).toBe('a {b} c');
+  });
+
+  it('resolves nested keys by dot-path and flat dotted keys alike', () => {
+    const nested = { a: { b: { c: 'deep' } } } as ThemeStringsDictionary;
+    const flat = { 'a.b.c': 'flat' } as unknown as ThemeStringsDictionary;
+    expect(t([nested], 'a.b.c')).toBe('deep');
+    expect(t([flat], 'a.b.c')).toBe('flat');
+  });
+
+  it('stringifies numbers and booleans', () => {
+    expect(t([{ v: '{n} / {b}' }], 'v', { n: 42, b: false })).toBe('42 / false');
+  });
+
+  it('reads the real default dictionary values used by the cart shell', () => {
+    expect(t([defaultThemeStrings], 'cart.title')).toBe('Your cart');
+    expect(t([defaultThemeStrings], 'cart.item.each', { price: '₦5,000' })).toBe('₦5,000 each');
+    expect(t([defaultThemeStrings], 'cart.item.decrease', { title: 'Egusi' })).toBe('Decrease Egusi');
+    expect(t([defaultThemeStrings], 'cart.terms.agree')).toBe('I agree to the ');
+  });
+});
+
+describe('unknown locale = English', () => {
+  it('canonicalises garbage to en', () => {
+    expect(canonicalThemeLocale(null)).toBe('en');
+    expect(canonicalThemeLocale(undefined)).toBe('en');
+    expect(canonicalThemeLocale('not a locale!!')).toBe('en');
+  });
+
+  it('canonicalises well-formed-but-unknown codes to en', () => {
+    expect(canonicalThemeLocale('xx')).toBe('en');
+  });
+
+  it('keeps known codes for plural/format selection', () => {
+    for (const code of ['en', 'fr', 'ar']) {
+      expect(canonicalThemeLocale(code)).toBe(code);
+    }
+  });
+
+  it('t() still renders English for an unknown locale', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(t([defaultThemeStrings], 'cart.title', {}, 'xx')).toBe('Your cart');
+    expect(warn).not.toHaveBeenCalled();
+  });
+});
+
+describe('RTL dir (locale catalogue)', () => {
+  it('marks Arabic-script locales rtl, everything else ltr', () => {
+    expect(themeLocaleDir('ar')).toBe('rtl');
+    expect(themeLocaleDir('ar-EG')).toBe('rtl');
+    expect(themeLocaleDir('he')).toBe('rtl');
+    for (const code of ['en', 'fr', 'es', 'pt', 'sw', 'ha', 'yo', 'ig', 'zh', 'de', 'pcm', null, 'bogus!!']) {
+      expect(themeLocaleDir(code), String(code)).toBe('ltr');
+    }
+  });
+});
+
+describe('default English dictionary budget (backend varchar(64))', () => {
+  function flatten(node: unknown, prefix: string, out: Array<[string, string]>): void {
+    if (typeof node === 'string') {
+      out.push([prefix, node]);
+      return;
+    }
+    if (node && typeof node === 'object' && !Array.isArray(node)) {
+      for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+        flatten(v, prefix ? `${prefix}.${k}` : k, out);
+      }
+    }
+  }
+
+  const pairs: Array<[string, string]> = [];
+  flatten(enDefault, '', pairs);
+
+  it('ships the ~75-string core skeleton', () => {
+    expect(pairs.length).toBeGreaterThanOrEqual(70);
+    expect(pairs.length).toBeLessThan(100);
+  });
+
+  it('every key fits the dotted-lowercase grammar and the 40-char budget', () => {
+    for (const [key] of pairs) {
+      expect(key, `grammar: ${key}`).toMatch(/^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/);
+      expect(key.length, `budget: ${key}`).toBeLessThanOrEqual(THEME_STRING_KEY_MAX_LENGTH);
+    }
+    // `<theme-slug>.<key>` must fit varchar(64): 40 + 1 + 23.
+    expect(Math.max(...pairs.map(([k]) => k.length))).toBeLessThanOrEqual(40);
+  });
+
+  it('every value fits the 1000-char budget', () => {
+    for (const [key, value] of pairs) {
+      expect(value.length, `value: ${key}`).toBeLessThanOrEqual(THEME_STRING_VALUE_MAX_LENGTH);
+    }
+  });
+
+  it('matches the runtime default export', () => {
+    expect(defaultThemeStrings).toEqual(enDefault);
+  });
+});
+
+describe('per-locale loading gate (decision 5)', () => {
+  function sourceFiles(dir: string, out: string[] = []): string[] {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules') continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) sourceFiles(full, out);
+      else if (/\.tsx?$/.test(entry.name)) out.push(full);
+    }
+    return out;
+  }
+
+  /** Import specifiers only (static `from`/`import` and dynamic `import()`). */
+  function importSpecifiers(source: string): string[] {
+    const out: string[] = [];
+    for (const match of source.matchAll(/from\s+['"]([^'"]+)['"]/g)) out.push(match[1]);
+    for (const match of source.matchAll(/import\s*\(\s*['"`]([^'"`]+)['"`]/g)) out.push(match[1]);
+    return out;
+  }
+
+  it('no client-reachable module statically imports a non-default locale file', () => {
+    const offenders: string[] = [];
+    for (const file of sourceFiles(ROOT)) {
+      const source = readFileSync(file, 'utf-8');
+      for (const spec of importSpecifiers(source)) {
+        if (spec.includes('locales/') && !spec.endsWith('locales/en.default.json')) {
+          offenders.push(`${file}: ${spec}`);
+        }
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('the kit never dynamic-imports the locales dir (only the host does, per locale)', () => {
+    const offenders: string[] = [];
+    for (const file of sourceFiles(ROOT)) {
+      if (file.endsWith('.test.ts') || file.endsWith('.test.tsx')) continue;
+      const source = readFileSync(file, 'utf-8');
+      if (/import\s*\(\s*[`'"][^`'"]*locales\//.test(source)) {
+        offenders.push(file);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('only the English default may be statically imported (exactly one locale ships)', () => {
+    const importers: string[] = [];
+    for (const file of sourceFiles(ROOT)) {
+      if (file.endsWith('.test.ts') || file.endsWith('.test.tsx')) continue;
+      const source = readFileSync(file, 'utf-8');
+      if (source.includes('locales/en.default.json')) importers.push(file);
+    }
+    expect(importers).toEqual([join(ROOT, 'strings', 'theme-strings.ts')]);
+  });
+
+  it('the pure/server-safe module imports neither next/* nor React', () => {
+    const source = readFileSync(join(ROOT, 'strings', 'theme-strings.ts'), 'utf-8');
+    expect(source).not.toMatch(/from ['"]next\//);
+    expect(source).not.toMatch(/from ['"]react['"]/);
+    expect(source).not.toContain("'use client'");
+    expect(existsSync(join(ROOT, 'locales', 'en.default.json'))).toBe(true);
+  });
+});
+
+describe('server surface: bound t with NO provider (decision 4a)', () => {
+  function Greeting({ bound, name }: { bound: BoundThemeStrings; name: string }): JSX.Element {
+    return (
+      <main>
+        <h1>{bound.t('cart.title')}</h1>
+        <p>{bound.t('cart.empty.message')}</p>
+        <p>{bound.t('cart.item.each', { price: name })}</p>
+      </main>
+    );
+  }
+
+  async function renderFor(locale: string | null): Promise<{ bound: BoundThemeStrings; html: string }> {
+    const bound = await createThemeStrings({
+      locale,
+      loaders: {
+        theme: async (active) => (active === 'fr' ? FR_CORE : null),
+      },
+    });
+    return { bound, html: renderToStaticMarkup(<Greeting bound={bound} name="5 000 F" />) };
+  }
+
+  it('renders EN from defaults with no provider in the tree', async () => {
+    const { html } = await renderFor(null);
+    expect(html).toContain('<h1>Your cart</h1>');
+    expect(html).toContain('Your cart is empty.');
+  });
+
+  it('renders FR from the active locale only', async () => {
+    const { bound, html } = await renderFor('fr');
+    expect(bound.locale).toBe('fr');
+    expect(html).toContain('<h1>Votre panier</h1>');
+    expect(html).toContain('Votre panier est vide.');
+    // Key missing from the FR pack falls back to the English VALUE.
+    expect(html).toContain('5 000 F each');
+  });
+
+  it('renders AR with English values and an rtl dir', async () => {
+    const { bound, html } = await renderFor('ar');
+    expect(bound.locale).toBe('ar');
+    expect(html).toContain('<h1>Your cart</h1>');
+    expect(themeLocaleDir(bound.locale)).toBe('rtl');
+  });
+});
+
+describe('Intl probe (report only — en fr es pt ar sw ha yo ig zh de pcm)', () => {
+  const LOCALES = ['en', 'fr', 'es', 'pt', 'ar', 'sw', 'ha', 'yo', 'ig', 'zh', 'de', 'pcm'];
+
+  it('records native support vs silent fallback on this Node runtime', () => {
+    const rows = LOCALES.map((locale) => ({
+      locale,
+      plural: Intl.PluralRules.supportedLocalesOf([locale]).length > 0 ? 'native' : 'FALLBACK',
+      number: Intl.NumberFormat.supportedLocalesOf([locale]).length > 0 ? 'native' : 'FALLBACK',
+      date: Intl.DateTimeFormat.supportedLocalesOf([locale]).length > 0 ? 'native' : 'FALLBACK',
+    }));
+    // eslint-disable-next-line no-console
+    console.log(`[intl-probe] node ${process.version}\n${rows.map((r) => `${r.locale}: plural=${r.plural} number=${r.number} date=${r.date}`).join('\n')}`);
+
+    // Every locale still formats without throwing (helpers fall back to English).
+    for (const locale of LOCALES) {
+      expect(() => formatThemeNumber(1234.5, locale)).not.toThrow();
+      expect(() => formatThemeDate('2026-02-14', locale)).not.toThrow();
+      expect(() => formatThemeMoney(5000, 'NGN', locale)).not.toThrow();
+      expect(t([defaultThemeStrings], 'cart.title', {}, locale)).toBe('Your cart');
+    }
+    expect(rows).toHaveLength(12);
+  });
+});

package/utils/locale.ts

@@ -0,0 +1,95 @@
+/**
+ * Storefront locale transport — the kit side of the translations plan.
+ *
+ * Contract (translations-core.md, decisions closed): the backend accepts
+ * `?locale=<code>` on every customer-facing read and answers translated text
+ * (unknown/unpublished locale → source text, no error). The storefront proxy
+ * sets `x-queek-locale` on the incoming request for published NON-primary
+ * locales only — the header is ABSENT on the primary locale — and suffixes
+ * revalidation tags as `<tag>:locale:<code>`.
+ *
+ * This module is deliberately pure (no `next/*` imports) so both sides share
+ * it: the server transport (`sdk/server-store-client`) and the browser hooks
+ * (`hooks/*` via `provider.tsx`). The ONLY `next/headers` read lives in
+ * `sdk/server-store-client.ts` (`readRequestLocale`) — never parse the header
+ * anywhere else.
+ *
+ * Backwards compatibility: every function here is a no-op returning its input
+ * unchanged when no valid locale is present, so no-locale behaviour is
+ * byte-identical to before.
+ */
+
+/** Request header the proxy sets for published non-primary locales. */
+export const LOCALE_CODE_HEADER = 'x-queek-locale';
+
+/** Infix the backend sends on revalidation tags for one locale's entries. */
+export const LOCALE_TAG_INFIX = ':locale:';
+
+const LOCALE_CODE_PATTERN = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+const LOCALE_CODE_MAX_LENGTH = 12;
+
+/**
+ * Validates a locale code (header value, provider prop or explicit override).
+ * Anything else — absent, wrong shape, too long — is ignored (null), mirroring
+ * the backend's unknown-locale → source-text rule: never an error.
+ */
+export function parseLocaleCode(value: unknown): string | null {
+  if (typeof value !== 'string' || value.length === 0 || value.length > LOCALE_CODE_MAX_LENGTH) {
+    return null;
+  }
+  return LOCALE_CODE_PATTERN.test(value) ? value : null;
+}
+
+type QueryRecord = Record<string, string | number | boolean | string[] | null | undefined>;
+
+/**
+ * Adds `?locale=<code>` to a backend query. No valid locale → the input is
+ * returned untouched (same reference), so the built URL is byte-identical.
+ */
+export function withLocaleQuery<T extends QueryRecord>(
+  query: T | undefined,
+  locale: string | null | undefined,
+): T | (T & { locale: string }) | undefined {
+  const code = parseLocaleCode(locale);
+  if (!code) return query;
+  return { ...(query ?? ({} as T)), locale: code };
+}
+
+/** Cache tag for one locale's entries of a resource (`<tag>:locale:<code>`). */
+export function withLocaleTag(tag: string, locale: string | null | undefined): string {
+  const code = parseLocaleCode(locale);
+  return code ? `${tag}${LOCALE_TAG_INFIX}${code.toLowerCase()}` : tag;
+}
+
+/**
+ * Suffixes EVERY cache tag with `:locale:<code>` so one locale's entries
+ * never share a cache entry with another's (or the primary's). No valid
+ * locale → the input array is returned untouched (same reference).
+ */
+export function withLocaleTags(tags: readonly string[], locale: string | null | undefined): string[] {
+  const code = parseLocaleCode(locale);
+  if (!code) return tags as string[];
+  return tags.map((tag) => `${tag}${LOCALE_TAG_INFIX}${code.toLowerCase()}`);
+}
+
+/**
+ * Appends `?locale=<code>` to an already-built request path — for callers
+ * whose client takes a path string only (the SDK-backed `getQueekClient`,
+ * whose `get(path, options?)` carries headers but no query). No valid locale
+ * → the path is returned untouched.
+ */
+export function withLocalePath(path: string, locale: string | null | undefined): string {
+  const code = parseLocaleCode(locale);
+  if (!code) return path;
+  return `${path}${path.includes('?') ? '&' : '?'}locale=${encodeURIComponent(code)}`;
+}
+
+/**
+ * The locale dimension of a client-side cache key (`''` when unset, so
+ * no-locale keys are exactly what they always were). Two locales never share
+ * a client cache entry; unset never collides with set.
+ */
+export function localeCacheKeySegment(locale: string | null | undefined): string {
+  const code = parseLocaleCode(locale);
+  return code ? code.toLowerCase() : '';
+}

package/utils/shop-query.ts

@@ -41,6 +41,13 @@ export interface ShopPrefetch {
   query: ShopQuery;
   products: Product[];
   pagination: ShopPagination;
+  /**
+   * Request locale the page was fetched in (null = primary). `useShop` only
+   * seeds from a prefetch whose locale matches its own, so two locales never
+   * share the seeded grid. Absent (older callers) means primary, exactly as
+   * before.
+   */
+  locale?: string | null;
 }
 
 export function normalizeShopQuery(input?: {