Translations and locales: ctx.t, ctx.format and the kit
On this page
A theme can print its words in more than one language, and the kit components (the pager, the gallery, the
filter rail, the product card) can use the same words. This page covers the locale files, t(), the
formatters, right-to-left layouts, how to translate the kit's built-in text once, and what the platform does
not do yet.
What is supported today
- One locale per store page. The page is rendered in the theme's
defaultLocale. When stores get a language setting, a store whose language the theme has will be rendered in it. Nothing else decides the locale. - The locale never comes from the visitor. Not from a cookie, not from
Accept-Language, not from the URL. A page is cached and shared between visitors, so a page that changed with the visitor would show one shopper's language to another. Do not build a language switcher on top of the browser's language. - The server and the browser print the same text: every formatter has its options pinned (Latin digits, the
Gregorian calendar, UTC for dates), and
format.listis built from your own strings, not from the browser'sIntl.ListFormat.
Not supported: a per-visitor language, a language in the URL (/fr/...), translated product or category
names (those come from the store), and a language switcher.
Locale files
Put one JSON file per locale in locales/, named by the BCP 47 tag:
locales/en.json
locales/ar.json{
"cart": {
"title": "Your cart",
"items": { "one": "{count} item", "other": "{count} items" }
},
"greeting": "Hello, {name}"
}Set the default in theme.config.ts. locales is optional: it defaults to the files in locales/.
import { theme } from '@bizzpocket/theme';
export default theme({
id: 'my-theme',
name: 'My Theme',
tokens: { /* ... */ },
i18n: { defaultLocale: 'en', locales: ['en', 'ar'] },
});A key may be nested (cart.title) or written as one dotted key ("cart.title": "..."). bizzpocket check
reports a missing key, an extra key, a placeholder that differs from the default file, an unknown key used in
code, and hard-coded text in JSX (i18n/* rules). Add locales to files in package.json when you
publish (publishing.md).
t() and plurals
Every block's render gets ctx.t:
import { block, f } from '@bizzpocket/theme';
export default block({
fields: { count: f.number({ default: 2 }) },
render: (p, ctx) => (
<section dir={ctx.dir}>
<h2>{ctx.t('cart.title')}</h2>
<p>{ctx.t('cart.items', { count: p.count })}</p>
<p>{ctx.t('greeting', { name: ctx.store.name })}</p>
</section>
),
});{name}placeholders are replaced in one pass. Replaced text is never scanned again and no code runs, so a store name that contains{count}stays as written.- A key whose value is an object with the plural categories (
zero,one,two,few,many,other) is a plural: passcount, and the locale's CLDR rules pick the form.otheris required. A locale needs only the categories it uses (English:oneandother; Arabic: all six). countis special only in a plural. A plural key'scountis anumberin the types; in a plain message ("label": "Items: {count}")countis a placeholder like any other,string | number, and never warns.countmay be a number or a plain decimal string ('3'). A count that is not a finite number (NaN,Infinity,'abc') usesotherand prints as an empty string, never asNaN; development builds warn once.- A missing key falls back to the default locale's file, then to the SDK's English kit text, then prints
the key itself (and warns in development).
ctx.t.has('key')tells you whether a key exists. - Keep whole sentences as keys. Do not join pieces of a sentence in code: word order differs by language.
- A plural in an island: the island has no
ctx, so the server block hands itctx.t.forms('cart.items')(every plural form of the message as plain JSON) andctx.locale. The island prints it withpluralTemplate(forms, count, locale)from@bizzpocket/theme/client, which picks the form the same wayctx.t('cart.items', { count })does on the server (sameIntl.PluralRules, falls back toother) and fills{count}. A third argument{ term }fills more placeholders.pluralForm(forms, count, locale)returns the chosen form with its{placeholders}still in it. No hook: call them inrender.
format: numbers, money, dates, lists
ctx.format has five formatters. All of them use the locale the engine actually supports: if the page's
locale tag is valid but the engine does not know it, the theme's default locale is used, then en, for
every formatter alike (ctx.format.locale is the tag in use).
ctx.format.number(1234.5); // '1,234.5'
ctx.format.money({ amount: 1499, currency: 'INR' }); // grouped the way the currency's home market does
ctx.format.date('2026-11-13'); // 'Nov 13, 2026' (UTC, Gregorian)
ctx.format.relative('2026-11-12T12:00:00Z', '2026-11-13T12:00:00Z'); // 'yesterday'
ctx.format.list(['red', 'green', 'blue']); // 'red, green, and blue'relative(date, now): passnow(for example a build or page time) so the server and the browser agree.list(items, { type: 'disjunction' })joins with "or". Onlytypeis read.listis built from the theme's messages, so it is the same on every JavaScript engine:kit.list.two({a} and {b}),kit.list.start,kit.list.middle,kit.list.endand, fortype: 'disjunction',kit.list.orTwoandkit.list.orEnd. English is built in. A theme in another language sets these keys in itskitsection (below); without them the list is joined in English.- Digits are Latin by default in every locale. Set
i18n: { nativeDigits: true }to use the locale's own.
Right to left and logical CSS
ctx.dir is 'rtl' for Arabic, Hebrew, Persian, Urdu and the other right-to-left locales and 'ltr'
otherwise; put it on your root element (dir={ctx.dir}). Write CSS with logical properties so one
stylesheet serves both directions:
| Physical | Logical |
|---|---|
margin-left, padding-right |
margin-inline-start, padding-inline-end |
text-align: left |
text-align: start |
left: 0 |
inset-inline-start: 0 |
border-left |
border-inline-start |
float: left |
float: inline-start |
bizzpocket check reports physical properties in a theme that ships a right-to-left locale
(i18n/physical-css). Arrows and chevrons that point the way the page flows must be mirrored; the kit's
default pager glyphs already flip.
Translate the kit once
The kit components print their own text (Previous page, Show image 2 of 5, Add to cart). Set it once
in the kit section of each locale file; every component picks it up and an explicit labels prop still
wins, field by field:
{
"kit": {
"pager": { "nav": "Seitennavigation", "prev": "Vorherige Seite", "next": "Nächste Seite", "page": "Seite {n}" },
"list": { "two": "{a} und {b}", "start": "{a}, {b}", "middle": "{a}, {b}", "end": "{a} und {b}" }
}
}In a theme you need no code: the host wraps the page so the kit sees the page's translator. Keys you leave out print the SDK's English. Components with no translator at all (an island rendered outside a page) print exactly the English defaults.
Every kit key
These are the keys in KIT_EN, with their English text. {n}, {total}, {min}, {max}, {title},
{remaining} and {subtotal} are placeholders; a plural key shows one row per form.
| Key | English |
|---|---|
kit.list.two |
{a} and {b} |
kit.list.start |
{a}, {b} |
kit.list.middle |
{a}, {b} |
kit.list.end |
{a}, and {b} |
kit.list.orTwo |
{a} or {b} |
kit.list.orEnd |
{a}, or {b} |
kit.pager.nav |
Pagination |
kit.pager.prev |
Previous page |
kit.pager.next |
Next page |
kit.pager.page |
Page {n} |
kit.breadcrumbs.nav |
Breadcrumb |
kit.cart.empty |
Your cart is empty. |
kit.cart.updated (one) |
Cart updated. {n} item, subtotal {subtotal}. |
kit.cart.updated (other) |
Cart updated. {n} items, subtotal {subtotal}. |
kit.cart.freeShippingRemaining |
Add {remaining} more for free shipping. |
kit.cart.freeShippingReached |
Your order ships free. |
kit.gallery.show |
Show image {n} of {total} |
kit.gallery.zoom |
Zoom image |
kit.gallery.close |
Close |
kit.gallery.prev |
Previous image |
kit.gallery.next |
Next image |
kit.productCard.was |
Was |
kit.productCard.off |
{n}% off |
kit.productCard.sale |
-{n}% |
kit.productCard.soldOut |
Sold out |
kit.productCard.addToCart |
Add to cart |
kit.productCard.wishlist |
Add {title} to wishlist |
kit.filterRail.rail |
Filters |
kit.filterRail.clear |
Clear all |
kit.filterRail.more |
+ {n} more |
kit.filterRail.price |
Price |
kit.filterRail.availability |
Availability |
kit.filterRail.under |
Under {max} |
kit.filterRail.over |
Over {min} |
kit.filterRail.range |
{min} – {max} |
Translated text inside islands
A client island cannot call ctx.t (it has no translator). The server block hands it the message, and the island
finishes it. There are three tools; pick by what the message is.
1. A plain message with placeholders: ctx.t.raw and fillTemplate.
// server block
<SearchBox labels={{ empty: ctx.t.raw('search.empty') }} /> // "No results for {term}"
// island ('use client')
import { fillTemplate } from '@bizzpocket/theme/client';
fillTemplate(labels.empty, { term }); // "No results for shoes"ctx.t.raw(key, count?) is the message as written in the locale file, in the page's language (a plural key gives the
form for count, the other form without one). fillTemplate(template, vars) fills {name} exactly the way ctx.t
does: one pass, only variables you pass, a value that contains {x} is not filled again.
2. A plural message: ctx.t.forms and pluralTemplate. The count is only known in the browser, and a language can have
up to six forms (Arabic: zero, one, two, few, many, other; Russian and Polish: four). Do not pick the form yourself.
// server block
<SearchBox locale={ctx.locale} labels={{ results: ctx.t.forms('search.results') }} />
// island ('use client')
import { pluralTemplate } from '@bizzpocket/theme/client';
pluralTemplate(labels.results, n, locale); // "3 results available" / "3 नतीजे"ctx.t.forms(key) returns every plural form of the message in the page's language as a plain object
({ zero?, one?, two?, few?, many?, other }; a plain message gives { other }; a key that is missing in the page's
language falls back like ctx.t; with typegen it accepts only keys that exist). pluralTemplate(forms, count, locale, vars?) picks the form with Intl.PluralRules,
uses other when the language has no such form, and fills the text; count is a placeholder, and vars adds more
({term}). It is not a hook: call it while rendering. The server (ctx.t(key, { count })) and the browser print the
same text for the same count, so there is no hydration mismatch. usePredictiveSearch({ locale, messages: { results: forms } })
and useCartView(cart, { locale, messages: { updated: forms } }) take the forms object directly.
Keep the placeholder names natural (count, term): you do not rename them for the island.
Typed keys with bizzpocket typegen
bizzpocket typegenreads your default locale file and the kit keys and writes types/bizzpocket.d.ts. With that file in your
tsconfig.json, ctx.t('cart.titel'), a missing placeholder or a plural without count is a compile error.
See the CLI page.
Every placeholder is typed string | number, except count of a plural key, which is a number (it picks the form).
head() has the translator too
A block's head(props, ctx) gets ctx.t, ctx.format, ctx.locale and ctx.dir (the same as render), so a
title or description can be translated:
head: (p, ctx) => ({ title: p.listing?.collection?.title ?? ctx.t('listing.title') }),For hosts: giving the kit its translator
This is for the storefront and the Bun renderer, not for theme code. The kit finds the locale in this order:
the nearest I18nProvider above it, else the source the host registered, else nothing (English). The
provider alone is not enough on a server: a built theme carries its own copy of the SDK, and React Server
Components have no context at all. So the host also registers a request-scoped source, the same way it
registers the site origin:
import { registerRenderI18nSource, type KitI18n } from '@bizzpocket/theme/kit';
// Bun renderer: backed by AsyncLocalStorage. Next: backed by React cache().
declare const current: () => KitI18n | null | undefined;
const unregister = registerRenderI18nSource(() => current());A source must read request-scoped state, never a module variable. A source that throws counts as absent.