# 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`, `hero`, `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 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.`), 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.`) | 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 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/.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 `` 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.