Queek docs

Translating your theme

Put every word your theme prints in locale files and call it through t(). Key rules, plurals, the fallback chain and the checks that enforce them.

Every word your theme prints (headings, button labels, aria-labels, placeholders, empty states) must come from t(), never from a hard-coded string. A merchant's own data (product titles, menu labels, the vendor name) stays as props. Only your theme's own chrome is translatable.

A shopper whose language has no translation file reads the English value, so a theme with English only still works everywhere. Add a language by adding one file.

This page covers the words your theme prints. A merchant's own content (products, collections, pages, posts and menus) is translated through the store's translations, with the Merchant API: see Translate store content.

Quickstart

  1. Put every string in theme/locales/en.default.json.
  2. Reference that file from manifest.ts as strings.
  3. Read strings with useThemeStrings() and call the returned t with a key.
  4. Add a language by copying the English file to theme/locales/fr.json and translating the values. Keep the keys.
  5. Run npm run check. Hard-coded copy and missing keys are reported with the file and line.

The starter ships theme/locales/en.default.json and a worked French sample at locales/fr.json at the repository root.

Locale files

theme/locales/en.default.json holds every key with its English value. Each extra language is theme/locales/{lang}.json with the same keys. English is always named en.default.json; a bare en.json is invalid.

Nested scopes ({"cartpanel": {"title": "…"}}) and flat dotted keys ({"cartpanel.title": "…"}) are the same cartpanel.title leaf. An excerpt of the starter's English file:

theme/locales/en.default.json (excerpt)
{
  "header.cart.count": {
    "one": "Cart ({count})",
    "other": "Cart ({count})"
  },
  "cartpanel.close": "Close",
  "cartpanel.total": "Total {total}",
  "categories.title": "Categories",
  "shop.title": "Shop"
}

Key rules and budgets

Before you add a key, check the kit's English defaults. If the kit already owns the string (anything under cart.*, for example), call that key instead of adding your own.

A key is either a leaf value or a parent scope, never both: header.cart beside header.cart.count is reported. Name the leaf header.cart.label.

BudgetLimitWhy
Key grammarDotted lowercase, [a-z0-9]+(\.[a-z0-9]+)*. No hyphens, capitals, spaces or empty segmentsHyphens belong to the theme slug, so <slug>.<key> stays unambiguous
Key lengthAt most 40 charactersMerchant overrides are stored as <theme-slug>.<key> in a 64-character field: 40 for the key, 23 for the slug, 1 for the dot
Theme slugAt most 23 characters, [a-z0-9-]Same 64-character field
ValueAt most 1,000 characters, plain text, not empty, no raw HTMLEscape a bracket the shopper must see as &lt;
FileAt most 3,400 keysThe per-file limit
Language file name<code>.json, a BCP 47 style code of at most 12 charactersfr.json, pt-BR.json
Plural mapone, two, few, many, other and zero are allowed; other is requiredother is the form the kit renders when no form matches

Reading strings in a component

Client components (anything with 'use client', which is every component that reads data) get the dictionaries from the provider that already wraps the storefront. Add no provider.

A client component
'use client';

import { useThemeStrings } from '@usequeek/theme-kit/provider';

export function CartClose({ onClose }: { onClose: () => void }) {
  const t = useThemeStrings();
  return (
    <button type="button" aria-label={t('cartpanel.close')} onClick={onClose}>
      ×
    </button>
  );
}

Server components cannot call the hook. Pass the bound t down from a client parent as a prop, or lift the copy up, and keep English as the default when no strings arrive so the theme still renders without them.

Interpolation

Values use {var} placeholders, filled from the second argument:

<p>{t('cartpanel.total', { total: formattedTotal })}</p>

A missing or nullish variable keeps its {placeholder} text, visible and easy to search for, and never throws. {{ and }} produce literal braces.

Plurals

Counts need plural maps, not ternaries. The kit picks the form for the shopper's language with Intl.PluralRules:

<span>{t('header.cart.count', { count: itemCount })}</span>

When no count is passed, or the language selects a form your map does not carry, the kit renders other.

Register the English file in the manifest

Reference the English file from manifest.ts, or your English is blank anywhere the host passes no dictionaries of its own, such as the local preview:

theme/manifest.ts
import type { ThemeManifest } from '@usequeek/theme-kit/types/theme';
import strings from './locales/en.default.json';

