Files
SlpSoftware/docs/translations.md

4.5 KiB

Texts and translations

The static texts of the site live in language files, not in the components. Dutch is the only language now; the structure allows a second one without touching the components.

Where things are

  • src/i18n/nl.json: the Dutch texts, ONE file per language with a block per area (below). The file is the source of the types. A second language is a second file (en.json) with exactly the same keys.
  • src/i18n/index.ts: t(key, params?), tList(key) and the TextKey type.
  • src/i18n/i18n.test.ts: tests for the helpers and the language files.

Namespaces

Namespace Holds
common Texts used all over the site: navigation, footer, buttons, aria labels, error and alert texts.
site Site-wide texts: page title, meta description, structured data.
home The texts of the landing page sections (about, packages intro, contact form, and so on).
era The texts of the 2026 era variant of the landing page.

(The blocks were called shared and landing earlier, and were separate files; common and site/home replace them, all in one nl.json.)

Keys and placeholders

A key is a dotted path: the namespace, then the section, then the element, for example home.contact.submit or common.aria.backToTop. A list of plain texts is an array in the JSON and keeps the order of the page. A text may contain {name} placeholders, filled in from the second argument: t('home.contact.thanks', { name }). A placeholder that is not given stays as it is in the text. There is no HTML in the texts; a text with a link or emphasis is split into parts in the component.

Reading a text

  • t('home.about.title') returns one text, with placeholders replaced.
  • tList('home.about.points') returns an array of texts.
  • TextKey is the union of all keys that exist, so a typo or a removed key stops tsc -b (and therefore pnpm build). Do not build keys at run time with template strings.

What is deliberately not in the language files

  • The title, lead and buttons of the Hero: they come from the CMS (data block #cms-data, see docs/hero-integration.md). The baked fallback texts of the Hero and its fixed lines (small line, code line, brand prefix of the heading) are in the language file, block home.hero.
  • Everything that comes from the CMS: packages, banners, and so on.
  • src/cms-client: it is a movable package and has its own messages (messages.nl.ts); it may not import from the app.
  • The privacy statement: it is its own feature and has its own text.

ESLint knows these exceptions: react/jsx-no-literals and a rule for text attributes (aria-label, aria-description, alt, title, placeholder, label) warn about a text typed straight into JSX in src/**/*.tsx, except in tests and the privacy statement. Single technical signs (/, |, -, :, and so on), whitespace and numbers are allowed. They are warnings for now; they become errors when the move is done.

Adding a second language

  1. Copy src/i18n/nl to src/i18n/<code> and translate the values. Keys and {placeholders} stay the same.
  2. Type it against the Dutch files (for example satisfies typeof nl) so a missing key is a compile error, and add a test that both languages have the same keys and placeholders.
  3. Make t() and tList() read from the active language (a locale in src/i18n/index.ts) instead of nl directly.
  4. The site needs a way to choose the language, <html lang> from the language, and a prerender per language. That is separate work; the texts do not stand in its way.

Checking that nothing changed

When texts are moved into the language files, the prerendered page has to stay word for word the same.

pnpm build            # tsc -b, vite build and the prerender
pnpm baseline:save    # before the change: stores .baseline/index.html (not in git)
# ... make the change, then build again
pnpm baseline:check   # compares dist/index.html with the baseline; exit code 1 and a diff if it differs

The baseline keeps the text, links, labels, meta tags, structured data (JSON-LD) and a CMS data block if there is one. Formatting, scripts, styles, class names and asset hashes are ignored. The code is in scripts/htmlBaseline.mjs, with tests in scripts/htmlBaseline.test.mjs.