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>
64 lines
7.5 KiB
Markdown
64 lines
7.5 KiB
Markdown
# 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.<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)
|
|
|
|
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.
|