7.7 KiB
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 |
De labels voor de gegevens van de bezoeker in de mail aan de eigenaar: Naam, E-mailadres, Onderwerp, Bericht (contact.mail.label.*) |
|
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) |
|
De antwoorden van de wachtwoord- en gebruikersbeheer-endpoints (core.identity.auth.*, core.identity.users.*) |
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.jsonenTexts/en.json, ingebed in de assembly (<EmbeddedResource Include="Texts\*.json" WithCulture="false" />).WithCulture="false"is nodig: zonder die vlag maakt de SDK van bestanden alsX.Texts.en.jsoneen satellite-assembly en vindt de host ze niet. - Genest JSON; de loader maakt er punt-sleutels van (
{"core":{"mail":{"footer":"..."}}}iscore.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) metnl.json,en.jsonof*.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(standaardnl). Een mail volgt de taal van de ontvanger (nl/en), anders de sitetaal. Een onbekende taal valt terug op de standaardtaal, daarna opnl, daarnaen. - 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:
texts.Get(CoreTexts.Mail.Footer, language, ("site", siteName));
- Services krijgen
ITextCatalog(een optionele parameter, zonder waarde gebruikt de code de gedeelde Nederlandse standaardcatalogusTextCatalog.Default). - Controllers en middleware:
HttpTexts.From(HttpContext). - Validatie (
IValidatableObject,ValidationAttribute):ValidationContext.GetService(typeof(ITextCatalog)), in de Offerings-module viaOfferingsTexts.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
- Nieuwe tekst: voeg de sleutel toe aan de sleutelklasse van de module (met de plaatshouders), en de tekst aan
nl.jsonénen.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. - Nieuwe taal: een extra bestand
Texts/<taal>.jsonper project (bijvoorbeeldde.json) met dezelfde sleutels en plaatshouders; voeg de taal toe aan deVerify-aanroepen in de tests. ZetTexts:DefaultLanguageals de site die taal als standaard moet hebben. Voor mails is de ondersteunde taalset nu nognl/en(MailLanguages); die uitbreiden is een aparte stap. - Een tekst voor één site aanpassen zonder rebuild: zet
Texts__Directorynaar een map met eennl.jsonmet 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/mailen 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 inSlpModularCms.Modules.Offerings.Tests/Golden/host-injection. - Regenereren van de mail-snapshots met opzet:
UPDATE_GOLDEN=1 dotnet test --filter MailGoldenTests.
Gedragswijzigingen bij de verhuizing
Twee bewuste wijzigingen, goedgekeurd door Bryan (via de leider): teksten die alleen in het Engels bestonden zijn nu Nederlands bij Texts:DefaultLanguage=nl; de Engelse bestandsversie bevat de oude teksten letterlijk.
- De validatiemeldingen van pakketten en banners (
offerings.validation.*, 9 teksten). Beheerders zijn Nederlandstalig en de admin toont de melding letterlijk. - De Engelse antwoorden van de endpoints voor wachtwoord vergeten/instellen en gebruikersbeheer (
core.identity.auth.invalidEmail,resetRequested,linkInvalid,passwordSet,passwordRejectedencore.identity.users.*, 13 teksten), zoals 'You cannot delete your own account.' De admin toont voor wachtwoord vergeten zijn eigen tekst (forgotPassword.sentMessage) en niet het antwoord van de server, dus er wordt niets dubbel getoond.
Verder is de uitvoer ongewijzigd; de uitzondering MasterControlledAvailabilityException heeft een technische Engelse melding gekregen, de zin voor de beheerder komt uit availability.masterControlled.
Leesbaar overzicht van de mails
mail-teksten.md toont alle mailteksten per soort in het Nederlands en Engels, plus de tekstversie van een voorbeeldmail. Het bestand wordt gegenereerd met ./scripts/Export-MailTexts.ps1 (niet met de hand wijzigen).
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.