@usequeek/theme-kit 0.1.16 → 0.1.18

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/index.ts

@@ -49,5 +49,8 @@ export * from './utils/video-embed';
 export * from './utils/match-variant';
 export * from './utils/announcement';
 
+// Theme strings — the pure/server-safe i18n core (no next/*, no React).
+export * from './strings/theme-strings';
+
 // Rendering a theme's own demo.json — what makes local preview possible.
 export * from './demo';

package/locales/en.default.json

@@ -0,0 +1,138 @@
+{
+  "cart": {
+    "title": "Your cart",
+    "empty": {
+      "message": "Your cart is empty.",
+      "browse": "Browse products"
+    },
+    "item": {
+      "each": "{price} each",
+      "decrease": "Decrease {title}",
+      "increase": "Increase {title}",
+      "remove": "Remove {title}"
+    },
+    "related": {
+      "title": "You may also like",
+      "prev": "Previous",
+      "next": "Next",
+      "choose": "Choose options for {title}",
+      "add": "Add {title} to cart",
+      "from": "From {price}"
+    },
+    "summary": {
+      "title": "Order summary",
+      "subtotal": "Subtotal:",
+      "continue": "Continue shopping"
+    },
+    "note": {
+      "toggle": "Add order note",
+      "placeholder": "Order instructions (optional)"
+    },
+    "terms": {
+      "agree": "I agree to the ",
+      "policy": "terms and refund policy"
+    },
+    "checkout": {
+      "action": "Checkout"
+    }
+  },
+  "checkout": {
+    "empty": {
+      "message": "Your cart is empty.",
+      "browse": "Browse products"
+    },
+    "page": {
+      "back": "Continue shopping"
+    },
+    "contact": {
+      "label": "Contact",
+      "signin": "Sign in",
+      "signout": "Sign out",
+      "options": "Account options"
+    },
+    "delivery": {
+      "title": "How you'll get it"
+    },
+    "zone": {
+      "title": "Shipping zone"
+    },
+    "address": {
+      "title": "Delivery address"
+    },
+    "schedule": {
+      "title": "Schedule"
+    },
+    "payment": {
+      "title": "Payment",
+      "secure": "All transactions are secure and encrypted."
+    },
+    "summary": {
+      "title": "Order summary",
+      "empty": "Your cart is empty",
+      "subtotal": "Subtotal",
+      "proceed": "Proceed to checkout"
+    },
+    "tabs": {
+      "summary": "Summary",
+      "checkout": "Checkout"
+    },
+    "policy": {
+      "close": "Close",
+      "view": "View full page",
+      "list": "Store policies"
+    }
+  },
+  "auth": {
+    "login": {
+      "title": "Sign in",
+      "subtitle": "Enter your email and password",
+      "email": "Email address",
+      "password": "Password"
+    },
+    "email": {
+      "title": "Sign in",
+      "subtitle": "Enter your email to continue",
+      "or": "or",
+      "placeholder": "your@email.com"
+    },
+    "code": {
+      "title": "Enter code",
+      "sent": "{length}-digit code sent to {email}",
+      "digit": "Digit {index}"
+    },
+    "register": {
+      "title": "Create account",
+      "subtitle": "Fill in your details to get started",
+      "first": "First name",
+      "last": "Last name (optional)",
+      "email": "Email address",
+      "password": "Password (min 8 characters)"
+    },
+    "signup": {
+      "title": "Create your account",
+      "subtitle": "Just a few details to get you started",
+      "first": "First name",
+      "last": "Last name (optional)"
+    }
+  },
+  "blog": {
+    "pagination": {
+      "prev": "← Previous",
+      "next": "Next →",
+      "nav": "Blog pagination",
+      "page": "Page {current}"
+    },
+    "filter": {
+      "all": "All",
+      "nav": "Blog categories"
+    },
+    "share": {
+      "label": "Share",
+      "action": "Share",
+      "x": "Share on X",
+      "facebook": "Share on Facebook",
+      "whatsapp": "Share on WhatsApp",
+      "copy": "Copy link"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",
@@ -23,6 +23,7 @@
     "**/*.ts",
     "**/*.tsx",
     "**/*.css",
+    "locales/*.json",
     "README.md",
     "LICENSE"
   ],

package/provider.tsx

@@ -8,6 +8,14 @@ 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 {
+  defaultThemeStrings,
+  t as translateThemeStrings,
+  type ThemeStringsDictionary,
+  type ThemeStringsFn,
+  type ThemeStringsVars,
+} from './strings/theme-strings';
 import { DesignTokenPreviewListener } from './design-token-preview';
 
 export interface StorefrontPreviewData {
@@ -36,6 +44,12 @@ 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;
+  /** Active locale's dictionaries (override, theme, core — the host merges and
+   * passes ONLY the active locale). Empty = English defaults only. */
+  strings: ThemeStringsDictionary[];
 }
 
 export const StorefrontContext = createContext<StorefrontContextValue | null>(null);
@@ -47,6 +61,8 @@ export function StorefrontProvider({
   previewData,
   basePath,
   pagesChrome,
+  locale,
+  strings,
   children,
 }: {
   vendor: VendorProfile;
@@ -55,9 +71,34 @@ 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;
+  /**
+   * Active locale's theme-string dictionaries (merchant override, theme
+   * locale, kit core locale — the host merges and passes ONLY the active
+   * locale, loaded per-locale so no other language ships to the client).
+   * Optional — absent means English defaults, and every kit component
+   * renders exactly as before. Existing props are untouched.
+   */
+  strings?: ThemeStringsDictionary | ThemeStringsDictionary[] | null;
   children: ReactNode;
 }): JSX.Element {
   const resolvedBasePath = basePath ?? `/${vendor.slug ?? ''}`;
+  const resolvedLocale = parseLocaleCode(locale);
+  const resolvedStrings = useMemo(
+    () =>
+      !strings
+        ? []
+        : (Array.isArray(strings) ? strings : [strings]).filter(
+            (d): d is ThemeStringsDictionary => !!d,
+          ),
+    [strings],
+  );
   const value = useMemo(
     () => ({
       vendor,
@@ -66,8 +107,10 @@ export function StorefrontProvider({
       previewData,
       basePath: resolvedBasePath,
       pagesChrome: pagesChrome ?? {},
+      locale: resolvedLocale,
+      strings: resolvedStrings,
     }),
-    [config, menus, previewData, vendor, resolvedBasePath, pagesChrome],
+    [config, menus, previewData, vendor, resolvedBasePath, pagesChrome, resolvedLocale, resolvedStrings],
   );
   const brandRootRef = useRef<HTMLDivElement>(null);
 
@@ -90,3 +133,47 @@ 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;
+}
+
+/**
+ * The client theme-string surface: the bound `t` for the active locale
+ * (`strings` prop, then the English default — never the raw key). Works in
+ * themes mounted by `ThemeMount` (which renders inside the host's provider).
+ * No `strings` prop → the English defaults, so kit components render exactly
+ * as before and third-party themes keep working untranslated.
+ */
+export function useThemeStrings(): ThemeStringsFn {
+  const context = useContext(StorefrontContext);
+
+  if (!context) {
+    throw new Error('useThemeStrings must be used within StorefrontProvider');
+  }
+
+  const { strings, locale } = context;
+  return useMemo(
+    () =>
+      (key: string, vars?: ThemeStringsVars, overrideLocale?: string | null) =>
+        translateThemeStrings(
+          [...strings, defaultThemeStrings],
+          key,
+          vars,
+          overrideLocale ?? locale ?? undefined,
+        ),
+    [strings, locale],
+  );
+}

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',