Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Localization

View as Markdownllms.txt

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

  1. 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é.',
    })
  2. 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.

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.

lang/en/posts.ts
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 tag
TypeError: defineMessages: message "posts.count" must be a string

A locale (or language tag) is the code for a language, optionally with a region: pt is Portuguese, pt-BR Brazilian Portuguese.

{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.'

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}}
  • =0 matches exactly zero (checked first);
  • one, few, many, other… follow the language’s rules (from the built-in Intl.PluralRules);
  • other is 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:

lang/pl/posts.ts
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.

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 malformed

For each request, the language is chosen like this:

  1. the language the signed-in user picked in the app (planned UI switcher);
  2. otherwise the best match for the browser’s Accept-Language header among the languages your app has;
  3. 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 → en

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

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:

  1. field: an override for one field of one resource;
  2. resource: for one resource;
  3. app: your lang/ catalogs;
  4. package: catalogs shipped by installed packages;
  5. built-in: the framework’s English messages.
lang/en/validation.ts
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
Terminal window
node strut lang:check

What you’ll see (something like this):

fr: 3 keys missing
posts.count
posts.deleted_by
validation.unique
pl: complete

A 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 0.1 core API, which t() will wrap. Useful in tests and scripts:

scripts/messages-demo.ts
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 articles
true
[ ... 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

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

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.

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.

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:

Terminal window
curl -H "Accept-Language: fr" http://localhost:3000/api/posts

My 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}}

Why: the code didn’t pass name. Fix: pass every placeholder the template uses: t('posts.deleted_by', { name: user.name }).

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.

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