@usequeek/theme-kit 0.1.16 → 0.1.18

package/README.md

@@ -42,6 +42,47 @@ Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks
 (framework-owned blocks), plus per-component CSS next to its component
 (`components/variant-picker.css`, `apps/apps.css`).
 
+## Theme strings
+
+The kit's Shopify-shaped UI-string mechanism (`strings/theme-strings.ts`,
+pure: no `next/*`, no React). Additive and backward-compatible — a theme or
+provider that passes nothing renders exactly as today, in English.
+
+- **Authoring contract.** `t(dictionaries, key, vars?, locale?)`: dot-path
+  lookup (`cart.title`), `{var}` interpolation (`{{`/`}}` escape to literal
+  braces; a missing var keeps its `{placeholder}`), CLDR plurals via
+  `Intl.PluralRules` — a key holding `{ one, two, few, many, other }`
+  (nested, or flat `key.one` … `key.other` suffix keys) selects by
+  `vars.count`, defaulting to `other`. Locale-aware `formatThemeNumber`,
+  `formatThemeDate` and `formatThemeMoney` replace hardcoded `en-GB`
+  formatting; an unknown locale falls back to English. Keys are dotted
+  lowercase `scope.thing.state`, max **40 chars**; values max **1000 chars**:
+  the backend overlay stores `<theme-slug>.<key>` in a varchar(64), so the
+  key budget leaves 23 chars for the slug plus the dot.
+- **Two surfaces.** Server (provider-free): the host supplies per-locale
+  loaders and calls
+  `createThemeStrings({ locale, loaders })` — `{ override, theme, core }`,
+  each `(locale) => Promise<dict | null>` — usually a per-locale dynamic
+  `import()` with a try/catch returning null when the file is absent — then
+  passes the bound `t` via props/closure. A throwing loader simply drops
+  out of the chain.
+  Client: `<StorefrontProvider strings={…}>` (optional, no-op when absent)
+  plus `useThemeStrings()` returning the same bound `t`; works inside
+  `ThemeMount`. The kit ships `locales/en.default.json` (cart, checkout,
+  auth, blog) as the last-resort English default.
+- **Fallback.** Ordered dictionaries (override → theme → core → English
+  default); first hit wins. The last fallback is the English default
+  *value* — never the raw key, never "translation missing". Absent
+  everywhere renders `""` (and warns once per key in development only —
+  an empty string would otherwise leak internal key names into the UI).
+- **Per-locale loading.** `createThemeStrings` reads ONLY the active
+  locale's dictionaries, and the host passes ONLY that locale to the
+  provider — other `{lang}.json` files never enter the client bundle.
+  Only `locales/en.default.json` may be statically imported (by
+  `strings/theme-strings.ts` itself); every other locale arrives via the
+  host's dynamic `import()` per locale. `tests/theme-strings.test.tsx`
+  gates this: any other static locale import fails the suite.
+
 ## Consumers
 
 - **The Queek storefront** (`usequeek/queek-storefront`) installs this package
