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 @@ +{ +}