DcsvIo.D2.I18n 0.1.1

DcsvIo.D2.I18n

Runtime translation lib — Translator (loads contracts/messages/*.json catalogs and renders TKMessage instances per locale), SupportedLocales (env-driven BCP 47 locale registry with canonical-casing + language-fallback), and the AddD2I18n DI extension that wires both as singletons.

The pure-types slice (TKMessage, TK constants, ITranslator interface) lives in DcsvIo.D2.I18n.Abstractions. Domain layers reference Abstractions; this runtime is for infrastructure / composition-root code that actually renders translated strings (Courier emails, SMS, push notifications).

Translation strategy reminder. See DcsvIo.D2.I18n.Abstractions (Wire format section) for the canonical split: client-side via SvelteKit / Paraglide on HTTP-response payloads, server-side via this Translator for outbound notifications where the rendered text must be inlined before delivery.

Install

dotnet add package DcsvIo.D2.I18n

File layout

Public API

ITranslator.T(string locale, TKMessage message)

// Resolved via DI in a Courier handler:
public sealed class SendOrgInviteEmail(ITranslator translator) : ...
{
    public async ValueTask SendAsync(User recipient, ...)
    {
        var subject = translator.T(
            recipient.PreferredLocale,
            TK.Auth.Email.INVITATION_SUBJECT.With("orgName", inviting.Name));

        var body = translator.T(
            recipient.PreferredLocale,
            TK.Auth.Email.INVITATION_BODY.With("inviter", inviter.DisplayName));
        // ...
    }
}

Resolution chain:

1. SupportedLocales.Resolve(locale) normalises to canonical BCP 47 + applies language fallback (fr-CH → fr-FR if no fr-CH catalog, fr → fr-FR, etc.).
2. Lookup in the requested locale's catalog.
3. Fallback to base locale (PUBLIC_DEFAULT_LOCALE, default en-US) on miss.
4. Final fallback: return message.Key verbatim. Never throws on missing keys.

After lookup, any {paramName} placeholders in the template are substituted from message.Parameters via a source-generated regex. Unmatched placeholders are left literal.

SupportedLocales

AddD2I18n

// Composition root in a service's Program.cs:
builder.Services.AddD2I18n(builder.Configuration);

Registers both SupportedLocales and ITranslator as singletons via TryAddSingleton (idempotent — calling twice is safe). Translator's catalog directory defaults to Path.Combine(AppContext.BaseDirectory, "messages"), which is populated at build time via the consuming csproj's <Content Include="...contracts/messages/*.json" CopyToOutputDirectory="PreserveNewest" />. The default works for any service that follows the convention; pass an explicit messagesDirectory for tests or non-standard layouts.

Configuration

The indexed env-var convention matches the IConfiguration indexed-section binding used elsewhere. Casing is normalised to canonical BCP 47 at load time, so EN-us and en-US produce the same canonical entry.

Catalog files

The Translator loads any *.json file in its messages directory; each filename (without extension) is treated as the locale. The expected shape is a flat object of string-to-string:

{
  "$schema": "./schema.json",
  "common_errors_NOT_FOUND": "Not found.",
  "common_errors_FORBIDDEN": "Forbidden.",
  "auth_email_invitation_subject": "{inviter} invited you to {orgName}"
}

The $schema key is automatically stripped at load time. Parameter substitution uses {paramName} placeholders, matched against TKMessage.Parameters at render time.

The source-of-truth catalogs live in contracts/messages/. The consuming csproj copies them into the runtime via:

<ItemGroup>
  <Content Include="..\..\..\..\..\contracts\messages\*.json"
           LinkBase="messages"
           CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Dependencies

• DcsvIo.D2.I18n.Abstractions — TKMessage, ITranslator, the SrcGen-emitted TK constants
• DcsvIo.D2.Utilities — Falsey() for boundary checks during config parsing
• Microsoft.Extensions.Configuration.Abstractions + Microsoft.Extensions.Configuration.Binder — IConfiguration for env-var ingestion
• Microsoft.Extensions.DependencyInjection.Abstractions — IServiceCollection for the AddD2I18n extension

No Microsoft.AspNetCore.App framework reference — this lib is HTTP-stack-agnostic and can be consumed from console workers, Hangfire jobs, etc.

Tests

Unit tests (DcsvIo.D2.Tests I18n suite) —

• SupportedLocalesTests — ToBcp47 normalization, configuration ingestion (defaults, mixed-case, empty entries, dedup behavior), language-default ordering, IsValid / Resolve adversarial coverage.
• TranslatorTests — construction validation (null / missing / malformed dir), basic lookup, base-locale fallback, language-prefix resolution, parameter substitution (single, multiple, missing param, extra param, placeholder twice, brace-in-value non-recursion), HasKey, 100-caller concurrency stress.
• I18nServiceCollectionExtensionsTests — singleton registration, IConfiguration propagation, TryAdd idempotency, fluent return.
• TKGeneratedTests — end-to-end smoke that the SrcGen + Abstractions integration produces TK constants matching the live en-US.json.

Comprehensive coverage across every public surface — every translator path, every supported-locale operation, every DI registration branch.

Reference

• DcsvIo.D2.I18n.Abstractions — TKMessage, TK SrcGen, the wire format
• DcsvIo.D2.Result — D2Result.Messages / InputError.Errors consume TKMessage
• contracts/messages/ — the source-of-truth catalogs