The prerendered hero is plain HTML between the markers (first photo, h1, buttons), the slider takes over after hydration with the hero of the host block, the API or the build. The head preload is added to the finished HTML. Hero texts move into nl.json. The stand-in host and the e2e tests cover the hero. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
7.5 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,hero,home,about,contact,shoots,portfolio,instagram,testimonials,seo,cmsClient. The file is the source of the types. A second language isweb/src/i18n/en.jsonwith 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,localeandMessages.web/src/i18n/compare.ts: the checks the tests use (same keys and parameters, nothing empty).- The typed content modules in
web/src/contentkeep 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'), ortList(...)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 breakstsc, the same as a missing key. The content modules inweb/src/contentkeep their types, images and paths and take the words frommessages. 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 stopstscand 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 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)
- Copy
web/src/i18n/nl.jsontoweb/src/i18n/<code>.jsonand translate the values (keys and{parameters}stay). - Add it to
localesinweb/src/i18n/index.ts; the tests then compare it with Dutch. - 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.