@usequeek/theme-kit 0.1.16 → 0.1.18

package/strings/theme-strings.ts

@@ -0,0 +1,356 @@
+/**
+ * Theme strings — the kit's Shopify-shaped UI-string mechanism (slice K0).
+ *
+ * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
+ * from React, so server components, Node tooling and the browser all share it
+ * (precedent: `utils/locale.ts`). Keep it that way — `tests/theme-strings*`
+ * fails a build that adds either import here.
+ *
+ * Two surfaces (plan decision 4):
+ *  - Server: `createThemeStrings({ locale, loaders })` returns a bound `t`
+ *    that a server component receives via props/closure. NO provider in the
+ *    tree. The host supplies the loaders (per-locale dynamic imports) so the
+ *    kit never bundles locale files.
+ *  - Client: `StorefrontProvider` takes an optional `strings` prop and
+ *    `useThemeStrings()` returns the same bound `t`. Absent prop = English
+ *    defaults, byte-identical to the old hardcoded literals.
+ *
+ * Fallback (plan decision 3): the caller supplies an ordered list of
+ * dictionaries (merchant override, theme locale, kit core locale) and `t`
+ * returns the FIRST hit. The LAST entry is always the English default value —
+ * never the raw dotted key, never "translation missing". A key absent
+ * everywhere returns `''` (and warns once per key in development only).
+ *
+ * Key budget: dotted lowercase `scope.thing.state`, total length <= 40 chars.
+ * The backend overlay stores `<theme-slug>.<key>` in a varchar(64), so 40 for
+ * the key leaves 23 for the slug plus the dot separator. Values <= 1000 chars.
+ */
+
+import { parseLocaleCode } from '../utils/locale';
+import enDefault from '../locales/en.default.json';
+
+/** Interpolation variables: `{name}` in a value. `count` drives plurals. */
+export type ThemeStringsVars = Record<string, string | number | boolean | null | undefined>;
+
+/**
+ * CLDR plural variants for one key, using the `one/two/few/many/other`
+ * suffix convention. `other` is required (the fallback form); the rest are
+ * used only when `Intl.PluralRules` for the active locale selects them.
+ */
+export interface ThemeStringsPluralMap {
+  one?: string;
+  two?: string;
+  few?: string;
+  many?: string;
+  other: string;
+}
+
+export type ThemeStringsValue =
+  | string
+  | ThemeStringsPluralMap
+  | { [key: string]: ThemeStringsValue };
+
+/** One dictionary: nested objects traversed by dot-path, or flat dotted keys. */
+export type ThemeStringsDictionary = { [key: string]: ThemeStringsValue };
+
+/** The bound translator both surfaces hand out. */
+export type ThemeStringsFn = (
+  key: string,
+  vars?: ThemeStringsVars,
+  locale?: string | null,
+) => string;
+
+/** The kit's default English core dictionary (`locales/en.default.json`). */
+export const defaultThemeStrings: ThemeStringsDictionary =
+  enDefault as ThemeStringsDictionary;
+
+/** Maximum total key length — see the module docblock for the budget. */
+export const THEME_STRING_KEY_MAX_LENGTH = 40;
+
+/** Maximum value length. */
+export const THEME_STRING_VALUE_MAX_LENGTH = 1000;
+
+const PLURAL_FORMS = ['one', 'two', 'few', 'many', 'other'] as const;
+
+/**
+ * Canonical locale for string selection. Unknown/unparseable codes become
+ * English, mirroring `parseLocaleCode` (and the backend's unknown-locale
+ * rule). A well-formed code the runtime's ICU does not know also becomes
+ * English, so plural selection never silently follows the wrong language.
+ */
+export function canonicalThemeLocale(locale: string | null | undefined): string {
+  const code = parseLocaleCode(locale) ?? 'en';
+  try {
+    return Intl.PluralRules.supportedLocalesOf([code]).length > 0 ? code : 'en';
+  } catch {
+    return 'en';
+  }
+}
+
+/**
+ * Text direction for a locale (`dir` attribute). There is no locale catalogue
+ * in the kit to read this from, so the base language decides: Arabic-script
+ * languages render `rtl`, everything else (including unknown codes) `ltr`.
+ */
+export function themeLocaleDir(locale: string | null | undefined): 'rtl' | 'ltr' {
+  const base = (parseLocaleCode(locale) ?? 'en').split('-')[0]?.toLowerCase() ?? 'en';
+  return RTL_BASE_LANGUAGES.has(base) ? 'rtl' : 'ltr';
+}
+
+const RTL_BASE_LANGUAGES: ReadonlySet<string> = new Set([
+  'ar', 'he', 'fa', 'ur', 'ps', 'sd', 'yi', 'ug', 'dv', 'ku',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isPluralMap(value: unknown): value is ThemeStringsPluralMap {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value);
+  return (
+    keys.length > 0 &&
+    keys.every((k) => (PLURAL_FORMS as readonly string[]).includes(k)) &&
+    keys.every((k) => typeof value[k] === 'string')
+  );
+}
+
+/** Dot-path lookup that also accepts a flat literal dotted key. */
+function lookupValue(
+  dictionary: ThemeStringsDictionary,
+  key: string,
+): ThemeStringsValue | undefined {
+  if (Object.prototype.hasOwnProperty.call(dictionary, key)) {
+    return dictionary[key];
+  }
+  let node: ThemeStringsValue = dictionary;
+  for (const part of key.split('.')) {
+    if (!isRecord(node) || !Object.prototype.hasOwnProperty.call(node, part)) return undefined;
+    node = node[part] as ThemeStringsValue;
+  }
+  return node;
+}
+
+function pluralCount(vars: ThemeStringsVars | undefined): number | null {
+  const count = vars?.['count'];
+  return typeof count === 'number' && Number.isFinite(count) ? count : null;
+}
+
+function selectPluralForm(
+  map: ThemeStringsPluralMap,
+  vars: ThemeStringsVars | undefined,
+  locale: string,
+): string {
+  const count = pluralCount(vars);
+  if (count === null) return map.other;
+  let form: string;
+  try {
+    form = new Intl.PluralRules(locale).select(count);
+  } catch {
+    form = new Intl.PluralRules('en').select(count);
+  }
+  return map[form as keyof ThemeStringsPluralMap] ?? map.other;
+}
+
+/** Suffix convention: `key.one` … `key.other` looked up as (flat or nested) keys. */
+function lookupSuffixed(
+  dictionary: ThemeStringsDictionary,
+  key: string,
+  vars: ThemeStringsVars | undefined,
+  locale: string,
+): string | undefined {
+  const count = pluralCount(vars);
+  let form = 'other';
+  if (count !== null) {
+    try {
+      form = new Intl.PluralRules(locale).select(count);
+    } catch {
+      form = new Intl.PluralRules('en').select(count);
+    }
+  }
+  for (const candidate of form === 'other' ? ['other'] : [form, 'other']) {
+    const value = lookupValue(dictionary, `${key}.${candidate}`);
+    if (typeof value === 'string') return interpolate(value, vars);
+  }
+  return undefined;
+}
+
+/**
+ * `{var}` interpolation. A missing/nullish var keeps its `{placeholder}`
+ * (visible, greppable, never a crash); `{{` / `}}` escape to literal braces.
+ */
+export function interpolate(
+  template: string,
+  vars: ThemeStringsVars | undefined,
+): string {
+  if (!template.includes('{') && !template.includes('}')) return template;
+  let out = '';
+  let i = 0;
+  while (i < template.length) {
+    const ch = template[i];
+    if (ch === '{') {
+      if (template[i + 1] === '{') {
+        out += '{';
+        i += 2;
+        continue;
+      }
+      const close = template.indexOf('}', i + 1);
+      const name = close === -1 ? '' : template.slice(i + 1, close);
+      if (close !== -1 && /^[A-Za-z0-9_]+$/.test(name)) {
+        const value = vars?.[name];
+        out += value === undefined || value === null ? template.slice(i, close + 1) : String(value);
+        i = close + 1;
+        continue;
+      }
+      out += ch;
+      i += 1;
+      continue;
+    }
+    if (ch === '}' && template[i + 1] === '}') {
+      out += '}';
+      i += 2;
+      continue;
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+const warnedKeys = new Set<string>();
+
+function warnMissingKey(key: string): void {
+  if (typeof process !== 'undefined' && process.env['NODE_ENV'] === 'production') return;
+  if (warnedKeys.has(key)) return;
+  warnedKeys.add(key);
+  console.warn(`[theme-kit] missing theme string: "${key}" (no dictionary has it; rendered "")`);
+}
+
+/** Test-only: reset the warn-once set between cases. */
+export function resetThemeStringsWarnings(): void {
+  warnedKeys.clear();
+}
+
+/**
+ * Pure lookup: first hit across the ordered dictionaries wins
+ * (override, theme locale, kit core locale — the caller appends
+ * `defaultThemeStrings` LAST). Absent everywhere: `''` in production, plus a
+ * once-per-key `console.warn` in development. Never the raw key.
+ */
+export function t(
+  dictionaries: ThemeStringsDictionary | Array<ThemeStringsDictionary | null | undefined>,
+  key: string,
+  vars?: ThemeStringsVars,
+  locale?: string | null,
+): string {
+  const list = Array.isArray(dictionaries) ? dictionaries : [dictionaries];
+  const canonical = canonicalThemeLocale(locale);
+  for (const dictionary of list) {
+    if (!dictionary) continue;
+    const value = lookupValue(dictionary, key);
+    if (typeof value === 'string') return interpolate(value, vars);
+    if (isPluralMap(value)) return interpolate(selectPluralForm(value, vars, canonical), vars);
+    const suffixed = lookupSuffixed(dictionary, key, vars, canonical);
+    if (suffixed !== undefined) return suffixed;
+  }
+  warnMissingKey(key);
+  return '';
+}
+
+/** Per-locale loader the host supplies — usually a dynamic `import()`. */
+export type ThemeStringsLoader = (
+  locale: string,
+) => Promise<ThemeStringsDictionary | null | undefined>;
+
+export interface ThemeStringsLoaders {
+  /** Merchant overrides for the active locale (highest precedence). */
+  override?: ThemeStringsLoader;
+  /** Active theme's `{locale}.json`. */
+  theme?: ThemeStringsLoader;
+  /** Kit core pack for the active locale. */
+  core?: ThemeStringsLoader;
+}
+
+export interface BoundThemeStrings {
+  /** Bound to the active locale's dictionaries (+ English default last). */
+  t: ThemeStringsFn;
+  /** Validated requested locale (`en` when unknown) — what loaders were read with. */
+  locale: string;
+  /** Ordered dictionaries the bound `t` reads (override, theme, core, default). */
+  dictionaries: ThemeStringsDictionary[];
+}
+
+/**
+ * Server-safe, provider-free loader contract. Reads ONLY the active locale
+ * (one locale crosses to the client — never every `{lang}.json`), merges
+ * override → theme → core → English default, and returns a bound `t` for
+ * props/closure use. A loader that throws or returns null (e.g. a missing
+ * locale file) simply drops out of the chain — never an error.
+ */
+export async function createThemeStrings(options?: {
+  locale?: string | null;
+  loaders?: ThemeStringsLoaders;
+}): Promise<BoundThemeStrings> {
+  const requested = parseLocaleCode(options?.locale) ?? 'en';
+  const loaders = options?.loaders;
+  const dictionaries: ThemeStringsDictionary[] = [];
+  for (const load of [loaders?.override, loaders?.theme, loaders?.core]) {
+    if (!load) continue;
+    try {
+      const dictionary = await load(requested);
+      if (dictionary && isRecord(dictionary)) {
+        dictionaries.push(dictionary as ThemeStringsDictionary);
+      }
+    } catch {
+      // Missing locale file et al: fall through to the next dictionary.
+    }
+  }
+  dictionaries.push(defaultThemeStrings);
+  const active = requested;
+  return {
+    t: (key, vars, overrideLocale) =>
+      t(dictionaries, key, vars, overrideLocale ?? active),
+    locale: active,
+    dictionaries,
+  };
+}
+
+/** Locale-aware number formatting keyed by the active locale (unknown → English). */
+export function formatThemeNumber(
+  value: number,
+  locale?: string | null,
+  options?: Intl.NumberFormatOptions,
+): string {
+  return new Intl.NumberFormat(canonicalThemeLocale(locale), options).format(value);
+}
+
+/** Locale-aware date formatting keyed by the active locale (unknown → English). `''` if unparseable. */
+export function formatThemeDate(
+  value: string | number | Date,
+  locale?: string | null,
+  options: Intl.DateTimeFormatOptions = { day: 'numeric', month: 'short', year: 'numeric' },
+): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return '';
+  return new Intl.DateTimeFormat(canonicalThemeLocale(locale), options).format(date);
+}
+
+function normalizeMoneyCurrency(value: unknown): string {
+  return typeof value === 'string' && /^[A-Za-z]{3}$/.test(value.trim())
+    ? value.trim().toUpperCase()
+    : 'NGN';
+}
+
+/** Locale-aware currency formatting keyed by the active locale (unknown → English). */
+export function formatThemeMoney(
+  amount: number,
+  currency: unknown,
+  locale?: string | null,
+  options?: Omit<Intl.NumberFormatOptions, 'style' | 'currency'>,
+): string {
+  return new Intl.NumberFormat(canonicalThemeLocale(locale), {
+    ...options,
+    style: 'currency',
+    currency: normalizeMoneyCurrency(currency),
+  }).format(amount);
+}

package/tests/locale-transport.test.tsx

@@ -0,0 +1,321 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { JSX, ReactNode } from 'react';
+import {
+  LOCALE_CODE_HEADER,
+  localeCacheKeySegment,
+  parseLocaleCode,
+  withLocalePath,
+  withLocaleQuery,
+  withLocaleTag,
+  withLocaleTags,
+} from '../utils/locale';
+import { StorefrontProvider, useStorefrontLocale } from '../provider';
+import { ShopPrefetchProvider, useShop } from '../hooks/use-shop';
+import { normalizeShopQuery, type ShopPrefetch } from '../utils/shop-query';
+import type { Product } from '../types/product';
+
+/**
+ * Theme-kit locale transport (slice K1): the backend answers `?locale=<code>`
+ * with translated text, the proxy sets `x-queek-locale` for published
+ * non-primary locales only, and every kit transport forwards it additively —
+ * no locale anywhere means byte-identical behaviour to before.
+ */
+
+const requestHeaders = vi.hoisted(() => ({ headers: new Headers(), throwOutsideScope: false }));
+
+vi.mock('next/headers', () => ({
+  headers: async () => {
+    if (requestHeaders.throwOutsideScope) throw new Error('headers() outside request scope');
+    return requestHeaders.headers;
+  },
+}));
+
+function setRequestHeaders(values: Record<string, string>): void {
+  requestHeaders.headers = new Headers(values);
+  requestHeaders.throwOutsideScope = false;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  setRequestHeaders({});
+});
+
+describe('parseLocaleCode (header / prop / override validation)', () => {
+  it('accepts well-formed codes', () => {
+    for (const code of ['en', 'zh', 'yo', 'pcm', 'zh-CN', 'pt-BR', 'zh-TW', 'sr-Latn']) {
+      expect(parseLocaleCode(code), code).toBe(code);
+    }
+  });
+
+  it('ignores anything else (never an error)', () => {
+    for (const bad of [
+      '',
+      'e',
+      'toolongcode123',
+      'zh!',
+      'en_US',
+      'en us',
+      'shop',
+      'products',
+      '-zh',
+      'zh-',
+      '123',
+      null,
+      undefined,
+      42,
+      {},
+    ]) {
+      expect(parseLocaleCode(bad), JSON.stringify(bad)).toBeNull();
+    }
+  });
+
+  it('enforces the 12-char cap', () => {
+    expect(parseLocaleCode('ab-cdefghij')).toBe('ab-cdefghij');
+    expect(parseLocaleCode('ab-cdefghijk')).toBeNull();
+  });
+});
+
+describe('withLocaleQuery (backend URL building)', () => {
+  it('adds locale=<code> to a query', () => {
+    expect(withLocaleQuery({ per_page: 24, page: 1 }, 'zh-CN')).toEqual({ per_page: 24, page: 1, locale: 'zh-CN' });
+  });
+
+  it('builds a query from nothing when locale is set', () => {
+    expect(withLocaleQuery(undefined, 'zh')).toEqual({ locale: 'zh' });
+  });
+
+  it('returns the input untouched when no valid locale is present', () => {
+    const query = { per_page: 24 };
+    expect(withLocaleQuery(query, null)).toBe(query);
+    expect(withLocaleQuery(query, undefined)).toBe(query);
+    expect(withLocaleQuery(query, '!!')).toBe(query);
+    expect(withLocaleQuery(undefined, null)).toBeUndefined();
+  });
+});
+
+describe('cache tag suffixing (`<tag>:locale:<code>`)', () => {
+  it('suffixes every tag, lower-cased', () => {
+    expect(withLocaleTag('v:acme:theme', 'zh-CN')).toBe('v:acme:theme:locale:zh-cn');
+    expect(withLocaleTags(['v:acme', 'v:acme:theme', 'v:acme:menus'], 'zh')).toEqual([
+      'v:acme:locale:zh',
+      'v:acme:theme:locale:zh',
+      'v:acme:menus:locale:zh',
+    ]);
+  });
+
+  it('returns tags untouched when no valid locale is present', () => {
+    const tags = ['v:acme', 'v:acme:theme'];
+    expect(withLocaleTags(tags, null)).toBe(tags);
+    expect(withLocaleTags(tags, 'shop')).toBe(tags);
+    expect(withLocaleTag('v:acme', null)).toBe('v:acme');
+  });
+});
+
+describe('withLocalePath (SDK-backed callers with path strings only)', () => {
+  it('appends locale, respecting an existing query string', () => {
+    expect(withLocalePath('/client/store/products/egusi', 'zh')).toBe('/client/store/products/egusi?locale=zh');
+    expect(withLocalePath('/x?limit=4', 'zh-CN')).toBe('/x?limit=4&locale=zh-CN');
+  });
+
+  it('returns the path untouched without a valid locale', () => {
+    expect(withLocalePath('/client/store/products/egusi', null)).toBe('/client/store/products/egusi');
+    expect(withLocalePath('/x?limit=4', 'nope!')).toBe('/x?limit=4');
+  });
+});
+
+describe('localeCacheKeySegment (client cache keys)', () => {
+  it('separates locales and never collides with unset', () => {
+    expect(localeCacheKeySegment('zh')).toBe('zh');
+    expect(localeCacheKeySegment('zh-CN')).toBe('zh-cn');
+    expect(localeCacheKeySegment(null)).toBe('');
+    expect(localeCacheKeySegment('!!')).toBe('');
+    expect(localeCacheKeySegment('zh')).not.toBe(localeCacheKeySegment(null));
+  });
+});
+
+describe('server transport (sdk/server-store-client)', () => {
+  type CapturedInit = RequestInit & { next?: { revalidate: number; tags: string[] } };
+
+  async function capturedGet(path: string, query?: Record<string, string | number>, locale?: string): Promise<{ url: string; init: CapturedInit }> {
+    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) => ({ ok: true, json: async () => ({ data: {} }) }));
+    vi.stubGlobal('fetch', fetchMock);
+    const { createServerStoreClient } = await import('../sdk/server-store-client');
+    const client = createServerStoreClient('acme', 'http://origin.test');
+    await client.get(path, query, locale);
+    const [[url, init]] = fetchMock.mock.calls as unknown as Array<[string, CapturedInit]>;
+    return { url, init };
+  }
+
+  it('appends locale=<code> and suffixes every tag when the header is set', async () => {
+    setRequestHeaders({ [LOCALE_CODE_HEADER]: 'zh-CN', host: 'acme.test' });
+    const { url, init } = await capturedGet('/info');
+    expect(url).toContain('locale=zh-CN');
+    expect(init.next?.tags).toEqual(['v:acme:locale:zh-cn', 'v:acme:profile:locale:zh-cn']);
+  });
+
+  it('is byte-identical to today with no header', async () => {
+    setRequestHeaders({ host: 'acme.test' });
+    const { url, init } = await capturedGet('/info');
+    expect(url).toBe('http://127.0.0.1:8000/api/v1/client/store/info');
+    expect(init.next).toEqual({ revalidate: 300, tags: ['v:acme', 'v:acme:profile'] });
+  });
+
+  it('ignores an invalid header value', async () => {
+    setRequestHeaders({ [LOCALE_CODE_HEADER]: 'not a locale!!', host: 'acme.test' });
+    const { url, init } = await capturedGet('/info');
+    expect(url).not.toContain('locale=');
+    expect(init.next?.tags).toEqual(['v:acme', 'v:acme:profile']);
+  });
+
+  it('never throws outside a request scope (treated as no locale)', async () => {
+    requestHeaders.throwOutsideScope = true;
+    const { readRequestLocale } = await import('../sdk/server-store-client');
+    await expect(readRequestLocale()).resolves.toBeNull();
+    requestHeaders.throwOutsideScope = false;
+    const { url } = await capturedGet('/info');
+    expect(url).not.toContain('locale=');
+  });
+
+  it('an explicit override wins over the header', async () => {
+    setRequestHeaders({ [LOCALE_CODE_HEADER]: 'zh', host: 'acme.test' });
+    const { url, init } = await capturedGet('/info', undefined, 'fr');
+    expect(url).toContain('locale=fr');
+    expect(init.next?.tags).toEqual(['v:acme:locale:fr', 'v:acme:profile:locale:fr']);
+  });
+
+  it('still bypasses the cache for preview renders, locale or not', async () => {
+    setRequestHeaders({ 'x-queek-preview': '1', [LOCALE_CODE_HEADER]: 'zh', host: 'acme.test' });
+    const { url, init } = await capturedGet('/info');
+    expect(url).toContain('locale=zh');
+    expect(init.next).toBeUndefined();
+    expect(init.cache).toBe('no-store');
+  });
+});
+
+describe('fetchShopPrefetch (api/shop)', () => {
+  async function runPrefetch(vendorSlug = 'kili-foods', locale?: string) {
+    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) => ({ ok: true, json: async () => ({ data: [], has_more: false }) }));
+    vi.stubGlobal('fetch', fetchMock);
+    const { fetchShopPrefetch } = await import('../api/shop');
+    const prefetch = await fetchShopPrefetch(vendorSlug, normalizeShopQuery({}), locale);
+    const urls = (fetchMock.mock.calls as unknown as Array<[string]>).map(([url]) => String(url));
+    const productsCall = urls.find((url) => url.includes('/products')) ?? '';
+    return { prefetch, productsCall };
+  }
+
+  it('forwards the request locale and echoes it for the seed match', async () => {
+    setRequestHeaders({ [LOCALE_CODE_HEADER]: 'zh', host: 'x.test' });
+    const { prefetch, productsCall } = await runPrefetch();
+    expect(productsCall).toContain('locale=zh');
+    expect(prefetch?.locale).toBe('zh');
+  });
+
+  it('fetches exactly as before with no locale (echo null)', async () => {
+    setRequestHeaders({ host: 'x.test' });
+    const { prefetch, productsCall } = await runPrefetch();
+    expect(productsCall).not.toContain('locale=');
+    expect(prefetch?.locale).toBeNull();
+  });
+});
+
+function product(id: string, title: string): Product {
+  return { id, title, slug: id } as unknown as Product;
+}
+
+function render(children: ReactNode, locale?: string | null): string {
+  return renderToStaticMarkup(
+    <StorefrontProvider
+      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      config={{} as never}
+      menus={[]}
+      {...(locale !== undefined ? { locale } : {})}
+    >
+      {children}
+    </StorefrontProvider>,
+  );
+}
+
+function LocaleProbe(): JSX.Element {
+  const locale = useStorefrontLocale();
+  return <span data-locale={locale ?? 'none'} />;
+}
+
+describe('StorefrontProvider locale prop + useStorefrontLocale', () => {
+  it('exposes the validated locale', () => {
+    expect(render(<LocaleProbe />, 'zh-CN')).toContain('data-locale="zh-CN"');
+  });
+
+  it('is null without the prop (unchanged behaviour)', () => {
+    expect(render(<LocaleProbe />)).toContain('data-locale="none"');
+  });
+
+  it('is null for an invalid prop (ignored, never an error)', () => {
+    expect(render(<LocaleProbe />, 'not a locale!!')).toContain('data-locale="none"');
+  });
+});
+
+const SEED_QUERY = normalizeShopQuery({ categorySlug: 'soups', keyword: 'egusi', sort: 'popular', page: 1, perPage: 24 });
+
+function seedPrefetch(locale?: string | null): ShopPrefetch {
+  const prefetch: ShopPrefetch = {
+    query: SEED_QUERY,
+    products: [product('p1', 'Egusi Soup')],
+    pagination: { currentPage: 1, perPage: 24, hasMore: false },
+  };
+  if (locale !== undefined) prefetch.locale = locale;
+  return prefetch;
+}
+
+function Grid(props: Parameters<typeof useShop>[0]): JSX.Element {
+  const { products, isLoading } = useShop(props);
+  return (
+    <ul data-loading={String(isLoading)}>
+      {products.map((p) => <li key={p.id}>{p.title}</li>)}
+    </ul>
+  );
+}
+
+function renderGrid(prefetch: ShopPrefetch | null, locale?: string | null): string {
+  return render(
+    <ShopPrefetchProvider value={prefetch}>
+      <Grid categorySlug="soups" keyword="egusi" sort="popular" page={1} perPage={24} />
+    </ShopPrefetchProvider>,
+    locale,
+  );
+}
+
+describe('useShop locale cache separation (seed match)', () => {
+  it('seeds from a prefetch fetched in the same locale', () => {
+    const html = renderGrid(seedPrefetch('zh'), 'zh');
+    expect(html).toContain('data-loading="false"');
+    expect(html).toContain('Egusi Soup');
+  });
+
+  it('ignores a prefetch fetched in another locale and refetches', () => {
+    const html = renderGrid(seedPrefetch('zh'), null);
+    expect(html).toContain('data-loading="true"');
+    expect(html).not.toContain('Egusi Soup');
+  });
+
+  it('keeps the old no-locale behaviour: absent echo means primary', () => {
+    const html = renderGrid(seedPrefetch(), null);
+    expect(html).toContain('data-loading="false"');
+    expect(html).toContain('Egusi Soup');
+  });
+});
+
+describe('no-locale regression (byte-identical guarantee)', () => {
+  it('server and client helpers pass input through untouched', () => {
+    const query = { per_page: 24, page: 1 };
+    expect(withLocaleQuery(query, null)).toBe(query);
+    const tags = ['v:acme', 'v:acme:products'];
+    expect(withLocaleTags(tags, null)).toBe(tags);
+    expect(withLocalePath('/client/store/products', null)).toBe('/client/store/products');
+    expect(parseLocaleCode(null)).toBeNull();
+  });
+
+  it('every hook still renders without a provider locale', () => {
+    expect(renderGrid(seedPrefetch(), null)).toContain('data-loading="false"');
+  });
+});