Files
AndreaSlopFotografie/docs/translations.md
T

3.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: the Dutch texts, one file per area (common, site, home, about, contact, shoots, portfolio, instagram, testimonials, seo). The files are the source of the types.
  • 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 file name, 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.

Adding a language (later)

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