Translations
Put one JSON file per locale in src/views/locales/, and print messages with the t pipe.
src/views/locales/
en.json
sw.json{
"cart": {
"title": "Your cart",
"items": { "zero": "Your cart is empty", "one": "{count} item", "other": "{count} items" },
"greeting": "Hello {name}"
}
}<h1>{{ 'cart.title' | t }}</h1>
<p>{{ 'cart.items' | t:'count':cart.items.length }}</p>
<p>{{ 'cart.greeting' | t:'name':user.name }}</p>
<button title="{{ 'cart.title' | t }}">…</button>- Keys are the JSON's nested names joined with dots:
cart.title. - Parameters follow
tas name/value pairs, as withkvQuery:t:'count':n:'name':user.name. A message names them in braces:{count}. Numbers are formatted for the locale (1,024). - Plurals: a message can be an object of plural forms (
zero,one,two,few,many,other;otheris required). Thecountparameter picks the form, by the language's plural rules.zerois used for0when it's there. - Escaping: messages and their parameters are escaped, like any
{{ }}. Messages can't contain HTML.
Which locale
A render uses the locale it's given: ctx.render(name, data, { locale: user.locale }), else createViews({ locale }), else en-US. A message is looked up in that locale (sw-KE), then its language (sw), then the default locale (messagesLocale, else locale) and its language. A key no catalogue has prints as the key itself, with a warning in dev.
Checked by the build
kick check:views, the Vite build and kick dev check every t call whose key is written in the template:
- a key no catalogue has is an error:
unknown message 'cart.nope'; - a key some catalogues lack is a warning naming the locales;
- a
{placeholder}the call doesn't pass is an error:message 'cart.items' needs 'count'; - parameters that aren't name/value pairs are an error.
A key computed at render time ({{ item.labelKey | t }}) isn't checked. The editor doesn't show these checks yet.
Outside templates
views.t gives controllers, emails and flash messages the same messages:
const subject = await views.t('mail.welcome.subject', { name: user.name }, { locale: user.locale })Where catalogues come from
kick devand file mode: read from<viewsDir>/locales/*.json. In dev (kick dev, orcreateViews({ dev: true })) edits show on the next render; otherwise they're read once, like the templates.- A Vite build: bundled into
virtual:kick-viewsasmessages, socreateViews({ ...kickViews })needs no file system (the edge works too). Upgrade@forinda/kickjs-vitewith@forinda/kickjs-view: an older plugin doesn't knowtand the new pipes. - Your own:
createViews({ messages: { en: { 'cart.title': 'Cart' } } }).
Using another i18n library
Export your own t from pipes.ts and it replaces the built-in one. The build then leaves your t calls unchecked:
// src/views/pipes.ts
import i18next from 'i18next'
import { withEnv } from '@forinda/kickjs-view'
export const t = withEnv(({ locale }) => (key: string, ...pairs: unknown[]) => {
const params: Record<string, unknown> = {}
for (let i = 0; i + 1 < pairs.length; i += 2) params[String(pairs[i])] = pairs[i + 1]
return i18next.t(key, { lng: locale, ...params })
})