JTigerNova.jtiger.lang 1.0.3

jtiger.lang

.NET Standard 2.0 library for looking up localized user-facing messages from a caller-supplied translation table.

Stateless. No I/O, no globals, no DI. The caller owns the message table; this library just resolves a key against it with a sensible fallback chain.

API

public static class Lang
{
    public static string Get(
        IReadOnlyDictionary<string, IReadOnlyDictionary<string, string>> msgs,
        string key,
        string locale                    = null,
        Action<string> onMissingKey      = null,
        Action<string> onMissingFallback = null);
}

locale is optional. When omitted (or null/empty), the resolver skips the locale-specific lookups and falls straight through to English.

Message table shape

A two-level dictionary: key → locale → message.

var msgs = new Dictionary<string, IReadOnlyDictionary<string, string>>
{
    ["greeting.hello"] = new Dictionary<string, string>
    {
        ["en"]    = "Hello",
        ["es"]    = "Hola",
        ["es-MX"] = "¿Qué onda?",
        ["fr"]    = "Bonjour",
    },
    ["greeting.bye"] = new Dictionary<string, string>
    {
        ["en"] = "Bye",
        // no es entry — falls back to English
    },
};

Fallback chain

For each Get(msgs, key, locale) call, the resolver tries in order:

1. Exact locale match.
2. Language-only fallback - strips the first dash ("es-ES" → "es").
3. English - byLocale["en"].
4. The raw key - returned verbatim if nothing else matched.

Multi-segment tags like "zh-Hans-CN" only fall back one level (to "zh-Hans"), not two ("zh").

The locale string must be in BCP-47 dash form. Underscored variants like "es_ES" are not parsed and only match if the table registered that exact spelling.

Examples

Lang.Get(msgs, "greeting.hello", "es-MX");  // "¿Qué onda?"
Lang.Get(msgs, "greeting.hello", "es-AR");  // "Hola" (language fallback)
Lang.Get(msgs, "greeting.hello", "de");     // "Hello" (English fallback)
Lang.Get(msgs, "greeting.bye", "es");       // "Bye" (no es entry; falls back to en)
Lang.Get(msgs, "greeting.unknown", "en");   // "greeting.unknown" (raw key)
Lang.Get(msgs, "greeting.hello");           // "Hello" (locale omitted → English)

Missing-key callbacks

Two optional Action<string> callbacks signal the two ways a lookup can fail to find a real translation:

• onMissingKey - fires when key is not in msgs at all. The caller probably forgot to register a message for a key the code path is using.
• onMissingFallback - fires when key IS in msgs but its inner dictionary has no English entry, so even the safety-net path returned the raw key. The caller probably needs to add an English value as a baseline.

Lang.Get(
    msgs, "greeting.unknown", "en",
    onMissingKey:      k => log.Warn($"unwired translation key: {k}"),
    onMissingFallback: k => log.Warn($"key {k} has no English fallback"));

Either callback is invoked at most once per Get call. Exceptions thrown inside a callback are swallowed so a misbehaving logger cannot break the lookup.

Exceptions

Threading

Lang.Get is pure with respect to its arguments. Concurrent calls are safe as long as the msgs dictionary you pass in is not being mutated concurrently - which is the same constraint IReadOnlyDictionary<,> already implies.