SnappyLib.Localization 1.1.0

SnappyLib.Localization

A compile-time localization source generator for .NET. Define translations in .lang.csv files and get strongly-typed access with optional dependency injection support and random string variants.

Installation

dotnet add package SnappyLib.Localization

When installed via NuGet, all .lang.csv files in your project are automatically picked up -- no extra MSBuild configuration needed.

If you're referencing the generator as a project reference (e.g. during development), you need to manually register your .lang.csv files as AdditionalFiles in your .csproj:

<ItemGroup>
  <AdditionalFiles Include="Strings.lang.csv" />
</ItemGroup>

Quick Start

1. Create a .lang.csv file

Add a file named Strings.lang.csv (or any *.lang.csv) to your project:

Path,Name,en|English,no|Norsk
Greetings,Hello,Hello!,Hei!
Greetings,Goodbye,Goodbye!,Ha det!
Errors,NotFound,Not found,Ikke funnet

Columns:

• Path -- Groups strings into categories (becomes a nested class)
• Name -- The string identifier (becomes a property)
• code|Language -- One column per language, header format is languageCode|DisplayName

2. Use the generated code

The generator creates a class matching your file name with strongly-typed access:

// Access a localized string (defaults to first language)
var greeting = Strings.Greetings.Hello;   // "Hello!"
var error = Strings.Errors.NotFound;      // "Not found"

// Switch language
Strings.Options.CurrentLangCode = "no";
var greeting = Strings.Greetings.Hello;   // "Hei!"

Features

Root-Level Strings

Leave the Path column empty to place strings directly on the main class instead of in a nested category:

Path,Name,en|English,no|Norsk
,AppName,My App,Min App
,Version,1.0,1.0
Greetings,Hello,Hello!,Hei!

var name = Strings.AppName;          // "My App" (directly on class)
var hi = Strings.Greetings.Hello;    // "Hello!" (nested under Greetings)

This is useful for app-wide strings that don't belong to a specific category.

String Parameters

Use {paramName} placeholders for parameterized strings:

Path,Name,en|English,no|Norsk
Messages,Welcome,Hello {name}!,Hei {name}!

var msg = Strings.Messages.Welcome("John");  // "Hello John!"

Random Variants

Add multiple rows with the same Path and Name to define variants. A random variant is selected automatically:

Path,Name,en|English,no|Norsk
Greetings,Hello,Hello!,Hei!
Greetings,Hello,Hi there!,Hei der!
Greetings,Hello,Hey!,Heia!

// Returns one of: "Hello!", "Hi there!", "Hey!"
var greeting = Strings.Greetings.Hello;

// Re-roll all random selections
Strings.Regenerate();

Variants work with parameters too:

Path,Name,en|English,no|Norsk
Messages,Welcome,Hello {name},Hei {name}
Messages,Welcome,Hi {name},Heia {name}

Strings without duplicate rows are unaffected and behave normally.

Dependency Injection

When your project references Microsoft.Extensions.DependencyInjection, the generator automatically creates DI-aware code:

// Program.cs
builder.Services.AddSnappyLang();

// In a controller or service
public class MyController(Strings loc, LocOptions opts)
{
    public string GetGreeting()
    {
        opts.CurrentLangCode = "no";
        return loc.Greetings.Hello;
    }
}

In DI mode:

• Each scope gets its own LocOptions and variant selections (per-user/request)
• Regenerate() is an instance method
• Variant index fields are instance-scoped, so each user gets independent random choices

Without DI, everything is static and shared across the application.

Automatic Language Detection (ASP.NET)

In ASP.NET projects, AddSnappyLang() automatically detects the user's preferred language from the Accept-Language HTTP header. No extra configuration needed -- each request scope gets the correct language based on the browser's preferences.

// That's it -- language is auto-detected per request
builder.Services.AddSnappyLang();

The header is parsed and matched against your defined languages. For example, a browser sending Accept-Language: no,en-US;q=0.9,en;q=0.8 will match no if it's in your CSV. Both exact matches (en) and prefix matches (en-US → en) are supported.

Custom Language Provider

For full control over language selection, implement ILanguageCodeProvider and register it before AddSnappyLang(). It takes priority over Accept-Language detection:

public class MyLanguageProvider : ILanguageCodeProvider
{
    public string GetLanguageCode()
    {
        // Return a language code, or null to fall back to default detection
        return "no";
    }
}

// Program.cs
builder.Services.AddScoped<ILanguageCodeProvider, MyLanguageProvider>();
builder.Services.AddSnappyLang();

The resolution order is:

1. ILanguageCodeProvider (if registered and returns non-null)
2. Accept-Language header (ASP.NET projects only)
3. Default language (first language in CSV)

You can also override the language manually per-request if needed:

public class MyController(Strings loc, LocOptions opts)
{
    public string ForceEnglish()
    {
        opts.CurrentLangCode = "en";
        return loc.Greetings.Hello;
    }
}

Generated Structure

For a file named Strings.lang.csv:

Strings                          // Main class (static or DI-injected)
  .Options                       // LocOptions with CurrentLangCode
  .Languages                     // Dictionary<string, string> of available languages
  .AppName                       // Root-level string (empty path)
  .Greetings                     // GreetingsLocalisations (one per non-empty Path)
    .Hello                       // string property (or method if parameterized)
    .Goodbye
  .Errors
    .NotFound
  .Regenerate()                  // Re-randomize variant selections (if any variants exist)

CSV Format Reference

Path,Name,langCode1|LangName1,langCode2|LangName2,...

• Use {param} syntax in values for string parameters
• Duplicate Path,Name rows create random variants
• At least one language column is required

Translation Fallback

If a translation is missing for a language, the generator falls back to the first non-empty translation from another language in the same row and emits a compiler warning (SLOC0004):

Path,Name,en|English,no|Norsk
Greetings,Hello,Hello,

Here, Norwegian is empty so it falls back to the English value Hello. The generated doc comment marks it as (fallback) so it's visible in IDE tooltips.

If all translations are empty for a row, the generator emits a compiler error (SLOC0005) and the row is excluded from generation.