Localization
Localization (often shortened to i18n) means your app speaks your users’ language: “Title is required.” in English, “Le titre est obligatoire.” in French. In Strutvane every message a user can see, from validation errors to the generated screens’ labels, comes from a message catalog: a list of keys (validation.required) and their text in one language. Nothing user-facing is hard-coded, so everything can be translated.
You’d use this page to add a second language, to change a built-in message (“Title is required.” → “Please give your post a title.”), or to write your own messages with numbers that need plurals (“1 post”, “5 posts”).
The smallest example
Section titled “The smallest example”-
Create a catalog for French:
lang/fr/posts.ts import { defineMessages } from '@strutvane/framework'export default defineMessages('fr', {'posts.published': 'Votre article « {title} » est publié.',}) -
Use the key in your code:
app/http/controllers/post.controller.ts import { t } from '@strutvane/framework'return ctx.json({ message: t('posts.published', { title: post.title }) })
What you’ll see for a browser that prefers French (Accept-Language: fr):
{ "message": "Votre article « Bonjour » est publié." }and, with an English catalog defining the same key, "Your post "Hello" is published." for everyone else.
Catalogs and keys
Section titled “Catalogs and keys”A catalog is one language and a list of key: text pairs. Keys are dotted names, grouped by topic: posts.published, validation.required, nav.posts.
import { defineMessages } from '@strutvane/framework'
export default defineMessages('en', { 'posts.published': 'Your post "{title}" is published.', 'posts.count': '{count, plural, =0 {No posts yet} one {# post} other {# posts}}', 'posts.deleted_by': '{name} deleted this post.',})defineMessages() checks its input when the app starts:
- the locale must be a valid language tag (
en,fr,pt-BR,zh-Hant), and is tidied (en-us→en-US); - every value must be a string.
RangeError: defineMessages: "english" is not a valid BCP 47 locale tagTypeError: defineMessages: message "posts.count" must be a stringA locale (or language tag) is the code for a language, optionally with a region: pt is Portuguese, pt-BR Brazilian Portuguese.
Placeholders
Section titled “Placeholders”{name} is replaced by the value you pass:
t('posts.deleted_by', { name: 'Grace' }) // → 'Grace deleted this post.'Numbers are formatted for the language: {amount} with 1250.5 shows 1,250.5 in English and 1 250,5 in French.
If you forget a value, the placeholder stays visible, so the mistake shows up on screen instead of producing half a sentence:
t('posts.deleted_by', {}) // → '{name} deleted this post.'Plurals
Section titled “Plurals”Languages count differently. English has “one” and “other”; Polish has four forms; Japanese has one. Plurals use the ICU syntax, which knows each language’s rules:
{count, plural, =0 {No posts yet} one {# post} other {# posts}}=0matches exactly zero (checked first);one,few,many,other… follow the language’s rules (from the built-inIntl.PluralRules);otheris required: it’s the fallback;#is the number, formatted for the language.
t('posts.count', { count: 0 }) // → 'No posts yet't('posts.count', { count: 1 }) // → '1 post't('posts.count', { count: 1250 }) // → '1,250 posts'A Polish catalog uses Polish forms:
import { defineMessages } from '@strutvane/framework'
export default defineMessages('pl', { 'posts.count': '{count, plural, =0 {Brak wpisów} one {# wpis} few {# wpisy} many {# wpisów} other {# wpisu}}',})Branches may contain placeholders and other plurals, up to 8 levels deep.
Broken templates never crash
Section titled “Broken templates never crash”Catalogs are often edited by translators, not developers. So the formatter never throws and never runs code: a malformed template is shown as plain text, and the problem is reported (in development) instead of breaking the page.
// a missing closing brace'{count, plural, one {# post} other {# posts}'// → shown literally, and marked malformedWhich language a request gets
Section titled “Which language a request gets”For each request, the language is chosen like this:
- the language the signed-in user picked in the app (planned UI switcher);
- otherwise the best match for the browser’s
Accept-Languageheader among the languages your app has; - otherwise the app’s default language (
en, or what you chose in installer question 21).
Matching Accept-Language (built in 0.1 as negotiateLocale):
| Header | Your app has | Chosen |
|---|---|---|
fr-CH, fr;q=0.9, en;q=0.8 |
en, fr |
fr (base language match for fr-CH) |
de, en;q=0.5 |
en, fr |
en |
pt-BR |
en, pt |
pt |
* or missing |
en, fr |
en (the default) |
fr;q=0 |
en, fr |
en (q=0 means “not French”) |
The header is attacker-controlled, so it’s cut to 4 KB and 50 entries, and anything malformed falls back to the default.
Fallbacks: what if a translation is missing?
Section titled “Fallbacks: what if a translation is missing?”Each lookup tries a chain of languages, most specific first. For pt-BR with English as the default:
pt-BR → pt → enSo a Brazilian user sees the pt-BR text if it exists, else the general Portuguese text, else English. A key missing everywhere shows the key itself:
t('posts.archvied') // → 'posts.archvied' (a typo: visible on screen, never empty)Changing built-in and package messages
Section titled “Changing built-in and package messages”Strutvane ships English messages for validation and errors (validation.required: {attribute} is required.), and packages ship their own. You override them without editing anyone’s files, by defining the same key in your app. The override chain, most specific first:
- field: an override for one field of one resource;
- resource: for one resource;
- app: your
lang/catalogs; - package: catalogs shipped by installed packages;
- built-in: the framework’s English messages.
import { defineMessages } from '@strutvane/framework'
export default defineMessages('en', { 'validation.required': 'Please fill in {attribute}.',})What you’ll see: every “required” error in the app now reads “Please fill in Title.” Within each language, each layer is checked for that language and then for its language-neutral * dictionary, so a field-specific override written for every language beats your general app text.
The built-in keys follow two patterns:
| Keys | Used for |
|---|---|
validation.<issue code> (validation.too_short, validation.unique…) |
validation messages; {attribute} is the field’s label |
errors.<CODE>.title, errors.<CODE>.detail |
the title and safe detail of error responses |
Finding missing translations
Section titled “Finding missing translations”node strut lang:checkWhat you’ll see (something like this):
fr: 3 keys missing posts.count posts.deleted_by validation.uniquepl: completeA key counts as present if the language or its base language has it (en-GB is covered by en). Run it in CI to catch untranslated text before release.
The API underneath: createMessages()
Section titled “The API underneath: createMessages()”The 0.1 core API, which t() will wrap. Useful in tests and scripts:
import { createMessages, defineMessages } from '@strutvane/framework'
const messages = createMessages({ fallbackLocale: 'en', app: [ defineMessages('en', { 'posts.count': '{count, plural, =0 {No posts yet} one {# post} other {# posts}}' }), defineMessages('fr', { 'posts.count': '{count, plural, =0 {Aucun article} one {# article} other {# articles}}' }), ],})
console.log(messages.format('posts.count', { count: 3 }, { locale: 'fr' }))console.log(messages.has('posts.count', { locale: 'de' }))console.log(messages.missingKeys('fr'))What you’ll see:
3 articlestrue[ ... every built-in key that has no French text yet ... ](has() is true for German because the chain falls back to English.)
| Method | What it does |
|---|---|
format(key, params?, { locale?, overrides? }) |
the finished text; a missing key returns the key |
resolve(key, lookup?) |
the raw template, or undefined |
has(key, lookup?) |
whether any layer defines it, along the chain |
locales() |
every language that has a catalog |
missingKeys(locale) |
keys in the default language that locale lacks |
Dates, numbers and money
Section titled “Dates, numbers and money”Placeholders format plain numbers for the language. For dates and money, format with the browser-standard Intl objects, which every Node and browser has:
new Intl.NumberFormat('fr', { style: 'currency', currency: 'EUR' }).format(1250.5) // → '1 250,50 €'new Intl.DateTimeFormat('en-GB', { dateStyle: 'long' }).format(new Date('2026-11-15')) // → '15 November 2026'The installer’s question 21 sets the app’s default language, time zone and currency. The generated screens format dates, numbers and money in the user’s language for you.
The generated screens
Section titled “The generated screens”The admin UI’s labels (menu entries, column headers, buttons, empty states) come from catalogs too. Installer question 30 picks the UI languages (English by default; add any). Translating your own data (a post’s title in three languages) is different: that’s the job of the planned @strutvane/translations package.
With Docker or without Docker
Section titled “With Docker or without Docker”Localization behaves the same in both. One thing to check in a slim container image: Node must include full ICU data for every language you use. Official Node builds (including the node:24-bookworm-slim image the generated Dockerfile uses) ship full ICU, so Intl and plurals work for every language. Custom Node builds with “small ICU” format everything as English.
Common mistakes
Section titled “Common mistakes”The page shows posts.published instead of a sentence
Section titled “The page shows posts.published instead of a sentence”Why: no catalog defines that key in any language of the chain: a typo, or the catalog file isn’t loaded.
Fix: check the spelling, and that the file is in lang/<locale>/ and exports defineMessages(...) as its default.
The French catalog is ignored
Section titled “The French catalog is ignored”Why: the request didn’t ask for French (check the Accept-Language header your browser sends), or the catalog’s locale is written wrong ('FR' is fine, 'french' stops the app at start-up).
Fix: test with an explicit header:
curl -H "Accept-Language: fr" http://localhost:3000/api/postsMy plural shows the whole {count, plural, …} text
Section titled “My plural shows the whole {count, plural, …} text”Why: the template is malformed (a missing }, no other branch, or a misspelled selector like ones), so it’s shown literally.
Fix: every plural needs an other branch and balanced braces:
{count, plural, one {# post} other {# posts}}{name} appears in the sentence
Section titled “{name} appears in the sentence”Why: the code didn’t pass name.
Fix: pass every placeholder the template uses: t('posts.deleted_by', { name: user.name }).
Numbers show as 1,250 for French users
Section titled “Numbers show as 1,250 for French users”Why: the message was formatted without the request’s language (for example in a queued job that ran later). Fix: store the user’s language with the job, and pass it when formatting.
Next steps
Section titled “Next steps”- Validation: where
validation.*messages appear. - Error Handling: error titles and details from
errors.*keys. - Configuration: the app’s default language and time zone.
- Mail: sending mail in the recipient’s language.