@@ -157,6 +198,32 @@ export default function Footer() {
   the seam for a possible future plan perk. There is no merchant-facing
   toggle for it in v1 — always render it visible.
 
+## Locales
+
+Customer-facing reads accept `?locale=<code>` and answer translated text
+(unknown/unpublished locale → source text, no error). The kit forwards the
+request locale on every catalogue/content transport, server and browser:
+
+- Server: `createServerStoreClient().get()` reads the incoming request's
+  `x-queek-locale` header (set by the storefront proxy for published
+  non-primary locales only — absent on the primary), appends `locale=<code>`
+  to the backend URL, and suffixes every cache tag with `:locale:<code>` so
+  locales never share a cache entry. `fetchShopPrefetch`, `fetchCollections`,
+  `fetchCollection` and `fetchCollectionProducts` take the same behaviour plus
+  an optional explicit override. No header → byte-identical requests and tags.
+- Browser: `StorefrontProvider` takes an optional `locale` prop (the host
+  passes its request header through) and `useStorefrontLocale()` exposes it.
+  `useShop`, `useProducts`/`useProductBySlug`, `useRelatedProducts`,
+  `useProductSections`, `useCategories`, `usePosts`, `useReviews`,
+  `useProductQuestions` and `useProductDetail` send `?locale=` when it is set
+  and key their client caches by it. No prop → unchanged.
+
+What this means for themes: nothing to handle. Never read the header, never
+append `locale` yourself, and never build a language switcher — locale
+routing, `basePath` prefixing and the switcher are core-owned in the
+storefront. Links built from `basePath` keep their locale prefix with zero
+theme changes.
+
 ## Links and navigation
 
 ```ts

package/api/collections.ts

@@ -13,18 +13,20 @@ export interface FetchCollectionProductsOptions {
   perPage?: number;
   sort?: CollectionSort;
   keyword?: string;
+  /** Explicit locale override; when omitted the request's `x-queek-locale` header decides. */
+  locale?: string;
 }
 
 // SSR collection reads go through `/client/store/*` so ResolveClientContext forces
 // X-Platform=storefront (base prices, no marketplace commission) — never the
 // legacy v1 routes shared with the commission-bearing marketplace.
-export async function fetchCollections(vendorSlug: string, storefrontOnly = true): Promise<Collection[]> {
+export async function fetchCollections(vendorSlug: string, storefrontOnly = true, locale?: string): Promise<Collection[]> {
   const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
 
   try {
     const response = await client.get<ApiResponse<Collection[]>>(`/collections`, {
       storefront: storefrontOnly ? 1 : 0,
-    });
+    }, locale);
 
     return response.data ?? [];
   } catch (error) {
@@ -34,8 +36,8 @@ export async function fetchCollections(vendorSlug: string, storefrontOnly = true
   }
 }
 
-export async function fetchCollection(vendorSlug: string, slug: string): Promise<Collection | null> {
-  const collections = await fetchCollections(vendorSlug);
+export async function fetchCollection(vendorSlug: string, slug: string, locale?: string): Promise<Collection | null> {
+  const collections = await fetchCollections(vendorSlug, true, locale);
 
   return collections.find((collection) => collection.slug === slug) ?? null;
 }
@@ -60,8 +62,8 @@ export async function fetchCollectionProducts(
 
   try {
     const [collection, response] = await Promise.all([
-      fetchCollection(vendorSlug, slug),
-      client.get<ApiResponse<unknown, Record<string, unknown>>>(`/collections/${slug}/products`, query),
+      fetchCollection(vendorSlug, slug, options?.locale),
+      client.get<ApiResponse<unknown, Record<string, unknown>>>(`/collections/${slug}/products`, query, options?.locale),
     ]);
 
     return {

package/api/shop.ts

@@ -1,4 +1,4 @@
-import { createServerStoreClient, getRequestOrigin } from '../sdk/server-store-client';
+import { createServerStoreClient, getRequestOrigin, resolveRequestLocale } from '../sdk/server-store-client';
 import type { ApiResponse } from '../types/product';
 import { parseShopResponse, shopRequestParams, type ShopPrefetch, type ShopQuery } from '../utils/shop-query';
 
@@ -15,11 +15,15 @@ import { parseShopResponse, shopRequestParams, type ShopPrefetch, type ShopQuery
  * Returns null on ANY failure: the page must never break over a head start —
  * `useShop` then fetches in the browser exactly as it did before.
  */
-export async function fetchShopPrefetch(vendorSlug: string, query: ShopQuery): Promise<ShopPrefetch | null> {
+export async function fetchShopPrefetch(vendorSlug: string, query: ShopQuery, locale?: string): Promise<ShopPrefetch | null> {
   try {
     const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
-    const response = await client.get<ApiResponse<unknown, Record<string, unknown>>>('/products', shopRequestParams(query));
-    return { query, ...parseShopResponse(response, query) };
+    // Explicit override wins; otherwise the request's `x-queek-locale`
+    // header decides (null on the primary) — resolved once here through the
+    // shared helper so the echoed `locale` below is exactly what was fetched.
+    const code = await resolveRequestLocale(locale);
+    const response = await client.get<ApiResponse<unknown, Record<string, unknown>>>('/products', shopRequestParams(query), code ?? undefined);
+    return { query, locale: code, ...parseShopResponse(response, query) };
   } catch {
     return null;
   }

package/components/cart/default-cart-shell.tsx

@@ -5,6 +5,7 @@ import { useRef, useState } from 'react';
 import Link from 'next/link';
 import type { CartShellProps } from '../../types/theme';
 import { useHref } from '../../hooks/use-href';
+import { useThemeStrings } from '../../provider';
 import { useCheckoutStore } from '../../stores/checkout-store';
 import { useRelatedProducts } from '../../hooks/use-related-products';
 import { useCart } from '../../hooks/use-cart';
@@ -27,6 +28,7 @@ export function DefaultCartShell({
   onRemove,
 }: CartShellProps): JSX.Element {
   const href = useHref();
+  const t = useThemeStrings();
   const { addProduct } = useCart();
   const vendorNote = useCheckoutStore((s) => s.vendorNote);
   const setVendorNote = useCheckoutStore((s) => s.setVendorNote);
@@ -48,10 +50,10 @@ export function DefaultCartShell({
   if (empty) {
     return (
       <div className="core-cart-page">
-        <h1 className="core-cart-page__title">Your cart</h1>
+        <h1 className="core-cart-page__title">{t('cart.title')}</h1>
         <div className="core-cart-page__empty">
-          <p>Your cart is empty.</p>
-          <Link href={href('/')} className="core-checkout__back-link">Browse products</Link>
+          <p>{t('cart.empty.message')}</p>
+          <Link href={href('/')} className="core-checkout__back-link">{t('cart.empty.browse')}</Link>
         </div>
       </div>
     );
@@ -59,7 +61,7 @@ export function DefaultCartShell({
 
   return (
     <div className="core-cart-page">
-      <h1 className="core-cart-page__title">Your cart</h1>
+      <h1 className="core-cart-page__title">{t('cart.title')}</h1>
 
       <div className="core-cart-page__grid">
         <div className="core-cart-page__main">
@@ -74,19 +76,19 @@ export function DefaultCartShell({
                   )}
                   <div className="core-cart-page__item-info">
                     <span className="core-cart-page__item-title">{item.title}</span>
-                    <span className="core-cart-page__item-price">{formatMoney(item.unit_price, currency)} each</span>
+                    <span className="core-cart-page__item-price">{t('cart.item.each', { price: formatMoney(item.unit_price, currency) })}</span>
                   </div>
                   <div className="core-cart-page__item-qty">
-                    <button type="button" onClick={() => onDecrease(item.id, item.shop_id)} aria-label={`Decrease ${item.title}`}>
+                    <button type="button" onClick={() => onDecrease(item.id, item.shop_id)} aria-label={t('cart.item.decrease', { title: item.title })}>
                       <svg width="10" height="10" viewBox="0 0 12 12" fill="none" aria-hidden="true"><path d="M2 6h8" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" /></svg>
                     </button>
                     <span>{item.quantity}</span>
-                    <button type="button" onClick={() => onIncrease(item.id, item.shop_id)} aria-label={`Increase ${item.title}`}>
+                    <button type="button" onClick={() => onIncrease(item.id, item.shop_id)} aria-label={t('cart.item.increase', { title: item.title })}>
                       <svg width="10" height="10" viewBox="0 0 12 12" fill="none" aria-hidden="true"><path d="M6 2v8M2 6h8" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" /></svg>
                     </button>
                   </div>
                   <span className="core-cart-page__item-total">{formatMoney(item.unit_price * item.quantity, currency)}</span>
-                  <button type="button" className="core-cart-page__item-remove" onClick={() => onRemove(item.id, item.shop_id)} aria-label={`Remove ${item.title}`}>
+                  <button type="button" className="core-cart-page__item-remove" onClick={() => onRemove(item.id, item.shop_id)} aria-label={t('cart.item.remove', { title: item.title })}>
                     <svg width="16" height="16" viewBox="0 0 20 20" fill="none" aria-hidden="true">
                       <path d="M4 6h12M8 6V4.5A1.5 1.5 0 019.5 3h1A1.5 1.5 0 0112 4.5V6m-6 0v9.5A1.5 1.5 0 007.5 17h5a1.5 1.5 0 001.5-1.5V6" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
                     </svg>
@@ -99,12 +101,12 @@ export function DefaultCartShell({
           {related.length > 0 ? (
             <section className="core-cart-page__related">
               <div className="core-cart-page__related-head">
-                <h2>You may also like</h2>
+                <h2>{t('cart.related.title')}</h2>
                 <div className="core-cart-page__related-nav">
-                  <button type="button" onClick={() => scrollRelated(-1)} aria-label="Previous">
+                  <button type="button" onClick={() => scrollRelated(-1)} aria-label={t('cart.related.prev')}>
                     <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M10 13L5 8l5-5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg>
                   </button>
-                  <button type="button" onClick={() => scrollRelated(1)} aria-label="Next">
+                  <button type="button" onClick={() => scrollRelated(1)} aria-label={t('cart.related.next')}>
                     <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M6 3l5 5-5 5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg>
                   </button>
                 </div>
@@ -125,13 +127,13 @@ export function DefaultCartShell({
                     )}
                     <div className="core-cart-page__related-info">
                       <span className="core-cart-page__related-title">{product.title}</span>
-                      <span className="core-cart-page__related-price">{product.pricing.is_price_from ? 'From ' : ''}{formatMoney(product.pricing.sale_amount, currency)}</span>
+                      <span className="core-cart-page__related-price">{product.pricing.is_price_from ? t('cart.related.from', { price: formatMoney(product.pricing.sale_amount, currency) }) : formatMoney(product.pricing.sale_amount, currency)}</span>
                     </div>
                     {productRequiresVariant(product) ? (
                       <Link
                         className="core-cart-page__related-add"
                         href={href(`/products/${product.slug}`)}
-                        aria-label={`Choose options for ${product.title}`}
+                        aria-label={t('cart.related.choose', { title: product.title })}
                       >
                         <svg width="16" height="16" viewBox="0 0 20 20" fill="none" aria-hidden="true">
                           <path d="M7 4l6 6-6 6" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
@@ -141,7 +143,7 @@ export function DefaultCartShell({
                     <button
                       type="button"
                       className="core-cart-page__related-add"
-                      aria-label={`Add ${product.title} to cart`}
+                      aria-label={t('cart.related.add', { title: product.title })}
                       onClick={() => addProduct(product)}
                     >
                       <svg width="16" height="16" viewBox="0 0 20 20" fill="none" aria-hidden="true">
@@ -160,10 +162,10 @@ export function DefaultCartShell({
 
         <div className="core-cart-page__summary">
           <div className="core-cart-page__summary-card">
-            <h2 className="core-cart-page__summary-title">Order summary</h2>
+            <h2 className="core-cart-page__summary-title">{t('cart.summary.title')}</h2>
 
             <button type="button" className="core-cart-page__note-toggle" onClick={() => setNoteOpen((v) => !v)}>
-              Add order note
+              {t('cart.note.toggle')}
               <span aria-hidden="true">{noteOpen ? '−' : '+'}</span>
             </button>
             {noteOpen ? (
@@ -172,18 +174,18 @@ export function DefaultCartShell({
                 rows={3}
                 value={vendorNote}
                 onChange={(event) => setVendorNote(event.target.value)}
-                placeholder="Order instructions (optional)"
+                placeholder={t('cart.note.placeholder')}
               />
             ) : null}
 
             <div className="core-cart-page__subtotal">
-              <span>Subtotal:</span>
+              <span>{t('cart.summary.subtotal')}</span>
               <strong>{formatMoney(total, currency)} {currency}</strong>
             </div>
 
             <label className="core-cart-page__terms">
               <input type="checkbox" checked={agreed} onChange={(event) => setAgreed(event.target.checked)} />
-              <span>I agree to the <Link href={href('/policies')}>terms and refund policy</Link></span>
+              <span>{t('cart.terms.agree')}<Link href={href('/policies')}>{t('cart.terms.policy')}</Link></span>
             </label>
 
             <Link
@@ -197,9 +199,9 @@ export function DefaultCartShell({
                 <circle cx="8" cy="17" r="1" fill="currentColor" />
                 <circle cx="14" cy="17" r="1" fill="currentColor" />
               </svg>
-              Checkout
+              {t('cart.checkout.action')}
             </Link>
-            <Link href={href('/')} className="core-cart-page__continue-link">Continue shopping</Link>
+            <Link href={href('/')} className="core-cart-page__continue-link">{t('cart.summary.continue')}</Link>
           </div>
         </div>
       </div>

package/hooks/use-categories.ts

@@ -1,8 +1,9 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useStorefront } from '../provider';
+import { useStorefront, useStorefrontLocale } from '../provider';
 import { createBrowserClient } from '../sdk/client';
+import { withLocaleQuery } from '../utils/locale';
 
 export interface Category {
   id: string;
@@ -44,6 +45,7 @@ export function useCategories(options?: {
   isLoading: boolean;
 } {
   const { previewData, vendor } = useStorefront();
+  const locale = useStorefrontLocale();
   const [categories, setCategories] = useState<Category[]>([]);
   const [isLoading, setIsLoading] = useState(true);
 
@@ -78,7 +80,7 @@ export function useCategories(options?: {
         }
 
         const query: Record<string, string> = { include_empty: '1' };
-        const response = await client.get<CategoriesResponse>('/collections', query);
+        const response = await client.get<CategoriesResponse>('/collections', withLocaleQuery(query, locale));
         let items = flattenCategories(Array.isArray(response.data) ? response.data : []);
 
         // Filter by specific IDs if provided — preserving input order
@@ -106,7 +108,7 @@ export function useCategories(options?: {
     return () => {
       cancelled = true;
     };
-  }, [idsKey, limit, previewData?.categories, vendor.slug]);
+  }, [idsKey, limit, previewData?.categories, vendor.slug, locale]);
 
   return { categories, isLoading };
 }

package/hooks/use-posts.ts

@@ -1,10 +1,11 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useStorefront } from '../provider';
+import { useStorefront, useStorefrontLocale } from '../provider';
 import type { ApiResponse } from '../types/product';
 import type { Post } from '../types/page';
 import { createBrowserClient } from '../sdk/client';
+import { withLocaleQuery } from '../utils/locale';
 
 /**
  * Client-side blog-post listing, for blocks embedded on an arbitrary page
@@ -15,6 +16,7 @@ import { createBrowserClient } from '../sdk/client';
  */
 export function usePosts(options?: { category?: string | null; limit?: number }): { posts: Post[]; isLoading: boolean } {
   const { previewData, vendor } = useStorefront();
+  const locale = useStorefrontLocale();
   const [posts, setPosts] = useState<Post[]>([]);
   const [isLoading, setIsLoading] = useState(true);
 
@@ -48,7 +50,7 @@ export function usePosts(options?: { category?: string | null; limit?: number })
         if (options?.category) query.category = options.category;
         if (options?.limit) query.per_page = options.limit;
 
-        const response = await client.get<ApiResponse<Post[]>>('/posts', query);
+        const response = await client.get<ApiResponse<Post[]>>('/posts', withLocaleQuery(query, locale));
 
         if (!cancelled) {
           setPosts(response.data ?? []);
@@ -69,7 +71,7 @@ export function usePosts(options?: { category?: string | null; limit?: number })
     return () => {
       cancelled = true;
     };
-  }, [options?.category, options?.limit, previewData?.posts, vendor.slug]);
+  }, [options?.category, options?.limit, previewData?.posts, vendor.slug, locale]);
 
   return { posts, isLoading };
 }

package/hooks/use-product-detail.ts

@@ -2,6 +2,7 @@
 
 import { useEffect, useState } from 'react';
 import { getQueekClient } from '../sdk/queek-client';
+import { withLocalePath } from '../utils/locale';
 import { normalizeProduct } from '../utils/product-normalizer';
 import type { Product, LegacyProductLike } from '../types/product';
 
@@ -28,6 +29,14 @@ export function useProductDetail(
   listProduct: Product | null,
   isOpen: boolean,
   vendorSlug?: string | null,
+  /**
+   * Request locale for the detail read (pass `useStorefrontLocale()`).
+   * Optional — absent/invalid fetches exactly as before. A separate
+   * parameter (rather than provider context) because this hook deliberately
+   * takes the vendor slug explicitly and must keep working outside a
+   * provider.
+   */
+  locale?: string | null,
 ): UseProductDetailResult {
   const [fullProduct, setFullProduct] = useState<Product | null>(null);
   const [loadingDetail, setLoadingDetail] = useState(false);
@@ -47,7 +56,7 @@ export function useProductDetail(
 
     const client = getQueekClient(vendorSlug ?? undefined);
     client
-      .get<{ data?: LegacyProductLike } | LegacyProductLike>(`/client/store/products/${listProduct.slug}`)
+      .get<{ data?: LegacyProductLike } | LegacyProductLike>(withLocalePath(`/client/store/products/${listProduct.slug}`, locale))
       .then((res) => {
         if (cancelled) return;
         const raw = (res as { data?: LegacyProductLike })?.data ?? res;
@@ -63,7 +72,7 @@ export function useProductDetail(
     return () => {
       cancelled = true;
     };
-  }, [isOpen, listProduct, vendorSlug]);
+  }, [isOpen, listProduct, vendorSlug, locale]);
 
   return { product: fullProduct ?? listProduct, loadingDetail };
 }

package/hooks/use-product-questions.ts

@@ -1,8 +1,9 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useStorefront } from '../provider';
+import { useStorefront, useStorefrontLocale } from '../provider';
 import { createBrowserClient } from '../sdk/client';
+import { withLocaleQuery } from '../utils/locale';
 import type { ProductQaBlockData, ProductQuestionItem } from '../types/block';
 
 interface ProductQuestionsResponse {
@@ -20,6 +21,7 @@ export function useProductQuestions(options: ProductQaBlockData): {
   isLoading: boolean;
 } {
   const { vendor, previewData } = useStorefront();
+  const locale = useStorefrontLocale();
   const [questions, setQuestions] = useState<ProductQuestionItem[]>(options._preview?.questions ?? []);
   const [isLoading, setIsLoading] = useState(!options._preview && !previewData);
 
@@ -52,7 +54,7 @@ export function useProductQuestions(options: ProductQaBlockData): {
       try {
         const response = await client.get<ProductQuestionsResponse>(
           `/products/${product_slug}/questions`,
-          query,
+          withLocaleQuery(query, locale),
         );
         if (!cancelled) {
           setQuestions(response.data.questions ?? []);
@@ -72,7 +74,7 @@ export function useProductQuestions(options: ProductQaBlockData): {
       cancelled = true;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [vendor.slug, previewData, product_slug, limit]);
+  }, [vendor.slug, previewData, product_slug, limit, locale]);
 
   return { questions, isLoading };
 }

package/hooks/use-product-sections.ts

@@ -1,10 +1,11 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useStorefront } from '../provider';
+import { useStorefront, useStorefrontLocale } from '../provider';
 import type { Product, ApiResponse, LegacyProductLike } from '../types/product';
 import { createBrowserClient } from '../sdk/client';
 import { getActivePlatform } from '../sdk/platform';
+import { localeCacheKeySegment, withLocaleQuery } from '../utils/locale';
 import { normalizeProduct } from '../utils/product-normalizer';
 
 export interface ProductSection {
@@ -59,9 +60,15 @@ export function useProductSections(): {
   isLoading: boolean;
 } {
   const { previewData, vendor } = useStorefront();
+  const locale = useStorefrontLocale();
   // Cache per vendor AND platform — the grouped catalogue can differ between
-  // storefront and instore_qr (the /qr page).
-  const cacheKey = `${vendor.slug ?? ''}::${getActivePlatform()}`;
+  // storefront and instore_qr (the /qr page) — AND locale, so two locales
+  // never share a client cache entry. The locale segment is appended only
+  // when set, leaving no-locale keys exactly what they always were.
+  const localeSegment = localeCacheKeySegment(locale);
+  const cacheKey = localeSegment
+    ? `${vendor.slug ?? ''}::${getActivePlatform()}::${localeSegment}`
+    : `${vendor.slug ?? ''}::${getActivePlatform()}`;
   const [result, setResult] = useState<SectionsResult>(() => sectionsCache.get(cacheKey) ?? EMPTY_RESULT);
   const [isLoading, setIsLoading] = useState(!sectionsCache.has(cacheKey));
 
@@ -108,7 +115,7 @@ export function useProductSections(): {
     if (!promise) {
       const client = createBrowserClient(vendor.slug ?? undefined);
       promise = client
-        .get<ApiResponse<unknown>>('/products')
+        .get<ApiResponse<unknown>>('/products', withLocaleQuery(undefined, locale))
         .then((response) => {
           const data = response.data;
           // instore_qr only — backend attaches this under meta.groups, never
@@ -159,7 +166,7 @@ export function useProductSections(): {
     });
 
     return () => { cancelled = true; };
-  }, [previewData?.products, vendor.slug, cacheKey]);
+  }, [previewData?.products, vendor.slug, cacheKey, locale]);
 
   return { sections: result.sections, groups: result.groups, isLoading };
 }

package/hooks/use-products.ts

@@ -1,10 +1,11 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useStorefront } from '../provider';
+import { useStorefront, useStorefrontLocale } from '../provider';
 import type { Product } from '../types/product';
 import type { ApiResponse, LegacyProductLike, ProductListMeta } from '../types/product';
 import { createBrowserClient } from '../sdk/client';
+import { withLocaleQuery } from '../utils/locale';
 import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
 
 type ProductQuery = {
@@ -49,6 +50,7 @@ export function useProducts(options?: ProductQuery & {
   hasVideo?: boolean;
 }): { products: Product[]; isLoading: boolean } {
   const { previewData, vendor } = useStorefront();
+  const locale = useStorefrontLocale();
   const hasPreviewProducts = Array.isArray(previewData?.products);
   const [products, setProducts] = useState<Product[]>(() => (
     options && hasPreviewProducts ? resolvePreviewProducts(previewData.products!, options) : []
@@ -92,6 +94,7 @@ export function useProducts(options?: ProductQuery & {
         if (options?.collection) {
           const response = await client.get<ApiResponse<unknown>>(
             `/collections/${options.collection}/products`,
+            withLocaleQuery(undefined, locale),
           );
           resolvedProducts = extractProducts(response.data).map((p) => normalizeProduct(p));
         } else {
@@ -106,7 +109,7 @@ export function useProducts(options?: ProductQuery & {
           // silently dropping hand-picked products from the storefront.
           if (options?.ids && options.ids.length > 0) query.ids = options.ids;
 
-          const response = await client.get<ApiResponse<unknown, ProductListMeta>>('/products', query);
+          const response = await client.get<ApiResponse<unknown, ProductListMeta>>('/products', withLocaleQuery(query, locale));
           resolvedProducts = extractProducts(response.data).map((p) => normalizeProduct(p));
         }
 
@@ -138,7 +141,7 @@ export function useProducts(options?: ProductQuery & {
     return () => {
       cancelled = true;
     };
-  }, [hasOptions, options?.collection, options?.ids, options?.limit, options?.sort, options?.hasVideo, previewData?.products, vendor.slug]);
+  }, [hasOptions, options?.collection, options?.ids, options?.limit, options?.sort, options?.hasVideo, previewData?.products, vendor.slug, locale]);
 
   return { products, isLoading };
 }
@@ -165,6 +168,7 @@ export function useProducts(options?: ProductQuery & {
  */
 export function useProductBySlug(slug: string | null | undefined): { product: Product | null; isLoading: boolean } {
   const { previewData, vendor } = useStorefront();
+  const locale = useStorefrontLocale();
   const [product, setProduct] = useState<Product | null>(null);
   const [isLoading, setIsLoading] = useState(!!slug);
 
@@ -190,7 +194,7 @@ export function useProductBySlug(slug: string | null | undefined): { product: Pr
     async function run(): Promise<void> {
       setIsLoading(true);
       try {
-        const response = await client.get<ApiResponse<LegacyProductLike>>(`/products/${slug}`);
+        const response = await client.get<ApiResponse<LegacyProductLike>>(`/products/${slug}`, withLocaleQuery(undefined, locale));
         const products = extractProducts(response.data);
         const payload = products[0] ?? response.data;
         if (!cancelled) {
@@ -212,7 +216,7 @@ export function useProductBySlug(slug: string | null | undefined): { product: Pr
     return () => {
       cancelled = true;
     };
-  }, [slug, previewData?.products, vendor.slug]);
+  }, [slug, previewData?.products, vendor.slug, locale]);
 
   return { product, isLoading };
 }

package/hooks/use-related-products.ts

@@ -1,10 +1,11 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useStorefront } from '../provider';
+import { useStorefront, useStorefrontLocale } from '../provider';
 import type { Product } from '../types/product';
 import type { ApiResponse } from '../types/product';
 import { createBrowserClient } from '../sdk/client';
+import { withLocaleQuery } from '../utils/locale';
 import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
 
 export function useRelatedProducts(
@@ -12,6 +13,7 @@ export function useRelatedProducts(
   limit = 4,
 ): { products: Product[]; isLoading: boolean } {
   const { vendor, previewData } = useStorefront();
+  const locale = useStorefrontLocale();
   const [products, setProducts] = useState<Product[]>([]);
   const [isLoading, setIsLoading] = useState(true);
 
@@ -32,7 +34,7 @@ export function useRelatedProducts(
         const client = createBrowserClient(vendor.slug ?? undefined);
         const response = await client.get<ApiResponse<unknown>>(
           `/products/${currentSlug}/related`,
-          { limit },
+          withLocaleQuery({ limit }, locale),
         );
 
         const raw = extractProducts(response.data);
@@ -50,7 +52,7 @@ export function useRelatedProducts(
 
     void run();
     return () => { cancelled = true; };
-  }, [currentSlug, limit, vendor.slug, previewData?.products]);
+  }, [currentSlug, limit, vendor.slug, previewData?.products, locale]);
 
   return { products, isLoading };
 }