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
+1
View File
@@ -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 |
+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.
@@ -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, @"(?<=<p[^>]*>)\s+", "");
return System.Text.RegularExpressions.Regex.Replace(collapsed, @"\s+(?=</p>)", "").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());
}
}
@@ -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("<!doctype html><title>Nog geen website geplaatst</title>" +
"<p>Er staat hier nog geen website. Beheer via <a href=\"/admin/\">/admin/</a>.</p>");
await context.Response.WriteAsync("<!doctype html><title>" + texts.Get(CoreTexts.Host.Placeholder.Title) + "</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)
@@ -1,10 +1,10 @@
<!doctype html>
<html lang="nl">
<html lang="{{lang}}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="noindex, nofollow">
<title>Nog geen website geplaatst</title>
<title>{{title}}</title>
<style>
:root { color-scheme: light dark; }
body {
@@ -40,18 +40,10 @@
</head>
<body>
<main>
<h1>Er staat hier nog geen website</h1>
<p>
Het CMS draait, maar er is nog geen publieke website geplaatst. De website
wordt apart aangeleverd en hoort in de map <code>wwwroot/web/</code> te staan,
met een <code>index.html</code> in de hoofdmap daarvan.
</p>
<p>
Beheerders kunnen inloggen via <a href="/admin/">/admin/</a>.
</p>
<p class="muted">
Deze pagina wordt automatisch vervangen zodra de website is geplaatst.
</p>
<h1>{{heading}}</h1>
<p>{{intro}}</p>
<p>{{admin}}</p>
<p class="muted">{{note}}</p>
</main>
</body>
</html>
+20
View File
@@ -6,6 +6,26 @@ namespace SlpModularCms.Core.Texts;
/// </summary>
public static class CoreTexts
{
/// <summary>
/// Texts of pages the host writes itself. They may contain simple inline markup (<c>&lt;code&gt;</c>, <c>&lt;a&gt;</c>):
/// these files are authored by us, never filled with visitor input. Key path <c>core.host.*</c>.
/// </summary>
public static class Host
{
/// <summary>The page shown while no website is deployed.</summary>
public static class Placeholder
{
public static readonly TextKey Title = new("core.host.placeholder.title");
public static readonly TextKey Heading = new("core.host.placeholder.heading");
public static readonly TextKey Intro = new("core.host.placeholder.intro");
public static readonly TextKey Admin = new("core.host.placeholder.admin");
public static readonly TextKey Note = new("core.host.placeholder.note");
/// <summary>The short page used if the embedded template is missing.</summary>
public static readonly TextKey Fallback = new("core.host.placeholder.fallback");
}
}
/// <summary>Messages of sign-in, invitations and first-time setup (shown to the administrator). Key path <c>core.identity.*</c>.</summary>
public static class Identity
{
+10
View File
@@ -77,6 +77,16 @@
"createOwnerFailed": "Could not create the owner: {errors}",
"completed": "System initialised successfully. The first owner has been created."
}
},
"host": {
"placeholder": {
"title": "No website deployed yet",
"heading": "There is no website here yet",
"intro": "The CMS is running, but no public website has been deployed yet. The website is delivered separately and belongs in the folder <code>wwwroot/web/</code>, with an <code>index.html</code> in its root.",
"admin": "Administrators can sign in at <a href=\"/admin/\">/admin/</a>.",
"note": "This page is replaced automatically as soon as the website is deployed.",
"fallback": "<p>There is no website here yet. Manage the site at <a href=\"/admin/\">/admin/</a>.</p>"
}
}
}
}
+10
View File
@@ -77,6 +77,16 @@
"createOwnerFailed": "Fout bij aanmaken eigenaar: {errors}",
"completed": "Systeem succesvol geïnitialiseerd. De eerste eigenaar is aangemaakt."
}
},
"host": {
"placeholder": {
"title": "Nog geen website geplaatst",
"heading": "Er staat hier nog geen website",
"intro": "Het CMS draait, maar er is nog geen publieke website geplaatst. De website wordt apart aangeleverd en hoort in de map <code>wwwroot/web/</code> te staan, met een <code>index.html</code> in de hoofdmap daarvan.",
"admin": "Beheerders kunnen inloggen via <a href=\"/admin/\">/admin/</a>.",
"note": "Deze pagina wordt automatisch vervangen zodra de website is geplaatst.",
"fallback": "<p>Er staat hier nog geen website. Beheer via <a href=\"/admin/\">/admin/</a>.</p>"
}
}
}
}
@@ -31,6 +31,13 @@ public static class OfferingsTexts
}
}
/// <summary>Texts the host writes into the website's pages (the plain list of packages).</summary>
public static class Injection
{
/// <summary>The booking link of a package; <c>{name}</c> is the package name, already HTML-encoded by the caller.</summary>
public static readonly TextKey Book = new("offerings.injection.book", "name");
}
/// <summary>The catalogue of the request being validated, or the shared default one outside a request (unit tests).</summary>
public static ITextCatalog From(ValidationContext? context)
=> context?.GetService(typeof(ITextCatalog)) as ITextCatalog ?? TextCatalog.Default;
@@ -1,6 +1,7 @@
using System.Globalization;
using System.Text;
using System.Text.RegularExpressions;
using SlpModularCms.Core.Texts;
using SlpModularCms.Modules.Offerings.Data.Entities;
using SlpModularCms.Modules.Offerings.Models;
@@ -75,8 +76,9 @@ public static partial class CmsPageHtml
/// <c>[a-z0-9-]+</c> (the first of a duplicate wins), it has a title, at least one feature (none blank) and a price
/// that reads as whole euros above zero; the order is <c>displayOrder</c>.
/// </summary>
public static string OfferingsList(IReadOnlyList<OfferingDto> offerings)
public static string OfferingsList(IReadOnlyList<OfferingDto> offerings, ITextCatalog? texts = null)
{
texts ??= TextCatalog.Default;
var kept = Keep(offerings);
if (kept.Count == 0)
{
@@ -99,7 +101,7 @@ public static partial class CmsPageHtml
}
html.Append("</ul>")
.Append("<a href=\"/?pakket=").Append(id).Append("#contact\">Boek ").Append(name).Append("</a>")
.Append("<a href=\"/?pakket=").Append(id).Append("#contact\">").Append(texts.Get(OfferingsTexts.Injection.Book, args: ("name", name))).Append("</a>")
.Append("</li>");
}
@@ -1,6 +1,7 @@
using System.Text.Json;
using System.Text.Json.Nodes;
using SlpModularCms.Core.Hosting.Website;
using SlpModularCms.Core.Texts;
using SlpModularCms.Modules.Offerings.Data.Entities;
using SlpModularCms.Modules.Offerings.Models;
@@ -12,7 +13,7 @@ namespace SlpModularCms.Modules.Offerings.Services;
/// page's JSON-LD and inline prices. It only touches what a page marks; a page without markers is not handed to it.
/// Any exception means "leave the page as it was built" (the injector logs it and serves the baked page).
/// </summary>
public sealed class OfferingsHtmlTransform(IOfferingsService offerings, IOfferingBannersService banners) : IHtmlPageTransform
public sealed class OfferingsHtmlTransform(IOfferingsService offerings, IOfferingBannersService banners, ITextCatalog? texts = null) : IHtmlPageTransform
{
public const string OfferingsRegion = "CMS:OFFERINGS-HTML";
public const string BannerTopRegion = "CMS:BANNER-TOP-HTML";
@@ -48,7 +49,7 @@ public sealed class OfferingsHtmlTransform(IOfferingsService offerings, IOfferin
if (wantsOfferings)
{
html = HtmlMarkerEditor.ReplaceRegion(html, OfferingsRegion, CmsPageHtml.OfferingsList(live));
html = HtmlMarkerEditor.ReplaceRegion(html, OfferingsRegion, CmsPageHtml.OfferingsList(live, texts));
html = HtmlMarkerEditor.EditJsonLd(html, JsonLdMarker, (slug, json) => EditOfferJsonLd(json, FindPrice(live, slug)));
html = HtmlMarkerEditor.ReplaceInlineValues(html, PriceAttribute,
slug => FindPrice(live, slug) is { } euros ? CmsPageHtml.PriceHtml(euros) : null);
@@ -16,6 +16,9 @@
"schedule": {
"endAfterStart": "EndsAt must be after StartsAt."
}
},
"injection": {
"book": "Book {name}"
}
}
}
@@ -16,6 +16,9 @@
"schedule": {
"endAfterStart": "Het einde moet na het begin liggen."
}
},
"injection": {
"book": "Boek {name}"
}
}
}