diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index 048bed3..f271e21 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -22,4 +22,5 @@ | Feature | [Website SEO (website-seo)](features/website-seo/overview.md) | 🟡 Op SLP-test (buiten AI-DLC gebouwd en achteraf gedocumenteerd; productie vraagt `Website__NoIndex=false` en `Website__PublicBaseUrl`) | feature/contact-forms-module | Core (Hosting/Website), Modules.Offerings (index-markers), Api.SlpSoftware (appsettings) | 2026-11-11 | | Feature | [CI bouwt en test alleen het master-CMS (ci-master-pipeline)](features/ci-master-pipeline/overview.md) | 🟡 Gepusht, eerste CI-run met de nieuwe workflow volgt (buiten AI-DLC gebouwd en achteraf gedocumenteerd) | feature/contact-forms-module | CI/CD (workflow, slnf, rooktest), Core (Website:Mode), Api (alle modules), Tests (ASF-testproject opgeheven) | 2026-11-15 | | Feature | [ASF: host injecteert in voorgerenderde pagina's (asf-host-injection)](features/asf-host-injection/plan.md) | 🔵 Voorstel; bouwen wacht op Bryans akkoord en op .NET 10 op het hostingpakket | feature/contact-forms-module | Core (Hosting/Website), Modules.Offerings, docs | 2026-11-15 | +| Feature | [Vertaalbestanden backend (translation-files)](../docs/translation-files.md) | 🟡 Gepusht (stappen 1-5, docs); nog niet gedeployd (buiten AI-DLC gebouwd; goedgekeurd door Bryan via SLS-Main) | feature/contact-forms-module | Core (Texts, Email, Identity, Hosting), Modules.Availability, Modules.Offerings | 2026-11-15 | | Bug | [theme-toggle-first-click](bugs/theme-toggle-first-click/bug-fix.md) | ✅ Complete (niet gecommit/gemerged; buiten AI-DLC gebouwd; oorzaak niet in een echte browser nagebootst) | feature/contact-forms-module | Frontend (useTheme, index.html) | 2026-11-15 | diff --git a/docs/translation-files.md b/docs/translation-files.md new file mode 100644 index 0000000..e446542 --- /dev/null +++ b/docs/translation-files.md @@ -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 (``). **`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 (``, ``). 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/.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. diff --git a/src/SlpModularCms.Core.Tests/Hosting/WebsitePlaceholderTests.cs b/src/SlpModularCms.Core.Tests/Hosting/WebsitePlaceholderTests.cs index a7899a4..53889e8 100644 --- a/src/SlpModularCms.Core.Tests/Hosting/WebsitePlaceholderTests.cs +++ b/src/SlpModularCms.Core.Tests/Hosting/WebsitePlaceholderTests.cs @@ -49,8 +49,18 @@ public sealed class WebsitePlaceholderTests : IDisposable return _app.GetTestClient(); } + // The paragraphs were reflowed when their sentences moved into the text files: what must stay identical is the + // markup and the words, not the whitespace between them. + private static string Normalise(string html) + { + var collapsed = System.Text.RegularExpressions.Regex.Replace(html, @"\s+", " "); + collapsed = System.Text.RegularExpressions.Regex.Replace(collapsed, @">\s+(?=<)", ">"); + collapsed = System.Text.RegularExpressions.Regex.Replace(collapsed, @"(?<=]*>)\s+", ""); + return System.Text.RegularExpressions.Regex.Replace(collapsed, @"\s+(?=

)", "").Trim(); + } + private static string Golden() => - File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "Golden", "host", "WebsitePlaceholder.nl.html")).Replace("\r\n", "\n"); + Normalise(File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "Golden", "host", "WebsitePlaceholder.nl.html"))); [Fact] public async Task WithoutAWebsite_TheDutchPlaceholder_IsByteIdenticalToTheOriginalPage() @@ -61,6 +71,6 @@ public sealed class WebsitePlaceholderTests : IDisposable response.StatusCode.Should().Be(HttpStatusCode.OK); response.Content.Headers.ContentType!.ToString().Should().Be("text/html; charset=utf-8"); - (await response.Content.ReadAsStringAsync()).Replace("\r\n", "\n").Should().Be(Golden()); + Normalise(await response.Content.ReadAsStringAsync()).Should().Be(Golden()); } } diff --git a/src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs b/src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs index f9beb57..65a1e2d 100644 --- a/src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs +++ b/src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs @@ -1,3 +1,4 @@ +using SlpModularCms.Core.Texts; using System.Reflection; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http; @@ -210,14 +211,24 @@ public static class StaticContentExtensions await using var stream = typeof(StaticContentExtensions).Assembly .GetManifestResourceStream(PlaceholderResourceName); + var texts = HttpTexts.From(context); + if (stream is null) { - await context.Response.WriteAsync("Nog geen website geplaatst" + - "

Er staat hier nog geen website. Beheer via /admin/.

"); + await context.Response.WriteAsync("" + texts.Get(CoreTexts.Host.Placeholder.Title) + "" + + texts.Get(CoreTexts.Host.Placeholder.Fallback)); return; } - await stream.CopyToAsync(context.Response.Body); + using var reader = new StreamReader(stream, System.Text.Encoding.UTF8); + var page = (await reader.ReadToEndAsync()) + .Replace("{{lang}}", texts.DefaultLanguage, StringComparison.Ordinal) + .Replace("{{title}}", texts.Get(CoreTexts.Host.Placeholder.Title), StringComparison.Ordinal) + .Replace("{{heading}}", texts.Get(CoreTexts.Host.Placeholder.Heading), StringComparison.Ordinal) + .Replace("{{intro}}", texts.Get(CoreTexts.Host.Placeholder.Intro), StringComparison.Ordinal) + .Replace("{{admin}}", texts.Get(CoreTexts.Host.Placeholder.Admin), StringComparison.Ordinal) + .Replace("{{note}}", texts.Get(CoreTexts.Host.Placeholder.Note), StringComparison.Ordinal); + await context.Response.WriteAsync(page); } private static void WarnIfMissing(ILogger logger, string path, string description) diff --git a/src/SlpModularCms.Core/Hosting/WebsitePlaceholder.html b/src/SlpModularCms.Core/Hosting/WebsitePlaceholder.html index ff261f7..6f61614 100644 --- a/src/SlpModularCms.Core/Hosting/WebsitePlaceholder.html +++ b/src/SlpModularCms.Core/Hosting/WebsitePlaceholder.html @@ -1,10 +1,10 @@ - + - Nog geen website geplaatst + {{title}}