Files
AndreaSlopFotografie/docs/translations.md
T
SluijsensandClaude Sonnet 5.5 e7bae5edd7 Translation files: the form messages of the cms-client package come from nl.json
Block cmsClient.contact holds the field errors, fallback, waiting time (one
and other), too-large, captcha-required, failure and sending label.
src/i18n/cmsClientMessages.ts builds the ContactMessages object for
useContactForm; a test checks that it says the same as the package's own
Dutch defaults, which stay as the fallback.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 00:30:01 +01:00

7.6 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: all Dutch texts of the site in one file, in blocks per area in the order of the site: common, site, home, about, contact, shoots, portfolio, instagram, testimonials, seo, cmsClient. The file is the source of the types. A second language is web/src/i18n/en.json with the same keys.
  • 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 block (common, home, ...), 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.

Two ways to read a text

  • A single text in a component: t('home.pricing.title'), or tList(...) for a list of plain texts, tPlural(...) for singular and plural.
  • Structured content (a list of items with several texts, such as the questions and answers of a page): the content module reads the typed tree directly, messages.shoots.newborn.faq.map((item) => ({ question: item.question, answer: item.answer })). A missing property breaks tsc, the same as a missing key. The content modules in web/src/content keep their types, images and paths and take the words from messages.
  • t() is not given keys that are built at run time (`faq.${i}.question`): use the tree for lists.

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.

What is in which block

File Texts
common.json shared labels: aria, site.name, newTab, actions (general button words), form (labels, placeholders, captcha message), status (404 and error page), lightbox, gate, privacyNote, pricing labels
site.json nav, footer, breadcrumb, info (service area, reply time, mail subjects), socials
home.json the home page sections and the booking labels (booking.book, booking.readMore)
about.json, contact.json the about page and the contact page
shoots.json the overview, every shoot type and every shoot page (pages.<id>), shared shoot texts
portfolio.json, instagram.json, testimonials.json those pages and sections, with their photo alt texts and reviews
seo.json page titles, descriptions and link-preview alt texts per page (seo.pages.<page>)

The block cmsClient holds the texts of the shared src/cms-client package, per part of the package: cmsClient.contact has the form's field errors, fallback, waiting time (rateLimited.one/other with {minutes}), too-large, captcha-required, failure ({address}) and the sending label. src/i18n/cmsClientMessages.ts builds the ContactMessages object from it and ContactForm passes it to useContactForm({ messages }). The package keeps its own Dutch defaults (messages.nl.ts) as a fallback and a test checks that both say the same. Parts that come later (offerings) get their own part of the block.

Not here: the hero, the privacy statement and everything from the CMS.

Importing the language files

Components import from @/i18n. Files that Node loads while building (everything reached from src/seo.ts, src/sitePages.ts, the content modules, src/lib, src/navigation.ts) cannot use the @/ alias or a directory import, so they use ../i18n/index.ts (relative, with the extension). The JSON file is imported with with { type: 'json' } for the same reason.

Rules that are enforced

react/jsx-no-literals and a rule for text attributes (aria-label, alt, title, placeholder, label) are errors in components and routes (the hero, tests and the privacy page are left out; an empty alt="" for a decorative image is fine). A new text goes into nl.json first.

Adding a language (later)

  1. Copy web/src/i18n/nl.json to web/src/i18n/<code>.json 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.