diff --git a/AGENTS.md b/AGENTS.md index 0592a6c..103b2bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,4 +5,4 @@ This file is the entry point for AI coding agents working in this repository. Pr ## Index - [.ai/layout-conventions.md](.ai/layout-conventions.md) — how to build and update the Mermaid diagrams in [LAYOUT.md](LAYOUT.md). -- [README.md](README.md) and [docs/](docs/) — set-up and commands, [CMS integration](docs/cms-integration.md), [deploy and CI](docs/deploy-and-ci.md) and the [go-live checklist](docs/go-live-checklist.md). Update them in the same change when you alter the packages or banners, the use of the CMS API, the workflow (inputs, jobs, triggers), the server config or the go-live conditions. Work that is not built through AI-DLC is documented there, not only in a commit message. +- [README.md](README.md) and [docs/](docs/) — set-up and commands, [CMS integration](docs/cms-integration.md), [deploy and CI](docs/deploy-and-ci.md) and the [go-live checklist](docs/go-live-checklist.md), [translations](docs/translations.md) and the [assets and licences](docs/assets-and-licenses.md). New texts of the site go in `web/src/i18n/nl/*.json`, not in the components. Update them in the same change when you alter the packages or banners, the use of the CMS API, the workflow (inputs, jobs, triggers), the server config or the go-live conditions. Work that is not built through AI-DLC is documented there, not only in a commit message. diff --git a/README.md b/README.md index 789e786..265e4ee 100644 --- a/README.md +++ b/README.md @@ -31,5 +31,6 @@ Lay-out of the website and its pages can be found in a separate document [LAYOUT - [docs/cms-integration.md](docs/cms-integration.md): packages and banners from the CMS, the API, the build step, live refresh and the reverse proxy. - [docs/deploy-and-ci.md](docs/deploy-and-ci.md): the pipeline, the workflow inputs, deploying to test, the nightly build and the TEST ONLY commit. - [docs/assets-and-licenses.md](docs/assets-and-licenses.md): where the images, icons and fonts come from and what is still to confirm about their licence. +- [docs/translations.md](docs/translations.md): where the texts of the site live (language files), how keys work and how a language is added. - [docs/go-live-checklist.md](docs/go-live-checklist.md): what must be true before the CMS features and the contact form go to production. - [aidlc-docs/](aidlc-docs/): the AI-DLC records per feature (requirements, design, decisions, audit). [aidlc-docs/active-features.md](aidlc-docs/active-features.md) lists them. diff --git a/docs/translations.md b/docs/translations.md new file mode 100644 index 0000000..44c81a3 --- /dev/null +++ b/docs/translations.md @@ -0,0 +1,33 @@ +# 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. + +## 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/` 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. diff --git a/web/.gitignore b/web/.gitignore index 485a724..6c2388a 100644 --- a/web/.gitignore +++ b/web/.gitignore @@ -33,3 +33,6 @@ lighthouse-reports # Written by config/fetchOfferings.ts before every build src/content/offerings.generated.json + +# Saved text of the prerendered pages (pnpm baseline:save), a local safety net +.baseline diff --git a/web/config/htmlBaseline.test.ts b/web/config/htmlBaseline.test.ts new file mode 100644 index 0000000..2db732c --- /dev/null +++ b/web/config/htmlBaseline.test.ts @@ -0,0 +1,73 @@ +import { describe, expect, it } from 'vitest'; +import { firstDifferences, normalizeHtml } from './htmlBaseline.ts'; + +describe('normalizeHtml', () => { + it('keeps text, links, labels, meta and structured data', () => { + const html = + 'Titel' + + '' + + 'Over mij' + + ''; + const out = normalizeHtml(html); + for (const part of [ + 'Titel', + 'content="Tekst"', + 'rel="canonical"', + 'aria-label="Naar over mij"', + 'Over mij', + '{"a":1}', + ]) { + expect(out).toContain(part); + } + }); + + it('leaves out look and build details', () => { + const html = + '' + + '' + + '
tekst
' + + ''; + const out = normalizeHtml(html); + expect(out).not.toMatch( + /css-1abc|color:red|data-reveal|opmerking|\.a\{|stylesheet|AbCd1234.js/, + ); + expect(out).toContain('
'); + expect(out).toContain('/assets/foto.jpg'); + expect(out).toContain( + '', + ); + }); + + it('keeps the CMS markers and the data block', () => { + const html = + '' + + 'a'; + const out = normalizeHtml(html); + expect(out).toContain(''); + expect(out).toContain('{"x":1}'); + expect(out).toContain(''); + }); + + it('notices a changed word', () => { + expect(normalizeHtml('

een

')).not.toBe( + normalizeHtml('

twee

'), + ); + }); + + it('puts one tag per line and ends with a newline', () => { + expect(normalizeHtml('')).toBe( + '\n', + ); + }); +}); + +describe('firstDifferences', () => { + it('shows the lines that differ, at most a few', () => { + const out = firstDifferences('a\nb\nc', 'a\nB\nc\nd'); + expect(out.join('\n')).toContain('regel 2'); + expect(out.join('\n')).toContain('basislijn: b'); + expect(out.join('\n')).toContain('nu: B'); + expect(out.join('\n')).toContain('(geen)'); + expect(firstDifferences('a', 'a')).toEqual([]); + }); +}); diff --git a/web/config/htmlBaseline.ts b/web/config/htmlBaseline.ts new file mode 100644 index 0000000..35b16c8 --- /dev/null +++ b/web/config/htmlBaseline.ts @@ -0,0 +1,130 @@ +// Safety net for moving texts into the language files: saves what the +// prerendered pages say (their text, links, labels, meta tags and structured +// data) and later checks that a new build says exactly the same. Styling, +// scripts, asset hashes and generated class names are left out, so only a +// change of wording or content shows up. +// +// Usage (after `pnpm build`): +// node config/htmlBaseline.ts save writes .baseline/.html (ignored by git) +// node config/htmlBaseline.ts check compares dist/client with .baseline +import { + existsSync, + mkdirSync, + readdirSync, + readFileSync, + writeFileSync, +} from 'node:fs'; +import { join, relative } from 'node:path'; + +const DIST = 'dist/client'; +const BASELINE = '.baseline'; + +// What stays: text, links, labels, meta, structured data and the data block +const KEEP_SCRIPT = /type="application\/(?:ld\+json|json)"/; + +export function normalizeHtml(html: string): string { + return ( + html + .replace(//g, '') + .replace(//g, '') + .replace( + /]*)>([\s\S]*?)<\/script>/g, + (all, attrs: string) => (KEEP_SCRIPT.test(attrs) ? all : ''), + ) + .replace(/