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>
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 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 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'), 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 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)
- 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.