BizzPocket

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.list is built from your own strings, not from the browser's Intl.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
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/.

ts
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:

tsx
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: pass count, and the locale's CLDR rules pick the form. other is required. A locale needs only the categories it uses (English: one and other; Arabic: all six).
  • count is special only in a plural. A plural key's count is a number in the types; in a plain message ("label": "Items: {count}") count is a placeholder like any other, string | number, and never warns.
  • count may be a number or a plain decimal string ('3'). A count that is not a finite number (NaN, Infinity, 'abc') uses other and prints as an empty string, never as NaN; 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 it ctx.t.forms('cart.items') (every plural form of the message as plain JSON) and ctx.locale. The island prints it with pluralTemplate(forms, count, locale) from @bizzpocket/theme/client, which picks the form the same way ctx.t('cart.items', { count }) does on the server (same Intl.PluralRules, falls back to other) 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 in render.

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).

tsx
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): pass now (for example a build or page time) so the server and the browser agree.
  • list(items, { type: 'disjunction' }) joins with "or". Only type is read.
  • list is 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.end and, for type: 'disjunction', kit.list.orTwo and kit.list.orEnd. English is built in. A theme in another language sets these keys in its kit section (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:

json
{
  "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.

tsx
// 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.

tsx
// 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 typegen

reads 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:

tsx
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:

tsx
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.