Files
SlpSoftware/docs/translations.md
T

60 lines
4.2 KiB
Markdown

# 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 namespace. The files are the source of the types.
- `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. |
(Target layout. The files were called `shared` and `landing` before; if you find those names in older notes, `common` and `site`/`home` replace them.)
## 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 Hero (component and hero data): it becomes a CMS module.
- 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 the Hero, 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`.