const manifest: ThemeManifest = {
  // …
  strings,
};

export default manifest;

The manifest carries English only. Other languages are loaded per shopper language by the host and are never bundled into the theme. Do not import every {lang}.json yourself: every shopper would download every language.

Fallback chain

For each key you look up, the first hit wins, in this order:

  1. A merchant's override for the shopper's language.
  2. The dictionaries the host loads for that language: your locales/{lang}.json (or your en.default.json when that file is absent) and the platform's own translations.
  3. The English file you registered in the manifest.
  4. The kit's own English defaults.

The raw key is never shown and neither is "translation missing". A key found nowhere renders an empty string, and warns once per key in development. In production that means a key your English file should have carried, so treat a missing key as a bug in the theme.

Which languages a store has

A store's languages are the locales its merchant has published. Read them with GET /store/locales: each row has locale, name, native_name, is_primary, is_default, path_prefix, hreflang, html_lang and dir. The default language is served at the store root and has an empty path_prefix. A merchant picks which published language is the default. Every other language, English included when it is not the default, lives under its lower-case code (/fr, /en, /zh-cn). An unknown or unpublished language renders English.

The shopper's language reaches your theme through the host. A theme never reads locale headers, never appends locale= itself and never builds its own URL logic for switching language. To let shoppers switch, place the kit's language switcher (next section).

Merchants can override your strings per language. Those overrides are served by GET /store/theme-strings as flat dotted keys for the active theme.

Language switcher

Place the kit's LanguageSwitcher once, in your header or footer, and set languageSwitcher: 'theme' in manifest.ts. Without that flag the storefront also shows its own floating control, so shoppers would see two. The component renders nothing on a single-language store, so place it unconditionally.

import { LanguageSwitcher } from '@usequeek/theme-kit/components/language-switcher';

<LanguageSwitcher variant="menu" />                // button + popover (a bottom sheet on phones)
<LanguageSwitcher variant="menu" side="top" />     // a footer: opens upward
<LanguageSwitcher variant="inline-list" />         // a link per language, up to four

variant="menu" is the one to use. The trigger is a real button and every language is a real link, so open-in-new-tab and copy-link work, and it is fully keyboard operable. The default select variant uses the browser's own dropdown, which a theme cannot style. Language names are written in the language itself (Français); the kit does not use flags, because a flag stands for a country, not a language.

Make the menu match your theme by setting --qn-lang-* variables on it or an ancestor (--qn-lang-surface, --qn-lang-ink, --qn-lang-radius, --qn-lang-accent, --qn-lang-popover-width, and more) or by styling its data-part attributes. For fully custom markup use the useLocales() hook, which gives you the languages, the active one, and hrefFor(locale). The full list of props, variables, parts and keyboard behaviour is in the theme kit README.

theme-check rules

npm run check runs five locale rules. They report as warnings, which are advice and do not block submission. You can raise any of them to errors, or turn them off, in .queek-theme.yml.

RuleWhat it checks
theme/locale-key-namingKeys are dotted lowercase and at most 40 characters, values are strings or plural maps of at most 1,000 characters with no HTML and no empties, the slug fits 23 characters, and each file is valid JSON
theme/locale-file-parityEvery key in a locales/{lang}.json exists in en.default.json, interpolation variables stay a subset of the English ones, and string and plural shapes match
theme/locale-key-existsEvery literal key passed to t resolves to your English file or the kit's defaults. A missing key renders empty in production
theme/locale-key-unusedKeys in your English file that no t() call references, which translators would still pay for
theme/no-hardcoded-stringsShopper-visible JSX text and copy attributes (aria-label, placeholder, title, alt and similar) that are not routed through t()

Dynamic keys such as t(`orders.${status}`) cannot be resolved statically. The check reports them as information, so confirm every value the key can take exists in your English file.

Run the check
npm run check

Rule list: Checks reference. Command flags: CLI reference.

What is not translatable yet

  • Block body text. Copy a merchant types into a block stays merchant content. Products, pages and menus are translated through the store's translations, not through theme strings: see Translate store content.
  • Theme editor labels: the labels and descriptions in theme.config.ts and block setting labels. These are merchant-admin text, not shopper text.
  • Emails and other copy that is not part of the storefront.

On this page