SnappyLib.Localization 1.0.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

All .lang.csv files in your project are automatically picked up -- no extra MSBuild configuration needed.

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

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.

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
  .Greetings                     // GreetingsLocalisations (one per 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