@usequeek/theme-kit 0.1.15 → 0.1.17

package/README.md

@@ -157,6 +157,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/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 };
 }

package/hooks/use-reviews.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 { ReviewItem, ReviewsBlockData, ReviewsSummary } from '../types/block';
 
 interface ReviewsResponse {
@@ -67,6 +68,7 @@ export function useReviews(options: ReviewsBlockData): {
   isLoading: boolean;
 } {
   const { vendor, previewData } = useStorefront();
+  const locale = useStorefrontLocale();
   const seeded = options._preview?.reviews ?? (previewData?.reviews ? resolvePreviewReviews(previewData.reviews, options) : []);
   const [reviews, setReviews] = useState<ReviewItem[]>(seeded);
   const [summary, setSummary] = useState<ReviewsSummary>(options._preview?.summary ?? summarize(seeded));
@@ -116,7 +118,7 @@ export function useReviews(options: ReviewsBlockData): {
         let path = '/reviews';
         if (ids && ids.length > 0) {
           const params = new URLSearchParams();
-          for (const [key, value] of Object.entries(query)) {
+          for (const [key, value] of Object.entries(withLocaleQuery(query, locale) ?? {})) {
             params.set(key, String(value));
           }
           ids.forEach((id) => params.append('ids[]', id));
@@ -129,7 +131,7 @@ export function useReviews(options: ReviewsBlockData): {
           return;
         }
 
-        const response = await client.get<ReviewsResponse>('/reviews', query);
+        const response = await client.get<ReviewsResponse>('/reviews', withLocaleQuery(query, locale));
         if (!cancelled) {
           setReviews(response.data.reviews ?? []);
           setSummary(response.data.summary ?? EMPTY_SUMMARY);
@@ -161,6 +163,7 @@ export function useReviews(options: ReviewsBlockData): {
     with_media,
     limit,
     sort,
+    locale,
   ]);
 
   return { reviews, summary, isLoading };

package/hooks/use-shop.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { createContext, createElement, useContext, useEffect, useMemo, useRef, useState, type JSX, type ReactNode } from 'react';
-import { useStorefront } from '../provider';
+import { useStorefront, useStorefrontLocale } from '../provider';
 import type { Product, ApiResponse } from '../types/product';
 import { createBrowserClient } from '../sdk/client';
+import { localeCacheKeySegment, withLocaleQuery } from '../utils/locale';
 import {
   SHOP_DEFAULT_PER_PAGE,
   normalizeShopQuery,
@@ -95,6 +96,7 @@ export function useShop(options?: {
   pagination: ShopPagination;
 } {
   const { vendor, previewData } = useStorefront();
+  const locale = useStorefrontLocale();
   const prefetch = useContext(ShopPrefetchContext);
 
   const perPage = options?.perPage ?? SHOP_DEFAULT_PER_PAGE;
@@ -107,15 +109,25 @@ export function useShop(options?: {
   const previewProducts = previewData?.products;
   const isPreview = Array.isArray(previewProducts);
 
-  // The server's page, when it is exactly this query (see ShopPrefetchProvider).
-  const seed = !isPreview && prefetch && sameShopQuery(prefetch.query, query) ? prefetch : null;
+  // The server's page, when it is exactly this query IN THIS LOCALE (see
+  // ShopPrefetchProvider). The locale check keeps two locales from sharing
+  // the seeded grid; an absent prefetch locale means primary, as before.
+  const seed = !isPreview && prefetch && sameShopQuery(prefetch.query, query) && (prefetch.locale ?? null) === locale ? prefetch : null;
+
+  // Client cache key: the query plus the locale dimension, so two locales
+  // never share fetched results. Unset locale leaves it the query JSON
+  // alone — exactly the key it always was.
+  const queryKey = JSON.stringify(query);
+  const localeSegment = localeCacheKeySegment(locale);
+  const fetchKey = localeSegment ? `${queryKey}::locale:${localeSegment}` : queryKey;
 
   const [products, setProducts] = useState<Product[]>(seed?.products ?? []);
   const [isLoading, setIsLoading] = useState(!isPreview && !seed);
   const [pagination, setPagination] = useState<ShopPagination>(seed?.pagination ?? { ...EMPTY_PAGINATION, perPage });
-  // The query whose results are already in state. Seeded with the prefetch so
-  // the first effect run does not refetch the page the server just rendered.
-  const loadedQueryRef = useRef<string | null>(seed ? JSON.stringify(seed.query) : null);
+  // The key whose results are already in state. Seeded with the prefetch so
+  // the first effect run does not refetch the page the server just rendered
+  // (the seed's locale already matches `locale`, so `fetchKey` is its key).
+  const loadedQueryRef = useRef<string | null>(seed ? fetchKey : null);
 
   // Preview: derive everything synchronously from the demo catalogue.
   const previewResult = useMemo(() => {
@@ -140,12 +152,12 @@ export function useShop(options?: {
   }, [isPreview, previewProducts, categorySlug, keyword, sort, page, perPage]);
 
   // Production: fetch the live catalogue.
-  const queryKey = JSON.stringify(query);
   useEffect(() => {
     if (isPreview) return undefined;
-    // Already showing this query — the server's prefetch, or a fetch that
-    // finished. (Clear any loading state a cancelled in-between query left.)
-    if (loadedQueryRef.current === queryKey) {
+    // Already showing this query in this locale — the server's prefetch, or
+    // a fetch that finished. (Clear any loading state a cancelled
+    // in-between query left.)
+    if (loadedQueryRef.current === fetchKey) {
       setIsLoading(false);
       return undefined;
     }
@@ -162,14 +174,14 @@ export function useShop(options?: {
       try {
         const response = await client.get<ApiResponse<unknown, Record<string, unknown>>>(
           '/products',
-          shopRequestParams(current),
+          withLocaleQuery(shopRequestParams(current), locale),
         );
         if (cancelled) return;
 
         const parsed = parseShopResponse(response, current);
         setPagination(parsed.pagination);
         setProducts(parsed.products);
-        loadedQueryRef.current = queryKey;
+        loadedQueryRef.current = fetchKey;
       } finally {
         if (!cancelled) setIsLoading(false);
       }
@@ -180,7 +192,7 @@ export function useShop(options?: {
     return () => {
       cancelled = true;
     };
-  }, [isPreview, vendor.slug, queryKey]);
+  }, [isPreview, vendor.slug, queryKey, fetchKey, locale]);
 
   if (isPreview && previewResult) {
     return { products: previewResult.products, isLoading: false, pagination: previewResult.pagination };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

package/provider.tsx

@@ -8,6 +8,7 @@ import type { Post } from './types/page';
 import type { Product } from './types/product';
 import type { StorefrontConfig, VendorProfile } from './types/vendor';
 import { getBrandCssVariables } from './utils/brand';
+import { parseLocaleCode } from './utils/locale';
 import { DesignTokenPreviewListener } from './design-token-preview';
 
 export interface StorefrontPreviewData {
@@ -36,6 +37,9 @@ interface StorefrontContextValue {
   /** slug => 'full' | 'bare', for ShellInner to decide the CURRENT page's
    * header/footer without a per-navigation fetch. See VendorShell. */
   pagesChrome: Record<string, 'full' | 'bare'>;
+  /** Validated request locale (null = primary). Browser hooks read it via
+   * `useStorefrontLocale()` and send `?locale=` when it is set. */
+  locale: string | null;
 }
 
 export const StorefrontContext = createContext<StorefrontContextValue | null>(null);
@@ -47,6 +51,7 @@ export function StorefrontProvider({
   previewData,
   basePath,
   pagesChrome,
+  locale,
   children,
 }: {
   vendor: VendorProfile;
@@ -55,9 +60,17 @@ export function StorefrontProvider({
   previewData?: StorefrontPreviewData;
   basePath?: string;
   pagesChrome?: Record<string, 'full' | 'bare'>;
+  /**
+   * Request locale for translated reads (the storefront host passes its
+   * `x-queek-locale` request header through). Optional — absent/invalid
+   * means the primary locale, exactly as before. Themes never set this;
+   * the host owns it, like `basePath`.
+   */
+  locale?: string | null;
   children: ReactNode;
 }): JSX.Element {
   const resolvedBasePath = basePath ?? `/${vendor.slug ?? ''}`;
+  const resolvedLocale = parseLocaleCode(locale);
   const value = useMemo(
     () => ({
       vendor,
@@ -66,8 +79,9 @@ export function StorefrontProvider({
       previewData,
       basePath: resolvedBasePath,
       pagesChrome: pagesChrome ?? {},
+      locale: resolvedLocale,
     }),
-    [config, menus, previewData, vendor, resolvedBasePath, pagesChrome],
+    [config, menus, previewData, vendor, resolvedBasePath, pagesChrome, resolvedLocale],
   );
   const brandRootRef = useRef<HTMLDivElement>(null);
 
@@ -90,3 +104,19 @@ export function useStorefront(): StorefrontContextValue {
 
   return context;
 }
+
+/**
+ * Validated request locale for translated reads (`null` = primary).
+ * Browser hooks send `?locale=` when this is set and key their client
+ * caches by it, so two locales never share an entry. No provider prop →
+ * null, and every hook behaves exactly as before.
+ */
+export function useStorefrontLocale(): string | null {
+  const context = useContext(StorefrontContext);
+
+  if (!context) {
+    throw new Error('useStorefrontLocale must be used within StorefrontProvider');
+  }
+
+  return context.locale ?? null;
+}

package/sdk/server-store-client.ts

@@ -1,5 +1,6 @@
 import { headers } from 'next/headers';
 import { resolveCustomDomainVendorSlug, resolveCustomDomainVendorSlugRemote, resolveSubdomainVendorSlug } from '../utils/vendor-host';
+import { LOCALE_CODE_HEADER, parseLocaleCode, withLocaleQuery, withLocaleTags } from '../utils/locale';
 import { API_BASE_URL, request, type RequestCachePolicy, type RequestOptions } from './client';
 import { getActivePlatform } from './platform';
 
@@ -142,8 +143,52 @@ async function isPreviewRender(): Promise<boolean> {
   return h.get('x-queek-preview') === '1';
 }
 
+/**
+ * Validated locale of the incoming storefront request, or null for the
+ * primary rendering. The proxy sets `x-queek-locale` for published
+ * non-primary locales ONLY (absent on the primary); anything else is
+ * ignored, mirroring the backend's unknown-locale → source-text rule.
+ *
+ * THE single header-parsing site — every server fetcher resolves its locale
+ * through here (directly or via `resolveRequestLocale`), never by reading
+ * `next/headers` itself. Never throws: outside a request scope `headers()`
+ * throws, which is treated as no locale (today's behaviour).
+ */
+export async function readRequestLocale(): Promise<string | null> {
+  try {
+    const h = await headers();
+    return parseLocaleCode(h.get(LOCALE_CODE_HEADER));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Effective locale for one server read: an explicit override wins when
+ * valid, otherwise the incoming request's header decides. Invalid values in
+ * either place are ignored (never an error).
+ */
+export async function resolveRequestLocale(explicit?: string | null): Promise<string | null> {
+  return parseLocaleCode(explicit) ?? readRequestLocale();
+}
+
+/**
+ * Adds the locale dimension to a resolved cache policy: every tag is
+ * suffixed (`<tag>:locale:<code>`) so one locale's entries never share an
+ * entry with another's, and the revalidate route's `<tag>:locale:<code>`
+ * contract clears exactly that locale. No locale → the policy is returned
+ * untouched (same reference, byte-identical tags).
+ */
+export function withLocaleCachePolicy(
+  policy: RequestCachePolicy | null,
+  locale: string | null | undefined,
+): RequestCachePolicy | null {
+  if (!policy || !parseLocaleCode(locale)) return policy;
+  return { revalidate: policy.revalidate, tags: withLocaleTags(policy.tags, locale) };
+}
+
 export function createServerStoreClient(vendorSlug: string, origin?: string): {
-  get: <T>(path: string, query?: RequestOptions['query']) => Promise<T>;
+  get: <T>(path: string, query?: RequestOptions['query'], locale?: string) => Promise<T>;
   post: <T>(path: string, body?: unknown) => Promise<T>;
 } {
   const buildHeaders = (): Record<string, string> => {
@@ -156,17 +201,26 @@ export function createServerStoreClient(vendorSlug: string, origin?: string): {
   };
 
   return {
-    get: async <T>(path: string, query?: RequestOptions['query']) =>
-      request<T>(
+    // `locale` is an explicit override; when omitted the incoming request's
+    // `x-queek-locale` header decides. Either way an absent/invalid locale
+    // leaves the query and the tags exactly as today (translated reads are
+    // strictly additive: `locale=<code>` on the URL plus a `:locale:<code>`
+    // suffix on every cache tag).
+    get: async <T>(path: string, query?: RequestOptions['query'], locale?: string) => {
+      const code = await resolveRequestLocale(locale);
+      return request<T>(
         API_BASE_URL,
         `/client/store${path}`,
         {
-          query,
+          query: withLocaleQuery(query, code),
           timeoutMs: SSR_TIMEOUT_MS,
-          cachePolicy: (await isPreviewRender()) ? null : resolveCachePolicy(vendorSlug, path),
+          cachePolicy: (await isPreviewRender())
+            ? null
+            : withLocaleCachePolicy(resolveCachePolicy(vendorSlug, path), code),
         },
         buildHeaders(),
-      ),
+      );
+    },
     post: <T>(path: string, body?: unknown) =>
       request<T>(API_BASE_URL, `/client/store${path}`, {
         method: 'POST',

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"');
+  });
+});

package/tests/orders-walk.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { fetchOrders } from '../api/orders';
+
+/**
+ * `GET store/orders` answers the ONE storefront list envelope (pagination
+ * Slice 4b, founder 28/9/26): `has_more` + `next_cursor` top-level, no
+ * `links`, no paginator `meta`. The kit reads the page it asked for.
+ */
+describe('fetchOrders walk state', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('asks /client/store/orders by page and returns the top-level walk state', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        status: 'success',
+        message: 'Orders retrieved',
+        data: [{ id: 'o1', order_no: 'Q-1' }],
+        meta: { currency: { code: 'NGN' } },
+        has_more: true,
+        next_cursor: 'eyJ2IjoxfQ',
+      }),
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const page = await fetchOrders('kili-foods', 2, 'ongoing');
+
+    const url = String((fetchMock.mock.calls[0] as unknown[])[0]);
+    expect(url).toContain('/client/store/orders');
+    expect(url).toContain('page=2');
+    expect(url).toContain('status=ongoing');
+    expect(page.has_more).toBe(true);
+    expect(page.next_cursor).toBe('eyJ2IjoxfQ');
+    expect(page).not.toHaveProperty('links');
+    expect(page.data).toHaveLength(1);
+  });
+
+  it('never sends status=all (the unfiltered list)', async () => {
+    const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ data: [], has_more: false, next_cursor: null }) }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const page = await fetchOrders('kili-foods', 1, 'all');
+
+    expect(String((fetchMock.mock.calls[0] as unknown[])[0])).not.toContain('status=');
+    expect(page.has_more).toBe(false);
+    expect(page.next_cursor).toBeNull();
+  });
+});

package/types/order.ts

@@ -85,16 +85,18 @@ export interface OrderDetail {
   table?: { id: string; name: string; section?: string | null } | null;
 }
 
-export interface OrderPageMeta {
-  current_page: number;
-  last_page: number;
-  per_page: number;
-  total: number;
-}
-
+/**
+ * `GET store/orders` — the ONE storefront list envelope: the walk state rides
+ * top-level. A page-mode reader (`?page=N`) labels the page it asked for and
+ * loads the next while `has_more` is true; a cursor reader passes
+ * `next_cursor` back as `starting_after`. No totals, page counts or page URLs
+ * are sent; `meta` is context only (e.g. `currency`).
+ */
 export interface OrderListResponse {
   data: OrderListItem[];
-  meta: OrderPageMeta;
+  has_more: boolean;
+  next_cursor: string | null;
+  meta?: Record<string, unknown>;
 }
 
 export interface CheckoutPayload {

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?: {