diff --git a/src/SlpModularCms.Core.Tests/SlpModularCms.Core.Tests.csproj b/src/SlpModularCms.Core.Tests/SlpModularCms.Core.Tests.csproj
index 54104f5..34daa9d 100644
--- a/src/SlpModularCms.Core.Tests/SlpModularCms.Core.Tests.csproj
+++ b/src/SlpModularCms.Core.Tests/SlpModularCms.Core.Tests.csproj
@@ -29,6 +29,10 @@
+
+
+
+
diff --git a/src/SlpModularCms.Core.Tests/TextFixtures/Sample.Texts.en.json b/src/SlpModularCms.Core.Tests/TextFixtures/Sample.Texts.en.json
new file mode 100644
index 0000000..b52e894
--- /dev/null
+++ b/src/SlpModularCms.Core.Tests/TextFixtures/Sample.Texts.en.json
@@ -0,0 +1,7 @@
+{
+ "sample": {
+ "hello": "Hello {name}",
+ "nested": { "deep": "Deep" },
+ "plain": "Plain text"
+ }
+}
diff --git a/src/SlpModularCms.Core.Tests/TextFixtures/Sample.Texts.nl.json b/src/SlpModularCms.Core.Tests/TextFixtures/Sample.Texts.nl.json
new file mode 100644
index 0000000..407895a
--- /dev/null
+++ b/src/SlpModularCms.Core.Tests/TextFixtures/Sample.Texts.nl.json
@@ -0,0 +1,8 @@
+{
+ "sample": {
+ "hello": "Hallo {name}",
+ "onlynl": "Alleen nl",
+ "nested": { "deep": "Diep" },
+ "plain": "Gewone tekst"
+ }
+}
diff --git a/src/SlpModularCms.Core.Tests/Texts/TextAuditTests.cs b/src/SlpModularCms.Core.Tests/Texts/TextAuditTests.cs
new file mode 100644
index 0000000..c314bc5
--- /dev/null
+++ b/src/SlpModularCms.Core.Tests/Texts/TextAuditTests.cs
@@ -0,0 +1,68 @@
+using FluentAssertions;
+using SlpModularCms.Core.Texts;
+using Xunit;
+
+namespace SlpModularCms.Core.Tests.Texts;
+
+public class TextAuditTests
+{
+ private static readonly System.Reflection.Assembly Fixtures = typeof(TextAuditTests).Assembly;
+
+ public static class AllSampleKeys
+ {
+ public static readonly TextKey Hello = new("sample.hello", "name");
+ public static readonly TextKey Plain = new("sample.plain");
+ public static readonly TextKey Deep = new("sample.nested.deep");
+ public static readonly TextKey OnlyNl = new("sample.onlynl");
+ }
+
+ public static class WrongKeys
+ {
+ public static readonly TextKey HelloWithoutPlaceholder = new("sample.hello");
+ public static readonly TextKey Plain = new("sample.plain");
+ public static readonly TextKey Misspelled = new("sample.plian");
+ }
+
+ [Fact]
+ public void KeysOf_FindsEveryDeclaredKey_FieldsAndNestedTypes()
+ => TextAudit.KeysOf(typeof(AllSampleKeys)).Select(k => k.Path).Should().BeEquivalentTo(
+ ["sample.hello", "sample.plain", "sample.nested.deep", "sample.onlynl"]);
+
+ [Fact]
+ public void AFileSetThatMatchesTheKeys_HasNoProblems_ForTheLanguagesThatHaveAFile()
+ {
+ var keys = TextAudit.KeysOf(typeof(AllSampleKeys)).Where(k => k.Path != "sample.onlynl").ToList();
+
+ TextAudit.Verify(Fixtures, keys, "nl", "en").Should().Contain(p => p.Contains("sample.onlynl") && p.StartsWith("[nl]"),
+ "the nl file has a text that no key declares");
+ }
+
+ [Fact]
+ public void AKeyMissingInALanguage_IsReported()
+ {
+ var problems = TextAudit.Verify(Fixtures, TextAudit.KeysOf(typeof(AllSampleKeys)), "nl", "en");
+
+ problems.Should().Contain("[en] missing text for key 'sample.onlynl'");
+ problems.Should().NotContain(p => p.StartsWith("[nl]"));
+ }
+
+ [Fact]
+ public void DifferingPlaceholders_AndMisspelledOrOrphanKeys_AreReported()
+ {
+ var problems = TextAudit.Verify(Fixtures, TextAudit.KeysOf(typeof(WrongKeys)), "nl", "en");
+
+ problems.Should().Contain(p => p.Contains("'sample.hello'") && p.Contains("placeholders {name}"));
+ problems.Should().Contain("[nl] missing text for key 'sample.plian'");
+ problems.Should().Contain(p => p.Contains("'sample.onlynl'") && p.Contains("not declared"));
+ }
+
+ [Fact]
+ public void ARequiredLanguageWithoutAFile_IsReported()
+ => TextAudit.Verify(Fixtures, TextAudit.KeysOf(typeof(AllSampleKeys)), "nl", "en", "de")
+ .Should().Contain(p => p.Contains("language 'de'"));
+
+ [Fact]
+ public void ADuplicateKeyDeclaration_IsReported()
+ => TextAudit.Verify(Fixtures, [new TextKey("sample.plain"), new TextKey("sample.plain")], "nl")
+ .Should().Contain("key 'sample.plain' is declared more than once");
+}
diff --git a/src/SlpModularCms.Core.Tests/Texts/TextCatalogTests.cs b/src/SlpModularCms.Core.Tests/Texts/TextCatalogTests.cs
new file mode 100644
index 0000000..d713b10
--- /dev/null
+++ b/src/SlpModularCms.Core.Tests/Texts/TextCatalogTests.cs
@@ -0,0 +1,215 @@
+using FluentAssertions;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using SlpModularCms.Core.Texts;
+using Xunit;
+
+namespace SlpModularCms.Core.Tests.Texts;
+
+public sealed class TextCatalogTests : IDisposable
+{
+ private static readonly TextKey Hello = new("sample.hello", "name");
+ private static readonly TextKey Plain = new("sample.plain");
+ private static readonly TextKey OnlyNl = new("sample.onlynl");
+ private static readonly TextKey Deep = new("sample.nested.deep");
+ private static readonly TextKey Nope = new("sample.does.not.exist");
+
+ private readonly string _folder = Path.Combine(Path.GetTempPath(), "slp-texts-" + Guid.NewGuid().ToString("N"));
+ private readonly List _errors = [];
+
+ public void Dispose()
+ {
+ if (Directory.Exists(_folder)) Directory.Delete(_folder, recursive: true);
+ }
+
+ private sealed class ListLogger(List sink) : ILogger
+ {
+ public IDisposable? BeginScope(TState state) where TState : notnull => null;
+ public bool IsEnabled(LogLevel logLevel) => true;
+ public void Log(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func formatter)
+ {
+ if (logLevel >= LogLevel.Warning) sink.Add(formatter(state, exception));
+ }
+ }
+
+ private sealed class FixedOverrides(Dictionary<(string Language, string Key), string> values) : ITextOverrides
+ {
+ public string? Find(string language, string key) => values.GetValueOrDefault((language, key));
+ }
+
+ private TextCatalog Catalog(string defaultLanguage = "nl", string? directory = null, params ITextOverrides[] overrides) => new(
+ Options.Create(new TextsOptions { DefaultLanguage = defaultLanguage, Directory = directory }),
+ [new TextAssembly(typeof(TextCatalogTests).Assembly)],
+ overrides,
+ new ListLogger(_errors));
+
+ private void WriteFolder(string file, string json)
+ {
+ Directory.CreateDirectory(_folder);
+ File.WriteAllText(Path.Combine(_folder, file), json);
+ }
+
+ [Fact]
+ public void TheDefaultLanguageIsUsed_WhenNoneIsAsked_AndPlaceholdersAreFilled()
+ {
+ Catalog().Get(Hello, args: ("name", "Jan")).Should().Be("Hallo Jan");
+ Catalog("en").Get(Hello, args: ("name", "Jan")).Should().Be("Hello Jan");
+ }
+
+ [Theory]
+ [InlineData("en", "Hello Jan")]
+ [InlineData("EN", "Hello Jan")]
+ [InlineData("en-GB", "Hello Jan")]
+ [InlineData("nl", "Hallo Jan")]
+ public void AnAskedLanguage_WinsOverTheDefault(string asked, string expected)
+ => Catalog().Get(Hello, asked, ("name", "Jan")).Should().Be(expected);
+
+ [Fact]
+ public void NestedJson_BecomesDottedKeys()
+ => Catalog().Get(Deep).Should().Be("Diep");
+
+ [Fact]
+ public void AnUnknownLanguage_FallsBackToTheDefault_AndIsReportedOnce()
+ {
+ var catalog = Catalog();
+
+ catalog.Get(Plain, "fr").Should().Be("Gewone tekst");
+ catalog.Get(Plain, "fr").Should().Be("Gewone tekst");
+
+ _errors.Should().ContainSingle().Which.Should().Contain("sample.plain").And.Contain("fr");
+ }
+
+ [Fact]
+ public void ATextMissingInTheAskedLanguage_FallsBack_AndIsReportedOnce()
+ {
+ var catalog = Catalog();
+
+ catalog.Get(OnlyNl, "en").Should().Be("Alleen nl");
+ catalog.Get(OnlyNl, "en");
+
+ _errors.Should().ContainSingle();
+ }
+
+ [Fact]
+ public void AMissingKey_ReturnsTheKeyPath_NeverThrows_AndIsReportedOnce()
+ {
+ var catalog = Catalog();
+
+ catalog.Get(Nope).Should().Be("sample.does.not.exist");
+ catalog.Get(Nope).Should().Be("sample.does.not.exist");
+
+ _errors.Should().ContainSingle().Which.Should().Contain("sample.does.not.exist");
+ }
+
+ [Fact]
+ public void AMissingValueForAPlaceholder_LeavesItInTheText_AndIsReported()
+ {
+ Catalog().Get(Hello).Should().Be("Hallo {name}");
+
+ _errors.Should().ContainSingle().Which.Should().Contain("name");
+ }
+
+ [Fact]
+ public void ValuesAreFormattedInvariantly_AndNullBecomesEmpty()
+ {
+ Catalog().Get(Hello, args: ("name", 1234.5m)).Should().Be("Hallo 1234.5");
+ Catalog().Get(Hello, args: ("name", null)).Should().Be("Hallo ");
+ }
+
+ // ---- layers ----
+
+ [Fact]
+ public void TheOverrideFolder_WinsOverTheEmbeddedText_KeyByKey()
+ {
+ WriteFolder("nl.json", "{ \"sample\": { \"plain\": \"Aangepast\" } }");
+
+ var catalog = Catalog(directory: _folder);
+
+ catalog.Get(Plain).Should().Be("Aangepast");
+ catalog.Get(OnlyNl).Should().Be("Alleen nl", "keys the folder does not mention keep their embedded text");
+ catalog.Get(Plain, "en").Should().Be("Plain text");
+ }
+
+ [Fact]
+ public void TheOverrideFolder_AcceptsAnyFileNamedForALanguage()
+ {
+ WriteFolder("site.en.json", "{ \"sample\": { \"plain\": \"Custom\" } }");
+
+ Catalog(directory: _folder).Get(Plain, "en").Should().Be("Custom");
+ }
+
+ [Fact]
+ public void ABrokenOverrideFile_IsIgnoredAndLogged_TheEmbeddedTextsStay()
+ {
+ WriteFolder("nl.json", "{ not json");
+
+ Catalog(directory: _folder).Get(Plain).Should().Be("Gewone tekst");
+
+ _errors.Should().ContainSingle().Which.Should().Contain("nl.json");
+ }
+
+ [Fact]
+ public void AMissingOverrideFolder_IsNoProblem_ButIsMentioned()
+ {
+ Catalog(directory: Path.Combine(_folder, "nope")).Get(Plain).Should().Be("Gewone tekst");
+
+ _errors.Should().ContainSingle().Which.Should().Contain("does not exist");
+ }
+
+ [Fact]
+ public void ADatabaseStyleOverride_WinsOverTheFolderAndTheEmbeddedText()
+ {
+ WriteFolder("nl.json", "{ \"sample\": { \"plain\": \"Map\" } }");
+ var overrides = new FixedOverrides(new() { [("nl", "sample.plain")] = "Database" });
+
+ var catalog = Catalog(directory: _folder, overrides: overrides);
+
+ catalog.Get(Plain).Should().Be("Database");
+ catalog.Get(Plain, "en").Should().Be("Plain text");
+ }
+
+ // ---- files ----
+
+ [Fact]
+ public void Flatten_AcceptsCommentsAndTrailingCommas_AndRejectsNonTextValues()
+ {
+ using var ok = new MemoryStream("{ // note\n \"a\": { \"b\": \"x\", }, }"u8.ToArray());
+ TextCatalog.Flatten(ok).Should().Equal(new Dictionary { ["a.b"] = "x" });
+
+ using var number = new MemoryStream("{ \"a\": 1 }"u8.ToArray());
+ var act = () => TextCatalog.Flatten(number);
+ act.Should().Throw().WithMessage("*'a'*");
+ }
+
+ [Theory]
+ [InlineData("SlpModularCms.Core.Texts.nl.json", "nl")]
+ [InlineData("SlpModularCms.Modules.Offerings.Texts.EN.json", "en")]
+ [InlineData("SlpModularCms.Core.Tests.TextFixtures.Sample.Texts.nl.json", "nl")]
+ [InlineData("SlpModularCms.Core.Hosting.WebsitePlaceholder.html", null)]
+ [InlineData("SlpModularCms.Core.Texts.nl.txt", null)]
+ public void OnlyTextResources_AreRecognised(string resource, string? language)
+ => TextCatalog.LanguageOfResource(resource).Should().Be(language);
+
+ [Fact]
+ public void PlaceholdersIn_ListsTheNames()
+ => TextCatalog.PlaceholdersIn("Hallo {name}, {site} {name} {1} { x }").Should().BeEquivalentTo(["name", "site"]);
+
+ // ---- registration ----
+
+ [Fact]
+ public void TheRealRegistration_ResolvesTheCatalog_WithCoreAssembly()
+ {
+ var services = new ServiceCollection();
+ services.AddLogging();
+ var configuration = new ConfigurationBuilder()
+ .AddInMemoryCollection(new Dictionary { ["Texts:DefaultLanguage"] = "en" }).Build();
+ services.AddCmsTexts(configuration).AddCmsTextsFrom(typeof(TextCatalogTests).Assembly);
+
+ var catalog = services.BuildServiceProvider().GetRequiredService();
+
+ catalog.DefaultLanguage.Should().Be("en");
+ catalog.Get(Plain).Should().Be("Plain text");
+ }
+}
diff --git a/src/SlpModularCms.Core/Hosting/ServiceCollectionExtensions.cs b/src/SlpModularCms.Core/Hosting/ServiceCollectionExtensions.cs
index 6f82dc7..ddce67a 100644
--- a/src/SlpModularCms.Core/Hosting/ServiceCollectionExtensions.cs
+++ b/src/SlpModularCms.Core/Hosting/ServiceCollectionExtensions.cs
@@ -1,3 +1,4 @@
+using SlpModularCms.Core.Texts;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Authorization.Policy;
@@ -36,6 +37,9 @@ public static class ServiceCollectionExtensions
{
public static IServiceCollection AddCoreInfrastructure(this IServiceCollection services, IConfiguration configuration)
{
+ // Static user-facing texts (mails, messages, host pages), see docs/translation-files.md
+ services.AddCmsTexts(configuration);
+
// 1. Database
services.AddDbContext(options =>
{
diff --git a/src/SlpModularCms.Core/SlpModularCms.Core.csproj b/src/SlpModularCms.Core/SlpModularCms.Core.csproj
index 3606887..637a3e3 100644
--- a/src/SlpModularCms.Core/SlpModularCms.Core.csproj
+++ b/src/SlpModularCms.Core/SlpModularCms.Core.csproj
@@ -69,6 +69,7 @@
-->
+
diff --git a/src/SlpModularCms.Core/Texts/TextAudit.cs b/src/SlpModularCms.Core/Texts/TextAudit.cs
new file mode 100644
index 0000000..8787d3f
--- /dev/null
+++ b/src/SlpModularCms.Core/Texts/TextAudit.cs
@@ -0,0 +1,106 @@
+using System.Reflection;
+
+namespace SlpModularCms.Core.Texts;
+
+///
+/// Checks the text files of an assembly against its typed keys. Used by the tests of every project that owns texts, so
+/// that a key that is missing in a language, a placeholder that differs between languages, a key that code declares but
+/// no file has, or a text nothing uses fails a test instead of showing up on a user's screen.
+///
+public static class TextAudit
+{
+ /// Every declared as a public static field or property of the types (nested types included).
+ public static IReadOnlyList KeysOf(params Type[] holders)
+ {
+ var keys = new List();
+ foreach (var holder in holders)
+ {
+ Collect(holder, keys);
+ }
+
+ return keys;
+ }
+
+ private static void Collect(Type type, List into)
+ {
+ const BindingFlags flags = BindingFlags.Public | BindingFlags.Static | BindingFlags.DeclaredOnly;
+ foreach (var field in type.GetFields(flags).Where(f => f.FieldType == typeof(TextKey)))
+ {
+ into.Add((TextKey)field.GetValue(null)!);
+ }
+
+ foreach (var property in type.GetProperties(flags).Where(p => p.PropertyType == typeof(TextKey)))
+ {
+ into.Add((TextKey)property.GetValue(null)!);
+ }
+
+ foreach (var nested in type.GetNestedTypes(BindingFlags.Public))
+ {
+ Collect(nested, into);
+ }
+ }
+
+ /// The embedded texts of an assembly: language to flat keys.
+ public static IReadOnlyDictionary> EmbeddedTexts(Assembly assembly)
+ {
+ var result = new Dictionary>(StringComparer.Ordinal);
+ foreach (var resource in assembly.GetManifestResourceNames())
+ {
+ var language = TextCatalog.LanguageOfResource(resource);
+ if (language is null)
+ {
+ continue;
+ }
+
+ using var stream = assembly.GetManifestResourceStream(resource)!;
+ result[language] = TextCatalog.Flatten(stream);
+ }
+
+ return result;
+ }
+
+ ///
+ /// The problems found (empty = fine). must all have a file; every language
+ /// that has a file must contain exactly the declared keys, each with exactly the declared placeholders.
+ ///
+ public static IReadOnlyList Verify(Assembly assembly, IReadOnlyCollection declared, params string[] requiredLanguages)
+ {
+ var problems = new List();
+ var texts = EmbeddedTexts(assembly);
+
+ foreach (var language in requiredLanguages.Where(l => !texts.ContainsKey(l)))
+ {
+ problems.Add($"{assembly.GetName().Name}: no text file for language '{language}'");
+ }
+
+ var duplicates = declared.GroupBy(k => k.Path, StringComparer.Ordinal).Where(g => g.Count() > 1).Select(g => g.Key);
+ problems.AddRange(duplicates.Select(d => $"key '{d}' is declared more than once"));
+
+ foreach (var (language, entries) in texts)
+ {
+ foreach (var key in declared)
+ {
+ if (!entries.TryGetValue(key.Path, out var text))
+ {
+ problems.Add($"[{language}] missing text for key '{key.Path}'");
+ continue;
+ }
+
+ var found = TextCatalog.PlaceholdersIn(text);
+ var expected = key.Placeholders.ToHashSet(StringComparer.Ordinal);
+ if (!found.SetEquals(expected))
+ {
+ problems.Add($"[{language}] '{key.Path}' has placeholders {{{string.Join(",", found.OrderBy(x => x))}}} but the key declares {{{string.Join(",", expected.OrderBy(x => x))}}}");
+ }
+ }
+
+ var declaredPaths = declared.Select(k => k.Path).ToHashSet(StringComparer.Ordinal);
+ foreach (var orphan in entries.Keys.Where(k => !declaredPaths.Contains(k)))
+ {
+ problems.Add($"[{language}] text '{orphan}' is not declared by any key (unused or misspelled)");
+ }
+ }
+
+ return problems;
+ }
+}
diff --git a/src/SlpModularCms.Core/Texts/TextCatalog.cs b/src/SlpModularCms.Core/Texts/TextCatalog.cs
new file mode 100644
index 0000000..951572f
--- /dev/null
+++ b/src/SlpModularCms.Core/Texts/TextCatalog.cs
@@ -0,0 +1,308 @@
+using System.Collections.Concurrent;
+using System.Globalization;
+using System.Reflection;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace SlpModularCms.Core.Texts;
+
+///
+/// A text of the backend by its key. is a lower-case dotted path
+/// (module.subject.part, for example core.mail.invitation.subject); are the
+/// names of the {name} placeholders every language version of the text must contain (checked by tests).
+///
+public sealed record TextKey(string Path, params string[] Placeholders)
+{
+ public override string ToString() => Path;
+}
+
+/// Settings of the text catalogue (section Texts).
+public sealed class TextsOptions
+{
+ public const string SectionName = "Texts";
+
+ /// The language used when none is asked for or the asked one has no text. Default nl.
+ public string DefaultLanguage { get; set; } = "nl";
+
+ ///
+ /// Optional folder with override files (nl.json, en.json, or any *.nl.json): same nested JSON
+ /// as the embedded files; a key found here wins over the embedded text. Lets a site change a text at deploy time
+ /// without a rebuild.
+ ///
+ public string? Directory { get; set; }
+}
+
+///
+/// A later, finer override layer (for example from the database, editable in the CMS). Consulted before the override
+/// folder and the embedded files. Nothing implements it yet; the catalogue already honours it.
+///
+public interface ITextOverrides
+{
+ /// The overriding text for in , or null.
+ string? Find(string language, string key);
+}
+
+/// An assembly whose embedded Texts/{language}.json files belong to the catalogue.
+public sealed record TextAssembly(Assembly Assembly);
+
+///
+/// Access to the backend's static, user-facing texts (mails, messages shown to users, host pages, the text of
+/// injected HTML). Texts live in JSON files per language; see docs/translation-files.md.
+///
+public interface ITextCatalog
+{
+ /// The default language of this site.
+ string DefaultLanguage { get; }
+
+ ///
+ /// The text for in (default language when null or unknown), with
+ /// the {name} placeholders replaced. Never throws: a missing text is logged once and the key path is returned.
+ ///
+ string Get(TextKey key, string? language = null, params (string Name, object? Value)[] args);
+}
+
+public sealed partial class TextCatalog : ITextCatalog
+{
+ private static readonly string[] LastResortLanguages = ["nl", "en"];
+
+ private readonly ILogger _logger;
+ private readonly IReadOnlyList _overrides;
+ private readonly Dictionary> _folder;
+ private readonly Dictionary> _embedded;
+ private readonly ConcurrentDictionary _reported = new();
+
+ public string DefaultLanguage { get; }
+
+ public TextCatalog(
+ IOptions options,
+ IEnumerable assemblies,
+ IEnumerable overrides,
+ ILogger logger)
+ {
+ _logger = logger;
+ _overrides = overrides.ToList();
+ DefaultLanguage = NormalizeLanguage(options.Value.DefaultLanguage) ?? "nl";
+ _embedded = LoadEmbedded(assemblies.Select(a => a.Assembly));
+ _folder = LoadFolder(options.Value.Directory, logger);
+ }
+
+ /// The languages that have embedded texts.
+ public IReadOnlyCollection Languages => _embedded.Keys;
+
+ public string Get(TextKey key, string? language = null, params (string Name, object? Value)[] args)
+ {
+ var wanted = NormalizeLanguage(language) ?? DefaultLanguage;
+ foreach (var candidate in Chain(wanted))
+ {
+ var text = Find(candidate, key.Path);
+ if (text is null)
+ {
+ continue;
+ }
+
+ if (!string.Equals(candidate, wanted, StringComparison.Ordinal))
+ {
+ Report($"{key.Path}|fallback|{wanted}", "Text {Key} has no {Wanted} version; using {Used}", key.Path, wanted, candidate);
+ }
+
+ return Format(key, text, args);
+ }
+
+ Report($"{key.Path}|missing", "Text {Key} does not exist in any language", key.Path);
+ return key.Path;
+ }
+
+ /// Whether a text exists for the key in exactly this language (any layer).
+ public bool Has(string language, string key) => Find(language, key) is not null;
+
+ private IEnumerable Chain(string wanted)
+ {
+ var seen = new HashSet(StringComparer.Ordinal);
+ foreach (var language in new[] { wanted, DefaultLanguage }.Concat(LastResortLanguages))
+ {
+ if (seen.Add(language))
+ {
+ yield return language;
+ }
+ }
+ }
+
+ private string? Find(string language, string key)
+ {
+ foreach (var layer in _overrides)
+ {
+ if (layer.Find(language, key) is { } overridden)
+ {
+ return overridden;
+ }
+ }
+
+ if (_folder.TryGetValue(language, out var folder) && folder.TryGetValue(key, out var fromFolder))
+ {
+ return fromFolder;
+ }
+
+ return _embedded.TryGetValue(language, out var embedded) && embedded.TryGetValue(key, out var text) ? text : null;
+ }
+
+ private string Format(TextKey key, string text, (string Name, object? Value)[] args)
+ {
+ if (text.IndexOf('{') < 0)
+ {
+ return text;
+ }
+
+ var values = args.ToDictionary(a => a.Name, a => a.Value, StringComparer.Ordinal);
+ return PlaceholderPattern().Replace(text, match =>
+ {
+ var name = match.Groups["name"].Value;
+ if (values.TryGetValue(name, out var value))
+ {
+ return Convert.ToString(value, CultureInfo.InvariantCulture) ?? string.Empty;
+ }
+
+ Report($"{key.Path}|arg|{name}", "Text {Key} needs a value for {{{Name}}} that was not given", key.Path, name);
+ return match.Value;
+ });
+ }
+
+ private void Report(string once, string message, params object[] args)
+ {
+ if (_reported.TryAdd(once, 0))
+ {
+ _logger.LogError(message, args);
+ }
+ }
+
+ [GeneratedRegex(@"\{(?[A-Za-z][A-Za-z0-9]*)\}")]
+ private static partial Regex PlaceholderPattern();
+
+ // ---- loading ----
+
+ internal static string? NormalizeLanguage(string? language)
+ => string.IsNullOrWhiteSpace(language) ? null : language.Trim().ToLowerInvariant().Split('-')[0];
+
+ /// The names of the {name} placeholders in a text.
+ public static IReadOnlySet PlaceholdersIn(string text)
+ => PlaceholderPattern().Matches(text).Select(m => m.Groups["name"].Value).ToHashSet(StringComparer.Ordinal);
+
+ /// Reads nested JSON into flat dotted keys ({"a":{"b":"x"}} becomes a.b = "x").
+ public static Dictionary Flatten(Stream json)
+ {
+ var result = new Dictionary(StringComparer.Ordinal);
+ using var document = JsonDocument.Parse(json, new JsonDocumentOptions { CommentHandling = JsonCommentHandling.Skip, AllowTrailingCommas = true });
+ Walk(document.RootElement, string.Empty, result);
+ return result;
+ }
+
+ private static void Walk(JsonElement element, string prefix, Dictionary into)
+ {
+ switch (element.ValueKind)
+ {
+ case JsonValueKind.Object:
+ foreach (var property in element.EnumerateObject())
+ {
+ Walk(property.Value, prefix.Length == 0 ? property.Name : prefix + "." + property.Name, into);
+ }
+
+ break;
+ case JsonValueKind.String:
+ into[prefix] = element.GetString()!;
+ break;
+ default:
+ throw new FormatException($"Text '{prefix}' must be a string or an object, not {element.ValueKind}.");
+ }
+ }
+
+ private static Dictionary> LoadEmbedded(IEnumerable assemblies)
+ {
+ var result = new Dictionary>(StringComparer.Ordinal);
+ foreach (var assembly in assemblies.Distinct())
+ {
+ foreach (var resource in assembly.GetManifestResourceNames())
+ {
+ var language = LanguageOfResource(resource);
+ if (language is null)
+ {
+ continue;
+ }
+
+ using var stream = assembly.GetManifestResourceStream(resource)!;
+ var texts = Flatten(stream);
+ if (!result.TryGetValue(language, out var all))
+ {
+ result[language] = all = new Dictionary(StringComparer.Ordinal);
+ }
+
+ foreach (var (key, text) in texts)
+ {
+ if (!all.TryAdd(key, text))
+ {
+ throw new InvalidOperationException($"Text '{key}' ({language}) is defined twice (second time in {resource}).");
+ }
+ }
+ }
+ }
+
+ return result;
+ }
+
+ /// The language of an embedded resource named …Texts.{language}.json, or null.
+ public static string? LanguageOfResource(string resourceName)
+ {
+ var match = ResourceNamePattern().Match(resourceName);
+ return match.Success ? match.Groups["lang"].Value.ToLowerInvariant() : null;
+ }
+
+ [GeneratedRegex(@"\.Texts\.(?[A-Za-z]{2,3})\.json$")]
+ private static partial Regex ResourceNamePattern();
+
+ private static Dictionary> LoadFolder(string? directory, ILogger logger)
+ {
+ var result = new Dictionary>(StringComparer.Ordinal);
+ if (string.IsNullOrWhiteSpace(directory))
+ {
+ return result;
+ }
+
+ if (!System.IO.Directory.Exists(directory))
+ {
+ logger.LogWarning("Texts:Directory {Directory} does not exist; no text overrides are applied", directory);
+ return result;
+ }
+
+ foreach (var file in System.IO.Directory.EnumerateFiles(directory, "*.json").OrderBy(f => f, StringComparer.Ordinal))
+ {
+ var name = Path.GetFileNameWithoutExtension(file);
+ var language = NormalizeLanguage(name.Contains('.') ? name[(name.LastIndexOf('.') + 1)..] : name);
+ if (language is null || language.Length is < 2 or > 3)
+ {
+ continue;
+ }
+
+ try
+ {
+ using var stream = File.OpenRead(file);
+ var texts = Flatten(stream);
+ if (!result.TryGetValue(language, out var all))
+ {
+ result[language] = all = new Dictionary(StringComparer.Ordinal);
+ }
+
+ foreach (var (key, text) in texts)
+ {
+ all[key] = text;
+ }
+ }
+ catch (Exception ex) when (ex is JsonException or FormatException or IOException)
+ {
+ // A broken override file must not take the site down: the embedded texts stay in force.
+ logger.LogError(ex, "Text override file {File} could not be read and is ignored", Path.GetFileName(file));
+ }
+ }
+
+ return result;
+ }
+}
diff --git a/src/SlpModularCms.Core/Texts/TextsServiceCollectionExtensions.cs b/src/SlpModularCms.Core/Texts/TextsServiceCollectionExtensions.cs
new file mode 100644
index 0000000..c040bc2
--- /dev/null
+++ b/src/SlpModularCms.Core/Texts/TextsServiceCollectionExtensions.cs
@@ -0,0 +1,33 @@
+using System.Reflection;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+
+namespace SlpModularCms.Core.Texts;
+
+public static class TextsServiceCollectionExtensions
+{
+ ///
+ /// Registers the text catalogue with the texts embedded in Core. A module with texts of its own adds its assembly with
+ /// (embedded Texts/nl.json, Texts/en.json).
+ ///
+ public static IServiceCollection AddCmsTexts(this IServiceCollection services, IConfiguration configuration)
+ {
+ services.AddOptions().Bind(configuration.GetSection(TextsOptions.SectionName));
+ services.AddCmsTextsFrom(typeof(TextCatalog).Assembly);
+ services.TryAddSingleton();
+ services.TryAddSingleton(provider => (TextCatalog)provider.GetRequiredService());
+ return services;
+ }
+
+ /// Adds the embedded texts of an assembly to the catalogue.
+ public static IServiceCollection AddCmsTextsFrom(this IServiceCollection services, Assembly assembly)
+ {
+ if (!services.Any(d => d.ServiceType == typeof(TextAssembly) && d.ImplementationInstance is TextAssembly t && t.Assembly == assembly))
+ {
+ services.AddSingleton(new TextAssembly(assembly));
+ }
+
+ return services;
+ }
+}
diff --git a/src/SlpModularCms.Core/Texts/en.json b/src/SlpModularCms.Core/Texts/en.json
new file mode 100644
index 0000000..2c63c08
--- /dev/null
+++ b/src/SlpModularCms.Core/Texts/en.json
@@ -0,0 +1,2 @@
+{
+}
diff --git a/src/SlpModularCms.Core/Texts/nl.json b/src/SlpModularCms.Core/Texts/nl.json
new file mode 100644
index 0000000..2c63c08
--- /dev/null
+++ b/src/SlpModularCms.Core/Texts/nl.json
@@ -0,0 +1,2 @@
+{
+}