@usequeek/theme-kit 0.1.20 → 0.1.22

package/README.md

@@ -1,30 +1,35 @@
 # @usequeek/theme-kit
 
 The framework a Queek storefront theme is built against: hooks, stores, headless
-flows (auth, cart, checkout), types and the block renderer.
-
-**Ships TypeScript source, not a build.** Most of its modules carry a
-`'use client'` directive, and that directive is the whole contract with the React
-Server Components boundary — bundlers routinely strip or hoist it when a library
-is pre-compiled, which turns a client module into a server one silently. The
-consumer transpiles instead (`transpilePackages: ['@usequeek/theme-kit']`), so the
-directives survive to the bundler that actually enforces them.
-
-Deep subpaths resolve off the filesystem — there is deliberately NO `exports`
-map. One was tried: with source-shipped `.ts`/`.tsx` an extensionless wildcard
-target does not resolve, and spelling out extensions cannot cover both. Legacy
-resolution under `moduleResolution: bundler` handles it. The cost is that the
-package has no subpath encapsulation, so what a theme may import is enforced by
-convention plus tests: `tests/public-surface.test.ts` here (barrels declare
-only modules that exist) and `core-public-surface.test.ts` in the storefront
-repo (barrels cover every module the themes actually import).
-
-Every module that annotates a return as `JSX.Element` does
-`import type { JSX } from 'react'` — React 19 removed the global `JSX`
-namespace, and 0.1.0 shipped broken for every external consumer by relying on
-the storefront app's `next-env.d.ts` to provide it. `scripts/verify-package.ts`
-packs the current source and typechecks a real theme against it from a sandbox,
-so that class of breakage fails here instead of after publishing.
+flows (auth, cart, checkout), types and the block renderer. See the
+[theme documentation](https://docs.usequeek.com/docs/themes) for how themes
+work end to end.
+
+## Install
+
+```bash
+npm install @usequeek/theme-kit
+```
+
+Peer dependencies: `next` (>=15), `react` and `react-dom` (>=19) and
+`@queekai/client-sdk`.
+
+The package ships TypeScript source, not a build. Most modules carry a
+`'use client'` directive, and that directive is the whole contract with the
+React Server Components boundary; bundlers routinely strip or hoist it when a
+library is pre-compiled, which silently turns a client module into a server
+one. The consumer transpiles the package instead, so the directives reach the
+bundler that enforces them:
+
+```ts
+// next.config.ts
+export default { transpilePackages: ['@usequeek/theme-kit'] };
+```
+
+Compiling a theme against it needs `moduleResolution: bundler` and
+`jsx: react-jsx`. A vitest setup that renders kit components needs the package
+inlined (`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx`
+source is transformed like first-party code.
 
 ## Use
 
@@ -33,10 +38,16 @@ import { useCart } from '@usequeek/theme-kit/hooks/use-cart';
 import type { ThemeModule } from '@usequeek/theme-kit/types/theme';
 ```
 
-Deep paths, mirroring the old `@/lib/core/*`. Barrels exist (`.` and `./client`)
-to DECLARE the public surface — what a theme is allowed to build against — but
-importing through them pulls every client module into one chunk and was measured
-to break the app's build. Import the module you want.
+Import the module you need by its deep path. The barrels (`.` and `./client`)
+declare the public surface, meaning what a theme is allowed to build against,
+but importing through them pulls every client module into one chunk and can
+break an app's build.
+
+There is no `exports` map: with source-shipped `.ts`/`.tsx`, an extensionless
+wildcard target does not resolve, so subpaths resolve off the filesystem under
+`moduleResolution: bundler`. The package therefore has no subpath
+encapsulation; what a theme may import is the surface the barrels declare,
+checked by `tests/public-surface.test.ts`.
 
 Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks.css`
 (framework-owned blocks), plus per-component CSS next to its component
@@ -44,9 +55,9 @@ Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks
 
 ## 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.
+The kit's UI-string mechanism (`strings/theme-strings.ts`; pure, with no
+`next/*` and no React). A theme or provider that passes nothing renders in
+English. See also [Translating your theme](https://docs.usequeek.com/docs/themes/translations).
 
 - **Authoring contract.** `t(dictionaries, key, vars?, locale?)`: dot-path
   lookup (`cart.title`), `{var}` interpolation (`{{`/`}}` escape to literal
@@ -56,9 +67,9 @@ provider that passes nothing renders exactly as today, in English.
   `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.
+  lowercase `scope.thing.state`, max **40 chars**; values max **1000 chars**.
+  Merchant overrides are stored as `<theme-slug>.<key>` in a 64-character
+  field, 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 }`,
@@ -90,20 +101,108 @@ provider that passes nothing renders exactly as today, in English.
   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.
+  host's dynamic `import()` per locale.
+- **Typed keys (optional, compile-time).** A theme opts in per call site —
+  untyped `t(key)` callers keep compiling unchanged.
+  `ThemeStringKey<typeof strings>` derives the key union from the theme's
+  English dictionary object (nested objects flatten to dotted keys, a
+  plural map counts as ONE key, flat literal dotted keys stay one key),
+  and `createThemeT` binds it to any `t`:
+
+  ```ts
+  import enDefault from './locales/en.default.json';
+  import { createThemeT } from '@usequeek/theme-kit/strings/theme-strings';
+
+  const { t } = await createThemeStrings({ locale });
+  const tt = createThemeT<typeof enDefault>(t); // server …
+  // … or client: const tt = createThemeT<typeof enDefault>(useThemeStrings());
+  tt('cart.title'); // ok
+  // tt('cart.titl'); // type error — typo keys fail, valid keys pass
+  ```
+
+- **Pseudo-locale QA (dev/test only, never shipped).**
+  `pseudoLocalize(dictionary, options?)`
+  (`strings/pseudo-locale.ts`, pure: no `next/*`, no React) returns a
+  pseudo dictionary with identical keys and plural-map shape — every
+  value accent-mapped, ~30% longer, wrapped in `[!! … !!]` markers —
+  while `{placeholders}` and `{{`/`}}` escapes pass through and keys are
+  never touched. Use it two ways. As a dev-only locale, mount with the
+  pseudo dictionary as the `strings` prop: everything that went through
+  `t()` renders pseudo, so any text that remains plain English next to
+  pseudo text is a hard-coded (un-wrapped) string. In tests, render with
+  the pseudo dictionary and run the English-leak scan over the HTML:
+
+  ```tsx
+  import { pseudoLocalize, assertNoEnglishLeak } from '@usequeek/theme-kit/strings/pseudo-locale';
+
+  const pseudo = pseudoLocalize(enDefault, { rtl: true }); // spot-check RTL too
+  const html = renderToStaticMarkup(
+    <StorefrontProvider vendor={…} config={…} menus={[]} strings={pseudo}>
+      <MySection />
+    </StorefrontProvider>,
+  );
+  assertNoEnglishLeak(html, { allowlist: ['Queek'] }); // throws on any plain-English node
+  ```
+
+  `findEnglishLeaks(html, { allowlist, includeAttributes })` returns the
+  offending node texts instead of throwing; the scan covers visible text
+  nodes plus `aria-label`/`placeholder`/`title`/`alt` (opt out with
+  `includeAttributes: false`). Pseudo dictionaries are built on demand
+  in dev/test and never enter a client bundle.
+
+## Locale-aware dates, numbers and relative time
+
+Dates, counts, money and relative time follow the SHOPPER's locale. English
+renders in the British/Nigerian style — `2 October 2026`, never US
+`October 2, 2026`.
+
+- **One mapping.** `resolveIntlLocale(locale)` (`utils/locale.ts`, pure: no
+  `next/*`, no React) is the single canonical storefront-code → Intl-locale
+  mapping every formatter goes through. Missing/invalid codes and every
+  English variant (`en`, `en-GB`, `en-NG`, `en-US`, …) become `en-NG`;
+  everything else passes through (`fr`, `ar`, `pt-BR`, `zh-CN`, `yo`, `ha`,
+  `sw`, …). `en-NG` — not `en-GB` — because it renders NGN as `₦12,500`
+  where `en-GB` renders `NGN 12,500` (both print dates as `2 October 2026`;
+  checked on Node 22 with full ICU). `resolveSupportedLocale` falls back to
+  English when the runtime's ICU lacks a locale — formatting never throws.
+- **What themes call.** `formatThemeDate(value, locale?, options?)`
+  (`strings/theme-strings.ts`) instead of a hardcoded-`'en-GB'`
+  `toLocaleDateString`: pass the storefront locale — client components via
+  `useStorefrontLocale()`, server components via the request locale the host
+  already holds. Siblings: `formatThemeNumber`, `formatThemeMoney`, and
+  `formatThemeRelativeTime(-1, 'day', locale)` (`hier`, `أمس`, `ontem`, …,
+  `numeric: 'auto'`). `formatThemeMoney` uses the currency's default
+  decimals (`₦5,000.00`); `formatMoney` shows decimals only when present
+  (`₦5,000`, `₦0.28`). The fixed-zone display path is `formatShopperDate`
+  (`utils/format.ts`, Africa/Lagos, `''` for invalid dates);
+  `formatCount`/`formatMoney` take an optional locale, defaulting to English
+  output. `PostMeta` (`components/blog/post-meta.tsx`) renders its byline
+  through the provider locale.
+- **Fallbacks.** Unknown locale → English style; invalid date → `''`;
+  minimal-ICU runtimes render English rather than throwing.
+- **Plural selection stays separate.** `canonicalThemeLocale`
+  (`strings/theme-strings.ts`) is for `t()` plural selection ONLY: it returns
+  a bare `'en'` tag, which is a US-order Intl tag. Never pass it to a date,
+  number, money or relative-time formatter — formatters use
+  `resolveIntlLocale` (en* → `en-NG`) instead.
+
+```tsx
+import { useStorefrontLocale } from '@usequeek/theme-kit/provider';
+import { formatThemeDate } from '@usequeek/theme-kit/strings/theme-strings';
+
+const locale = useStorefrontLocale(); // null on the primary (English) locale
+formatThemeDate(post.published_at, locale, { year: 'numeric', month: 'long', day: 'numeric' });
+// en → "2 October 2026" · fr → "2 octobre 2026" · ar → "2 أكتوبر 2026"
+```
 
 ## Consumers
 
-- **The Queek storefront** (`usequeek/queek-storefront`) installs this package
-  from the npm registry (`"@usequeek/theme-kit": "^x.y.z"`) and transpiles it
-  via `transpilePackages`. Its vitest config inlines the package
-  (`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx`
-  source is transformed like first-party code.
-- **External theme developers** start from `packages/theme-starter` in the
-  storefront repo, which builds standalone against a packed tarball of this
-  source. Anyone testing a theme with vitest needs the same `inline` line;
-  anyone compiling one needs `moduleResolution: bundler` + `jsx: react-jsx`.
+- **Queek storefronts** install this package from npm
+  (`"@usequeek/theme-kit": "^x.y.z"`) and transpile it via
+  `transpilePackages`.
+- **Theme developers** start from
+  [`usequeek/theme-starter`](https://github.com/usequeek/theme-starter), which
+  builds against this package.
 
 ## Custom data: metafields & metaobjects
 
@@ -158,7 +257,7 @@ export default function ProductPage({ product }: ProductPageProps) {
 ```
 
 - MUST: place `<AppBlocks target="product" productId={...} />` on the
-  product page. `target` is product-only in phase 1 — no other slot exists.
+  product page. `target` is product-only: no other slot exists.
   `productId` scopes availability reads and deep links to the shown product;
   omit `vendorSlug` (the host resolves the store itself).
 - The host registers its placement component once through `AppBlocksProvider`
@@ -175,8 +274,7 @@ export default function ProductPage({ product }: ProductPageProps) {
 
 ## Attribution: Powered by Queek
 
-Every storefront is a billboard — every footer variant of every theme renders
-the core-owned attribution link:
+Every theme footer renders the core-owned attribution link:
 
 ```tsx
 import { PoweredByQueek } from '@usequeek/theme-kit/components/powered-by-queek';
@@ -194,7 +292,8 @@ export default function Footer() {
 - MUST: place `<PoweredByQueek />` on every footer variant (`footers/*.tsx`,
   or `footer.tsx` where a theme has no `footers/` dir). The placement and
   spacing are the theme's — the component is the content, the footer owns
-  where it sits. `theme-check` rule `theme/footer-shows-powered-by` enforces
+  where it sits. The theme check rule `theme/footer-shows-powered-by`
+  ([checks reference](https://docs.usequeek.com/docs/themes/checks)) enforces
   this, so a theme cannot ship without it.
 - Style only: the link emits `core-powered-by` with a
   `core-powered-by__brand` hook on the `Queek` wordmark; an optional
@@ -207,9 +306,8 @@ export default function Footer() {
   (`utm_source=powered_by&utm_medium=storefront&utm_campaign=<store slug>`,
   campaign omitted when the store has no slug); the component reads the slug
   from the storefront context, so themes pass nothing.
-- `hidden` (default false) takes the component's visibility from a prop as
-  the seam for a possible future plan perk. There is no merchant-facing
-  toggle for it in v1 — always render it visible.
+- `hidden` (default false) takes the component's visibility from a prop.
+  There is no merchant-facing toggle for it — always render it visible.
 
 ## Locales
 
@@ -220,7 +318,7 @@ 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
+  to the API 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.
@@ -231,11 +329,96 @@ request locale on every catalogue/content transport, server and browser:
   `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.
+What this means for themes: nothing to handle for the content itself. Never
+read the header and never append `locale` yourself — locale routing and
+`basePath` prefixing are core-owned in the storefront, and links built from
+`basePath` keep their locale prefix with zero theme changes. To let shoppers
+change language, place the kit's `LanguageSwitcher` (next section); do not
+build your own URL logic.
+
+## Language switcher
+
+A store can serve several languages. Its default language lives at the store
+root; every other language, English included when it is not the default, lives
+under its bare lower-case code (`/fr`, `/en`, `/zh-cn`). Changing language
+keeps the page, the query string and the hash.
+
+```tsx
+import { LanguageSwitcher } from '@usequeek/theme-kit/components/language-switcher';
+
+<LanguageSwitcher />                        // native <select> (default)
+<LanguageSwitcher variant="inline-list" />  // every language as a link
+```
+
+Place it unconditionally, in the header or the footer: it renders nothing on a
+single-language store, outside a storefront, and until the host passes the
+store's languages.
+
+| Prop | Default | |
+| --- | --- | --- |
+| `className` | | Extra class on the root, to position or restyle it. |
+| `variant` | `'select'` | `'select'`: one native dropdown (best keyboard, touch and screen-reader behaviour). `'inline-list'`: a link per language that wraps on narrow screens; suits a footer. |
+| `showNativeName` | `true` | Label languages in their own language (`Français`) instead of English (`French`). |
+| `showCode` | `false` | Append the code: `Français · FR`. |
+| `children` | | Render-prop `(state) => ReactNode`: replaces the default control entirely (never called on a single-language store). `state` is `useLocales()` plus `label`, `labelFor(locale)` and `displayName(locale)`. |
+
+**Tell the storefront the theme places it.** Set `languageSwitcher: 'theme'` in
+the theme manifest. Without it the storefront keeps rendering its own floating
+language control next to yours; with it the storefront renders none and the
+shopper sees exactly one.
+
+```ts
+// in the theme module
+manifest: { /* … */ languageSwitcher: 'theme' }   // ThemeManifest.languageSwitcher
+```
+
+**Fully custom markup.** `useLocales()` (from
+`@usequeek/theme-kit/hooks/use-locales`) returns:
+
+| Field | |
+| --- | --- |
+| `locales` | The store's languages, default first. One entry, or none, on a single-language store. |
+| `active` | The language the page renders in. |
+| `defaultLocale` | The language served at the store root. |
+| `hasMultiple` | `locales.length > 1`. |
+| `hrefFor(locale)` | The current page in another language (takes a row or a code), e.g. `/fr/shop?sort=new`. The first render carries no query string or hash, so server and client markup match; they are added right after mount. |
+| `switchTo(locale)` | Navigate to it, reading the live query string and hash. Use it for `onClick`/`onChange`. |
+
+Each language is `{ locale, name, native_name, is_primary, is_default,
+path_prefix, hreflang, html_lang, dir }`. Use `lang={l.html_lang}` and
+`dir={l.dir}` on a label written in that language. The pure URL rules are also
+exported (`localeHref`, `normalizeStoreLocales`, `defaultStoreLocale`,
+`resolveActiveLocale` from `@usequeek/theme-kit/utils/locale-switch`).
+
+**Strings.** `language.label` ("Language") names the control and
+`language.named` ("Language: {name}") names the select and the current
+language. Both are kit core strings with English defaults; a theme can
+override them in its manifest `strings`, and merchants and translators in
+their locale packs.
+
+**Styling.** The default control reads only these tokens, each with a neutral
+fallback, and uses logical properties, so it mirrors in right-to-left
+storefronts and sits in a header or footer unstyled:
+
+| Token | Used for | Fallback |
+| --- | --- | --- |
+| `--qn-text` | text and icon colour | inherited |
+| `--qn-border` | select border | 22% of the text colour |
+| `--qn-border-strong` | select border on hover | the text colour |
+| `--qn-surface` | select background | transparent |
+| `--qn-radius-sm` | corner radius | `6px` |
+| `--qn-focus` | focus ring | the text colour |
+
+Class names for deeper overrides: `qn-lang`, `qn-lang--select`,
+`qn-lang--inline-list`, `qn-lang__select`, `qn-lang__list`, `qn-lang__link`.
+Targets are at least 44px. The root carries `data-qn-language-switcher`.
+
+**Host side.** The host passes the store's languages to
+`StorefrontProvider` as the optional `locales` prop (the rows as it already
+holds them; extra fields are ignored, and a row without `is_default` falls
+back to `is_primary`). `basePath` must already carry the active language
+prefix, as in the Locales section. No prop, or one language: no switcher, and
+everything behaves as before.
 
 ## Links and navigation
 
@@ -244,42 +427,46 @@ import { Link, useRouter, usePathname } from '@usequeek/theme-kit/navigation';
 ```
 
 A theme links and navigates through these, never through `next/link` or
-`next/navigation`. Which framework runs the storefront is Queek's decision: the
-kit is the one place that knows it, so a change there is a kit release, not an
-update to every theme. `Link` is an `<a>` that moves inside the store without a
-full page load (`href`, `prefetch`, `replace`, plus any anchor attribute);
-`useRouter()` gives `push`, `replace`, `back` and `refresh`; `usePathname()`
-returns the current path. The theme check rejects a theme that imports `next`.
+`next/navigation`. Which framework runs the storefront is Queek's decision, so
+the kit is the one place that knows it, and a framework change is a kit
+release, not an update to every theme. `Link` is an `<a>` that moves inside the
+store without a full page load (`href`, `prefetch`, `replace`, plus any anchor
+attribute); `useRouter()` gives `push`, `replace`, `back` and `refresh`;
+`usePathname()` returns the current path. The theme check rejects a theme that
+imports `next`.
 
 ## Boundary
 
-The kit must never import the storefront app, its themes, or `lib/storefront`.
-That one-way rule is what makes this package extractable at all. The reverse
-also holds for the framework: the kit may import `next`, a theme may not.
+The kit never imports a host app or any theme. The reverse rule holds for the
+framework: the kit may import `next`, a theme may not.
 
 ## Develop
 
 ```bash
 npm install
-npm run typecheck   # tsc --noEmit, standalone — no storefront files
-npm test            # vitest run
+npm run typecheck       # tsc --noEmit
+npm test                # public-text check, then vitest run
 npm run verify-package  # pack current source, typecheck a real theme against it
 ```
 
+`verify-package` packs the current source and typechecks a real theme against
+it from a sandbox, so a break that only external consumers would see (for
+example a module relying on the global `JSX` namespace, which React 19 removed)
+fails here instead of after publishing.
+
 ## Release
 
-The package is public on npm; the repo is private. Publishing runs on tags via
-`.github/workflows/publish.yml` (needs the `NPM_TOKEN` secret):
+Publishing runs on tags via `.github/workflows/publish.yml`, which needs the
+`NPM_TOKEN` repository secret:
 
 ```bash
 # 1. Bump version in package.json and commit
-# 2. Tag and push the tag — the workflow typechecks, tests, verify-packages,
+# 2. Tag and push the tag — the workflow typechecks, tests, runs verify-package,
 #    then `npm publish --access public`:
-git tag v0.1.6
+git tag vX.Y.Z
 git push origin main --tags
 ```
 
-The storefront then bumps its dependency to match the published version
-(`yarn add @usequeek/theme-kit@^0.1.6` + lockfile) and pushes separately —
-never the other way round: the app must only ever depend on a version that
-actually exists on the registry.
+## License
+
+MIT

package/api/collections.ts

@@ -4,8 +4,8 @@ import type { Collection, Pagination } from '../types/page';
 import type { ApiResponse } from '../types/product';
 import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
 
-/** Matches `VendorCollectionProductsRequest`'s validated `sort` values exactly
- *  (queek_backend) — a value outside this list gets a 422 from the backend. */
+/** The `sort` values the collection-products endpoint accepts; any other value
+ *  gets a 422 from the API. */
 export type CollectionSort = 'newest' | 'popular' | 'price_low' | 'price_high';
 
 export interface FetchCollectionProductsOptions {
@@ -17,9 +17,9 @@ export interface FetchCollectionProductsOptions {
   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.
+// SSR collection reads go through `/client/store/*`, which resolves the store and
+// forces X-Platform=storefront (base prices, no marketplace commission) — never
+// the legacy v1 routes shared with the marketplace.
 export async function fetchCollections(vendorSlug: string, storefrontOnly = true, locale?: string): Promise<Collection[]> {
   const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
 

package/api/shop.ts

@@ -6,7 +6,7 @@ import { parseShopResponse, shopRequestParams, type ShopPrefetch, type ShopQuery
  * The shop page's first page of products, fetched while the server renders
  * `/shop`, for `ShopPrefetchProvider` to hand to `useShop` — so the product grid
  * is in the HTML instead of appearing after the browser has run the JS and
- * fetched it (kili-foods' `/shop` main content landed at 2.8 s that way).
+ * fetched it.
  *
  * Same request and the same parsing as the browser's `useShop` (both come from
  * utils/shop-query). Reads go through `/client/store/*` like every SSR read, so

package/client.ts

@@ -16,6 +16,7 @@ export * from './components/blog';
 export * from './components/image';
 export * from './components/product-metafields';
 export * from './components/powered-by-queek';
+export * from './components/language-switcher';
 export * from './components/default-metaobject-page';
 export * from './components/product-media-frame';
 export * from './components/variant-picker';
@@ -30,6 +31,7 @@ export * from './apps/subscribe-form';
 export * from './api/collections';
 export * from './api/orders';
 export * from './hooks/use-href';
+export * from './hooks/use-locales';
 export * from './hooks/use-auth';
 export * from './hooks/use-cart';
 export * from './hooks/use-shop-cart';

package/components/auth/auth-email-login-step.tsx

@@ -1,18 +1,20 @@
 'use client';
 import type { JSX } from 'react';
 import { useAuthFlow } from '../../hooks/use-auth-flow';
+import { useThemeStrings } from '../../provider';
 
 export function AuthEmailLoginStep(): JSX.Element {
   const { email, setEmail, password, setPassword, submitEmailLogin, loading, error, goToEmailRegister, goToEmailOtp } = useAuthFlow();
+  const t = useThemeStrings();
 
   return (
     <div className="core-auth__step core-auth__step--email-login">
-      <h2 className="core-auth__title">Sign in</h2>
-      <p className="core-auth__sub">Enter your email and password</p>
+      <h2 className="core-auth__title">{t('auth.login.title')}</h2>
+      <p className="core-auth__sub">{t('auth.login.subtitle')}</p>
       <input
         type="email"
         className="core-input"
-        placeholder="Email address"
+        placeholder={t('auth.login.email')}
         value={email}
         onChange={(e) => setEmail(e.target.value)}
         autoComplete="email"
@@ -21,7 +23,7 @@ export function AuthEmailLoginStep(): JSX.Element {
       <input
         type="password"
         className="core-input"
-        placeholder="Password"
+        placeholder={t('auth.login.password')}
         value={password}
         onChange={(e) => setPassword(e.target.value)}
         onKeyDown={(e) => { if (e.key === 'Enter') void submitEmailLogin(); }}
@@ -34,13 +36,13 @@ export function AuthEmailLoginStep(): JSX.Element {
         onClick={() => void submitEmailLogin()}
         disabled={loading || !email.trim() || !password}
       >
-        {loading ? 'Signing in…' : 'Sign in'}
+        {loading ? t('auth.login.signing') : t('auth.login.title')}
       </button>
       <button type="button" className="core-auth__link" onClick={goToEmailRegister}>
-        Don&apos;t have an account? Create one
+        {t('auth.login.create')}
       </button>
       <button type="button" className="core-auth__link" onClick={goToEmailOtp}>
-        Use an email code instead
+        {t('auth.login.code')}
       </button>
     </div>
   );

package/components/auth/auth-email-otp-step.tsx

@@ -2,14 +2,16 @@
 
 import type { JSX } from 'react';
 import { useAuthFlow } from '../../hooks/use-auth-flow';
+import { useThemeStrings } from '../../provider';
 
 export function AuthEmailOtpStep(): JSX.Element {
   const { email, setEmail, submitEmailRequestOtp, loading, error, initiateGoogleAuth, goToEmailLogin } = useAuthFlow();
+  const t = useThemeStrings();
 
   return (
     <div className="core-auth__step core-auth__step--email-otp">
-      <h2 className="core-auth__title">Sign in</h2>
-      <p className="core-auth__sub">Enter your email to continue</p>
+      <h2 className="core-auth__title">{t('auth.email.title')}</h2>
+      <p className="core-auth__sub">{t('auth.email.subtitle')}</p>
 
       <button
         type="button"
@@ -23,15 +25,15 @@ export function AuthEmailOtpStep(): JSX.Element {
           <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l3.66-2.84z" fill="#FBBC05"/>
           <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" fill="#EA4335"/>
         </svg>
-        Continue with Google
+        {t('auth.email.google')}
       </button>
 
-      <div className="core-auth__divider"><span>or</span></div>
+      <div className="core-auth__divider"><span>{t('auth.email.or')}</span></div>
 
       <input
         type="email"
         className="core-input"
-        placeholder="your@email.com"
+        placeholder={t('auth.email.placeholder')}
         value={email}
         onChange={(e) => setEmail(e.target.value)}
         onKeyDown={(e) => { if (e.key === 'Enter') void submitEmailRequestOtp(); }}
@@ -45,10 +47,10 @@ export function AuthEmailOtpStep(): JSX.Element {
         onClick={() => void submitEmailRequestOtp()}
         disabled={loading || !email.trim()}
       >
-        {loading ? 'Sending code…' : 'Continue'}
+        {loading ? t('auth.email.sending') : t('auth.email.continue')}
       </button>
       <button type="button" className="core-auth__link" onClick={goToEmailLogin}>
-        Have a password? Sign in with it instead
+        {t('auth.email.password')}
       </button>
     </div>
   );

package/components/auth/auth-email-otp-verify-step.tsx

@@ -3,11 +3,13 @@
 import type { JSX } from 'react';
 import { useRef } from 'react';
 import { useAuthFlow } from '../../hooks/use-auth-flow';
+import { useThemeStrings } from '../../provider';
 
 const OTP_LENGTH = 6;
 
 export function AuthEmailOtpVerifyStep(): JSX.Element {
   const { email, otp, setOtp, submitEmailVerifyOtp, submitEmailRequestOtp, goToEmailOtp, loading, error } = useAuthFlow();
+  const t = useThemeStrings();
   const refs = useRef<(HTMLInputElement | null)[]>([]);
 
   const focus = (i: number): void => {
@@ -40,9 +42,9 @@ export function AuthEmailOtpVerifyStep(): JSX.Element {
 
   return (
     <div className="core-auth__step core-auth__step--email-otp-verify">
-      <h2 className="core-auth__title">Enter code</h2>
+      <h2 className="core-auth__title">{t('auth.code.title')}</h2>
       <p className="core-auth__sub">
-        {OTP_LENGTH}-digit code sent to <strong>{email}</strong>
+        {t('auth.code.lead', { length: OTP_LENGTH })} <strong>{email}</strong>
       </p>
       <div className="core-auth-otp">
         {Array.from({ length: OTP_LENGTH }).map((_, i) => (
@@ -59,7 +61,7 @@ export function AuthEmailOtpVerifyStep(): JSX.Element {
             onFocus={(e) => e.target.select()}
             disabled={loading}
             autoComplete={i === 0 ? 'one-time-code' : 'off'}
-            aria-label={`Digit ${i + 1}`}
+            aria-label={t('auth.code.digit', { index: i + 1 })}
           />
         ))}
       </div>
@@ -70,13 +72,13 @@ export function AuthEmailOtpVerifyStep(): JSX.Element {
         onClick={() => void submitEmailVerifyOtp()}
         disabled={loading || otp.length < OTP_LENGTH}
       >
-        {loading ? 'Verifying…' : 'Verify'}
+        {loading ? t('auth.code.verifying') : t('auth.code.verify')}
       </button>
       <button type="button" className="core-auth__link" onClick={() => void submitEmailRequestOtp()}>
-        Resend code
+        {t('auth.code.resend')}
       </button>
       <button type="button" className="core-auth__link" onClick={goToEmailOtp}>
-        ← Change email
+        {t('auth.code.change')}
       </button>
     </div>
   );