grcontin.SimpleLocalization 1.0.1

SimpleLocalization

SimpleLocalization is a high-performance, strictly typed localization library for .NET 8+. It was designed to provide a superior Developer Experience (DX) by removing the friction of managing IStringLocalizer and multiple .resx files. It allows you to localize any part of your application

Installation

Install the package via NuGet:

dotnet add package grcontin.SimpleLocalization

Why SimpleLocalization?

Standard .NET localization (IStringLocalizer) is heavily tied to Dependency Injection and brittle XML-based .resx files, forcing infrastructure concerns into layers that should remain clean. SimpleLocalization solves this with a code-first approach that requires no DI or complex setup. It delivers superior DX by keeping everything in code.

By being natively compliant with RFC 9110, it handles 'Accept-Language' headers automatically. You simply define your localizable objects and add the middleware; no extra implementations or management overhead required

RFC 9110 Compliance & Middleware Integration

HTTP Accept-Language Header

SimpleLocalization is fully compliant with modern web standards regarding content negotiation.

The library seamlessly integrates with the standard ASP.NET Core localization pipeline. It honors the Accept-Language header sent by clients, following the negotiation rules defined in RFC 9110, Section 12.5.4.

This ensures that your API remains interoperable and follows internationalization (i18n) best practices.

Culture Fallback Mechanism

The library implements a robust hierarchical fallback system. If a translation is missing for a specific sub-culture, it automatically traverses up the culture tree:

1. Specific Culture — e.g. en-US
2. Parent Culture — e.g. en
3. Default / Absolute Key — if no translation is found in the hierarchy, the library returns the fully qualified name

Benchmarks

Comparison against Microsoft.Extensions.Localization using physical .resx files.

Quick Start

1. Define your messages

Mark your class with [Localizable] and use [Translation] attributes.

• Warning: The [Localizable] attribute in this library shares the same name as the one in System.ComponentModel. To avoid unexpected behavior or compilation errors, ensure you are importing the correct namespace: using SimpleLocalization;.

[Localizable]
public static class UserErrors
{
    [Translation("en-US", "User not found.")]
    [Translation("pt-BR", "Usuário não encontrado.")]
    public static readonly LocalizableString NotFound = new();

    [Translation("en-US", "Hello {0}, you have {1} messages.")]
    public static readonly LocalizableString Notifications = new();
}

2. Initialize

Call this once at your application startup (e.g., Program.cs).

You can provide multiple assemblies, which is useful when your localization messages are distributed across different projects or modules.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSimpleLocalization(
    typeof(ApplicationAssemblyMarker).Assembly,
    typeof(DomainAssemblyMarker).Assembly
);

3. Configure Middleware (ASP.NET Core)

For the library to correctly identify the user's culture, it is crucial to configure the native .NET localization middleware. SimpleLocalization relies on the CultureInfo.CurrentUICulture set by this pipeline.

var app = builder.Build();

var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture("en-US")
    .AddSupportedCultures("en-US", "pt-BR")
    .AddSupportedUICultures("en-US", "pt-BR");

app.UseRequestLocalization(localizationOptions);

4. Use it anywhere

// Implicit conversion to string
string message = UserErrors.NotFound;

string formatted = UserErrors.Notifications.Format("Gabriel", 5);