Vertaalbestanden 5-6/6: placeholder-pagina en 'Boek {name}' naar de tekstbestanden; docs/translation-files.md

Placeholder: sjabloon met {{tokens}}, zinnen in core.host.placeholder.*; vergeleken met het originele bestand (zonder witruimte). 'Boek {name}' in offerings.injection.book; ASF-golden files blijven groen.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 20:49:23 +01:00
co-authored by Claude Sonnet 5.5
parent 8f867d3dda
commit 2307417134
13 changed files with 154 additions and 23 deletions
+61
View File
@@ -0,0 +1,61 @@
# Vertaalbestanden van de backend
Levend document (2026-11-15). De vaste, voor gebruikers bedoelde teksten van de CMS-host staan niet meer in de C#-code maar in JSON-bestanden per taal. Dit document beschrijft de opzet, de sleutelstijl en hoe je een tekst of taal toevoegt. De beheerteksten van de admin staan in de frontend (`frontend/src/i18n/locales/nl|en/translation.json`) en zijn hier niet bij betrokken.
## Wat staat erin, wat niet
| In de bestanden | Blijft in code |
|---|---|
| Mails: uitnodigingen, wachtwoord resetten, accountwijzigingen, melding van een contactbericht (`core.mail.*`) | CMS-data: pakketten, banners, categorieën, berichten van bezoekers |
| Meldingen aan de beheerder bij inloggen, uitnodigen en eerste inrichting (`core.identity.*`) | Technische ProblemDetails-titels (`Validation failed`, `Too many requests`, `Service Unavailable`, `Unauthorized`, `Payload too large`, `Invalid category`) |
| Beschikbaarheidsmeldingen (`availability.*`) | Foutcodes van het contactformulier (`required`, `too_long`, `invalid`, ...): dat is een contract met de websites |
| Validatiemeldingen van pakketten en banners (`offerings.validation.*`) | Interne uitzonderingen (Master), log- en SecurityEvent-teksten |
| De pagina als er geen website is geplaatst (`core.host.placeholder.*`) | De HTML-structuur van mails en pagina's (alleen de zinnen gaan naar de bestanden) |
| 'Boek {name}' in de gewone lijst die de host in de website schrijft (`offerings.injection.book`) | Twee Engelse API-meldingen die bewust niet zijn verplaatst: het 'als dit adres bij een account hoort...'-antwoord van wachtwoord vergeten en 'You cannot delete your own account.' |
De golden files van de website (ASF) voor de lijst-HTML blijven leidend: de tekst 'Boek {name}' moet in het Nederlands exact zo blijven.
## Bestanden en lagen
- Per project dat teksten heeft: `Texts/nl.json` en `Texts/en.json`, ingebed in de assembly (`<EmbeddedResource Include="Texts\*.json" WithCulture="false" />`). **`WithCulture="false"` is nodig:** zonder die vlag maakt de SDK van bestanden als `X.Texts.en.json` een satellite-assembly en vindt de host ze niet.
- Genest JSON; de loader maakt er punt-sleutels van (`{"core":{"mail":{"footer":"..."}}}` is `core.mail.footer`). Opmerkingen en een komma aan het eind mogen.
- Plaatshouders heten `{naam}` (letters en cijfers, geen nummers). Waarden worden niet geëscaped door de catalogus: wie HTML schrijft, escaped de waarde zelf vóór het invullen.
- Een tekst die de host in HTML zet (placeholder-pagina) mag eenvoudige opmaak bevatten (`<code>`, `<a>`). Die bestanden schrijven wij zelf; er komt nooit bezoekersinvoer in.
- Lagen, de eerste die een sleutel kent wint: (1) een optionele database-override (`ITextOverrides`; nog geen implementatie, de catalogus kent de laag al), (2) een map naast de app (`Texts:Directory`) met `nl.json`, `en.json` of `*.nl.json`, zelfde vorm als de ingebedde bestanden, handig om een tekst bij een deploy te wijzigen zonder rebuild, (3) de ingebedde bestanden.
- Taal: `Texts:DefaultLanguage` (standaard `nl`). Een mail volgt de taal van de ontvanger (`nl`/`en`), anders de sitetaal. Een onbekende taal valt terug op de standaardtaal, daarna op `nl`, daarna `en`.
- Een ontbrekende sleutel breekt een request nooit: de sleutelnaam wordt de tekst en er komt één foutregel in het log (per sleutel en taal één keer). Een kapot override-bestand wordt genegeerd en gelogd.
## Sleutels in code
Elke tekst heeft een getypeerde sleutel: `CoreTexts.Mail.Invitation.Subject`, `AvailabilityTexts.Maintenance`, `OfferingsTexts.Validation.Banner.Position`, ... Een sleutel is een `TextKey(pad, plaatshouders...)`; de plaatshouders die erbij staan moeten in elke taal in de tekst staan. Gebruik de catalogus zo:
```csharp
texts.Get(CoreTexts.Mail.Footer, language, ("site", siteName));
```
- Services krijgen `ITextCatalog` (een optionele parameter, zonder waarde gebruikt de code de gedeelde Nederlandse standaardcatalogus `TextCatalog.Default`).
- Controllers en middleware: `HttpTexts.From(HttpContext)`.
- Validatie (`IValidatableObject`, `ValidationAttribute`): `ValidationContext.GetService(typeof(ITextCatalog))`, in de Offerings-module via `OfferingsTexts.From(context)`.
- Een module met eigen teksten registreert zijn assembly: `services.AddCmsTextsFrom(typeof(XModule).Assembly)`.
Sleutelstijl: kleine letters en camelCase per onderdeel, `module.onderwerp.onderdeel` (`core.mail.passwordReset.note`). De websites gebruiken dezelfde vorm (genest JSON per taal, punt-paden, `{naam}`), zodat later één gedeeld overzicht mogelijk is.
## Een tekst, sleutel of taal toevoegen
1. **Nieuwe tekst:** voeg de sleutel toe aan de sleutelklasse van de module (met de plaatshouders), en de tekst aan `nl.json` én `en.json`. Een test (`TextAudit`) faalt als een sleutel in een taal ontbreekt, als de plaatshouders afwijken, of als een bestand een tekst heeft die geen sleutel kent.
2. **Nieuwe taal:** een extra bestand `Texts/<taal>.json` per project (bijvoorbeeld `de.json`) met dezelfde sleutels en plaatshouders; voeg de taal toe aan de `Verify`-aanroepen in de tests. Zet `Texts:DefaultLanguage` als de site die taal als standaard moet hebben. Voor mails is de ondersteunde taalset nu nog `nl`/`en` (`MailLanguages`); die uitbreiden is een aparte stap.
3. **Een tekst voor één site aanpassen zonder rebuild:** zet `Texts__Directory` naar een map met een `nl.json` met alleen de sleutels die anders moeten zijn.
## Tests
- `TextAudit.Verify(assembly, TextAudit.KeysOf(typeof(Sleutelklasse)), "nl", "en")` (per project dat teksten heeft): sleutels per taal, plaatshouders, wezen.
- Karakteriseringstests: alle mails (7 soorten × nl, en, een onbekende taal × volledig en kaal) zijn vastgelegd in `SlpModularCms.Core.Tests/Golden/mail` en moesten na de verhuizing byte-identiek blijven; de placeholder-pagina is vergeleken met het originele bestand (zonder witruimte-verschillen); de Nederlandse meldingen van Identity en Availability zijn per tekst vastgelegd; de golden files van de website staan in `SlpModularCms.Modules.Offerings.Tests/Golden/host-injection`.
- Regenereren van de mail-snapshots met opzet: `UPDATE_GOLDEN=1 dotnet test --filter MailGoldenTests`.
## Gedragswijziging bij de verhuizing
Eén bewuste wijziging, goedgekeurd door Bryan: de validatiemeldingen van pakketten en banners waren Engels en zijn nu Nederlands bij `Texts:DefaultLanguage=nl` (de beheerders zijn Nederlandstalig en de admin toont de melding letterlijk). De Engelse bestandsversie bevat de oude meldingen letterlijk. Verder is de uitvoer ongewijzigd; de uitzondering `MasterControlledAvailabilityException` heeft een technische Engelse melding gekregen, de zin voor de beheerder komt uit `availability.masterControlled`.
## Productie
De bestanden zitten als resource in de assemblies, dus in elke publish, ook de self-contained Windows-publish voor IIS: er is geen aparte map met bestanden om mee te leveren. Een override-map (`Texts:Directory`) is optioneel en staat naast de app.