Vertaalbestanden 1/6: tekstcatalogus (JSON per taal, benoemde plaatshouders, typed sleutels, lagen: map-override en later database, fail-soft) + TextAudit en tests
Embedded resources met WithCulture=false (anders maakt de SDK van 'X.Texts.en.json' een satellite-assembly). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -29,6 +29,10 @@
|
||||
<Using Include="Xunit" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<EmbeddedResource Include="TextFixtures\*.json" WithCulture="false" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\SlpModularCms.Core\SlpModularCms.Core.csproj" />
|
||||
</ItemGroup>
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"sample": {
|
||||
"hello": "Hello {name}",
|
||||
"nested": { "deep": "Deep" },
|
||||
"plain": "Plain text"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"sample": {
|
||||
"hello": "Hallo {name}",
|
||||
"onlynl": "Alleen nl",
|
||||
"nested": { "deep": "Diep" },
|
||||
"plain": "Gewone tekst"
|
||||
}
|
||||
}
|
||||
@@ -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");
|
||||
}
|
||||
@@ -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<string> _errors = [];
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
if (Directory.Exists(_folder)) Directory.Delete(_folder, recursive: true);
|
||||
}
|
||||
|
||||
private sealed class ListLogger(List<string> sink) : ILogger<TextCatalog>
|
||||
{
|
||||
public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
|
||||
public bool IsEnabled(LogLevel logLevel) => true;
|
||||
public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> 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<string, string> { ["a.b"] = "x" });
|
||||
|
||||
using var number = new MemoryStream("{ \"a\": 1 }"u8.ToArray());
|
||||
var act = () => TextCatalog.Flatten(number);
|
||||
act.Should().Throw<FormatException>().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<string, string?> { ["Texts:DefaultLanguage"] = "en" }).Build();
|
||||
services.AddCmsTexts(configuration).AddCmsTextsFrom(typeof(TextCatalogTests).Assembly);
|
||||
|
||||
var catalog = services.BuildServiceProvider().GetRequiredService<ITextCatalog>();
|
||||
|
||||
catalog.DefaultLanguage.Should().Be("en");
|
||||
catalog.Get(Plain).Should().Be("Plain text");
|
||||
}
|
||||
}
|
||||
@@ -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<ApplicationDbContext>(options =>
|
||||
{
|
||||
|
||||
@@ -69,6 +69,7 @@
|
||||
-->
|
||||
<ItemGroup>
|
||||
<EmbeddedResource Include="Hosting\WebsitePlaceholder.html" />
|
||||
<EmbeddedResource Include="Texts\*.json" WithCulture="false" />
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
using System.Reflection;
|
||||
|
||||
namespace SlpModularCms.Core.Texts;
|
||||
|
||||
/// <summary>
|
||||
/// 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.
|
||||
/// </summary>
|
||||
public static class TextAudit
|
||||
{
|
||||
/// <summary>Every <see cref="TextKey"/> declared as a public static field or property of the types (nested types included).</summary>
|
||||
public static IReadOnlyList<TextKey> KeysOf(params Type[] holders)
|
||||
{
|
||||
var keys = new List<TextKey>();
|
||||
foreach (var holder in holders)
|
||||
{
|
||||
Collect(holder, keys);
|
||||
}
|
||||
|
||||
return keys;
|
||||
}
|
||||
|
||||
private static void Collect(Type type, List<TextKey> 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);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The embedded texts of an assembly: language to flat keys.</summary>
|
||||
public static IReadOnlyDictionary<string, Dictionary<string, string>> EmbeddedTexts(Assembly assembly)
|
||||
{
|
||||
var result = new Dictionary<string, Dictionary<string, string>>(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;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The problems found (empty = fine). <paramref name="requiredLanguages"/> must all have a file; every language
|
||||
/// that has a file must contain exactly the declared keys, each with exactly the declared placeholders.
|
||||
/// </summary>
|
||||
public static IReadOnlyList<string> Verify(Assembly assembly, IReadOnlyCollection<TextKey> declared, params string[] requiredLanguages)
|
||||
{
|
||||
var problems = new List<string>();
|
||||
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;
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
/// <summary>
|
||||
/// A text of the backend by its key. <see cref="Path"/> is a lower-case dotted path
|
||||
/// (<c>module.subject.part</c>, for example <c>core.mail.invitation.subject</c>); <see cref="Placeholders"/> are the
|
||||
/// names of the <c>{name}</c> placeholders every language version of the text must contain (checked by tests).
|
||||
/// </summary>
|
||||
public sealed record TextKey(string Path, params string[] Placeholders)
|
||||
{
|
||||
public override string ToString() => Path;
|
||||
}
|
||||
|
||||
/// <summary>Settings of the text catalogue (section <c>Texts</c>).</summary>
|
||||
public sealed class TextsOptions
|
||||
{
|
||||
public const string SectionName = "Texts";
|
||||
|
||||
/// <summary>The language used when none is asked for or the asked one has no text. Default <c>nl</c>.</summary>
|
||||
public string DefaultLanguage { get; set; } = "nl";
|
||||
|
||||
/// <summary>
|
||||
/// Optional folder with override files (<c>nl.json</c>, <c>en.json</c>, or any <c>*.nl.json</c>): 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.
|
||||
/// </summary>
|
||||
public string? Directory { get; set; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 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.
|
||||
/// </summary>
|
||||
public interface ITextOverrides
|
||||
{
|
||||
/// <summary>The overriding text for <paramref name="key"/> in <paramref name="language"/>, or null.</summary>
|
||||
string? Find(string language, string key);
|
||||
}
|
||||
|
||||
/// <summary>An assembly whose embedded <c>Texts/{language}.json</c> files belong to the catalogue.</summary>
|
||||
public sealed record TextAssembly(Assembly Assembly);
|
||||
|
||||
/// <summary>
|
||||
/// 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 <c>docs/translation-files.md</c>.
|
||||
/// </summary>
|
||||
public interface ITextCatalog
|
||||
{
|
||||
/// <summary>The default language of this site.</summary>
|
||||
string DefaultLanguage { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The text for <paramref name="key"/> in <paramref name="language"/> (default language when null or unknown), with
|
||||
/// the <c>{name}</c> placeholders replaced. Never throws: a missing text is logged once and the key path is returned.
|
||||
/// </summary>
|
||||
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<TextCatalog> _logger;
|
||||
private readonly IReadOnlyList<ITextOverrides> _overrides;
|
||||
private readonly Dictionary<string, Dictionary<string, string>> _folder;
|
||||
private readonly Dictionary<string, Dictionary<string, string>> _embedded;
|
||||
private readonly ConcurrentDictionary<string, byte> _reported = new();
|
||||
|
||||
public string DefaultLanguage { get; }
|
||||
|
||||
public TextCatalog(
|
||||
IOptions<TextsOptions> options,
|
||||
IEnumerable<TextAssembly> assemblies,
|
||||
IEnumerable<ITextOverrides> overrides,
|
||||
ILogger<TextCatalog> 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);
|
||||
}
|
||||
|
||||
/// <summary>The languages that have embedded texts.</summary>
|
||||
public IReadOnlyCollection<string> 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;
|
||||
}
|
||||
|
||||
/// <summary>Whether a text exists for the key in exactly this language (any layer).</summary>
|
||||
public bool Has(string language, string key) => Find(language, key) is not null;
|
||||
|
||||
private IEnumerable<string> Chain(string wanted)
|
||||
{
|
||||
var seen = new HashSet<string>(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(@"\{(?<name>[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];
|
||||
|
||||
/// <summary>The names of the <c>{name}</c> placeholders in a text.</summary>
|
||||
public static IReadOnlySet<string> PlaceholdersIn(string text)
|
||||
=> PlaceholderPattern().Matches(text).Select(m => m.Groups["name"].Value).ToHashSet(StringComparer.Ordinal);
|
||||
|
||||
/// <summary>Reads nested JSON into flat dotted keys (<c>{"a":{"b":"x"}}</c> becomes <c>a.b</c> = "x").</summary>
|
||||
public static Dictionary<string, string> Flatten(Stream json)
|
||||
{
|
||||
var result = new Dictionary<string, string>(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<string, string> 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<string, Dictionary<string, string>> LoadEmbedded(IEnumerable<Assembly> assemblies)
|
||||
{
|
||||
var result = new Dictionary<string, Dictionary<string, string>>(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<string, string>(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;
|
||||
}
|
||||
|
||||
/// <summary>The language of an embedded resource named <c>…Texts.{language}.json</c>, or null.</summary>
|
||||
public static string? LanguageOfResource(string resourceName)
|
||||
{
|
||||
var match = ResourceNamePattern().Match(resourceName);
|
||||
return match.Success ? match.Groups["lang"].Value.ToLowerInvariant() : null;
|
||||
}
|
||||
|
||||
[GeneratedRegex(@"\.Texts\.(?<lang>[A-Za-z]{2,3})\.json$")]
|
||||
private static partial Regex ResourceNamePattern();
|
||||
|
||||
private static Dictionary<string, Dictionary<string, string>> LoadFolder(string? directory, ILogger logger)
|
||||
{
|
||||
var result = new Dictionary<string, Dictionary<string, string>>(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<string, string>(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;
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
{
|
||||
/// <summary>
|
||||
/// Registers the text catalogue with the texts embedded in Core. A module with texts of its own adds its assembly with
|
||||
/// <see cref="AddCmsTextsFrom"/> (embedded <c>Texts/nl.json</c>, <c>Texts/en.json</c>).
|
||||
/// </summary>
|
||||
public static IServiceCollection AddCmsTexts(this IServiceCollection services, IConfiguration configuration)
|
||||
{
|
||||
services.AddOptions<TextsOptions>().Bind(configuration.GetSection(TextsOptions.SectionName));
|
||||
services.AddCmsTextsFrom(typeof(TextCatalog).Assembly);
|
||||
services.TryAddSingleton<ITextCatalog, TextCatalog>();
|
||||
services.TryAddSingleton(provider => (TextCatalog)provider.GetRequiredService<ITextCatalog>());
|
||||
return services;
|
||||
}
|
||||
|
||||
/// <summary>Adds the embedded texts of an assembly to the catalogue.</summary>
|
||||
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;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
{
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
{
|
||||
}
|
||||
Reference in New Issue
Block a user