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
- Put every string in
theme/locales/en.default.json. - Reference that file from
manifest.tsasstrings. - Read strings with
useThemeStrings()and call the returnedtwith a key. - Add a language by copying the English file to
theme/locales/fr.jsonand translating the values. Keep the keys. - 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:
{
"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.
| Budget | Limit | Why |
|---|---|---|
| Key grammar | Dotted lowercase, [a-z0-9]+(\.[a-z0-9]+)*. No hyphens, capitals, spaces or empty segments | Hyphens belong to the theme slug, so <slug>.<key> stays unambiguous |
| Key length | At most 40 characters | Merchant 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 slug | At most 23 characters, [a-z0-9-] | Same 64-character field |
| Value | At most 1,000 characters, plain text, not empty, no raw HTML | Escape a bracket the shopper must see as < |
| File | At most 3,400 keys | The per-file limit |
| Language file name | <code>.json, a BCP 47 style code of at most 12 characters | fr.json, pt-BR.json |
| Plural map | one, two, few, many, other and zero are allowed; other is required | other 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.
'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:
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:
- A merchant's override for the shopper's language.
- The dictionaries the host loads for that language: your
locales/{lang}.json(or youren.default.jsonwhen that file is absent) and the platform's own translations. - The English file you registered in the manifest.
- 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 fourvariant="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.
| Rule | What it checks |
|---|---|
theme/locale-key-naming | Keys 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-parity | Every 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-exists | Every 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-unused | Keys in your English file that no t() call references, which translators would still pay for |
theme/no-hardcoded-strings | Shopper-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.
npm run checkRule 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.tsand block setting labels. These are merchant-admin text, not shopper text. - Emails and other copy that is not part of the storefront.