Files
AndreaSlopFotografie/docs/translations.md
T
SluijsensandClaude Sonnet 5.5 246ebe5fd6 Translation files, step 0: typed text helper, checks and the baseline of the pages
Adds src/i18n (t, tList, tPlural over typed Dutch JSON, key and parameter
checks), the first text (back to top) as proof, a baseline tool for the
prerendered pages (pnpm baseline:save and baseline:check), a lint warning for
text typed straight into JSX, and docs/translations.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-15 17:34:18 +01:00

2.9 KiB

Texts and translations

The 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 a redesign.

Where things are

  • web/src/i18n/nl/*.json: the Dutch texts, one file per area (common, site, home, about, contact, shoots, portfolio, instagram, testimonials, seo). The files are the source of the types.
  • web/src/i18n/index.ts: t(key, params?) for a text, tList(key) for a list of texts, tPlural(key, count, params?) for a text with a singular and a plural form, locales, locale and Messages.
  • web/src/i18n/compare.ts: the checks the tests use (same keys and parameters, nothing empty).
  • The typed content modules in web/src/content keep their structure, images and paths; the words come from the language files.

Not in the language files: the hero (becomes a CMS module), the privacy statement (separate feature), and everything that comes from the CMS (packages, banners, later the gallery).

Keys

Dotted paths: the file name, then the page or section, then the element: home.pricing.title, shoots.newborn.faq.0.question, common.aria.backToTop, common.form.errors.required, seo.pages.contact.title. A list is an array in the JSON and keeps the order of the page; a position is a number in the path. Parameters are written {name}; a text with a plural has the forms one and other (photos.one, photos.other) and {count} is filled in by tPlural. No HTML in the texts: a text with a link or emphasis is a structured list of parts, as the content modules already have.

How a missing text is found

  • t('...') only accepts keys that exist in the Dutch files; a typo or a missing key stops tsc and the build.
  • A second language is typed as Messages, so a missing key is a compile error there too.
  • A test checks that every language has the same keys and {parameters} as Dutch, and that no text is empty or says TODO.
  • ESLint (react/jsx-no-literals) warns about a text typed straight into JSX, so a new hardcoded text is noticed in review and in CI.

Adding a language (later)

  1. Copy web/src/i18n/nl to web/src/i18n/<code> and translate the values (keys and {parameters} stay).
  2. Add it to locales in web/src/i18n/index.ts; the tests then compare it with Dutch.
  3. The site needs routes per language (/en/...) and a prerender per language, and <html lang> from the language. That is a separate piece of work; the texts do not stand in its way.

Moving the texts over: the check that nothing changed

While the texts were moved into the language files, the prerendered pages had to stay word for word the same. pnpm baseline:save (after pnpm build) saves the text, links, labels, meta tags and structured data of every page in web/.baseline (not in git), and pnpm baseline:check compares a new build with it; styling, scripts and file hashes are ignored. A step is only done when the check says the pages are equal.