SSolutions.LocalizationKit 1.0.3

LocalizationKit

Reusable ASP.NET Core localization engine for .NET 8. The package is an engine only — it contains zero .resx files. You supply your own resource files; supported cultures are auto-detected at startup.

Installation

dotnet add package LocalizationKit

Quick Setup

1. Add resource files to your project

YourApi/
├── Resources/
│   ├── SharedResource.cs          ← marker class
│   ├── SharedResource.resx        ← English (base/default)
│   ├── SharedResource.ar.resx     ← Arabic  (auto-detected)
│   └── SharedResource.fr.resx     ← French  (auto-detected)

Resources/SharedResource.cs — marker class, no logic:

namespace YourApi.Resources;

public class SharedResource { }

.csproj — mark all .resx files as embedded resources:

<ItemGroup>
  <EmbeddedResource Include="Resources\SharedResource.resx" />
  <EmbeddedResource Include="Resources\SharedResource.ar.resx" />
  <EmbeddedResource Include="Resources\SharedResource.fr.resx" />
</ItemGroup>

2. Register in Program.cs

using YourApi.Resources;
using LocalizationKit.Extensions;

// Minimal — cultures auto-detected from .resx files
builder.Services.AddLocalizationKit(options =>
    options.ResourcesAssembly = typeof(SharedResource).Assembly);

var app = builder.Build();

// Add after UseRouting(), before UseAuthorization()
app.UseLocalizationKit();

Full options:

builder.Services.AddLocalizationKit(options =>
{
    options.ResourcesAssembly = typeof(SharedResource).Assembly;
    options.ResourcesPath     = "Resources";       // default
    options.ResourceBaseName  = "SharedResource";  // default
    options.DefaultCulture    = "en-US";           // default
    options.SupportedCultures = new() { "en-US", "ar-SA" }; // override auto-detect
});

3. Use in controllers and services

public class CompaniesController : ControllerBase
{
    private readonly ILocalizationService _loc;

    public CompaniesController(ILocalizationService loc) => _loc = loc;

    [HttpGet("{id}")]
    public async Task<IActionResult> Get(int id)
    {
        var company = await _service.GetByIdAsync(id);
        if (company is null)
            return NotFound(new { message = _loc.T("Error_NotFound") });

        return Ok(new {
            data    = company,
            isRtl   = _loc.IsRtl,
            culture = _loc.CurrentCulture
        });
    }
}

ILocalizationService API

Culture Detection (per request)

The response always includes a Content-Language header showing the culture actually used.

Short codes are normalized automatically:

.resx Key Naming Convention

Use Category_Description format:

Placeholders use {0}, {1}:

<data name="Validation_Required" xml:space="preserve">
  <value>{0} is required</value>
</data>

_loc.T("Validation_Required", "Name") // → "Name is required"

Optional: Auto-generate Key Constants (T4 Template)

Add Resources/LocalizationKeys.tt to avoid typing key strings manually. The T4 reads SharedResource.resx and generates LocalizationKeys.cs grouped by prefix. To regenerate: right-click LocalizationKeys.tt → Run Custom Tool.

Generated output:

// Auto-generated from SharedResource.resx — do not edit manually
public static class LocalizationKeys
{
    public static class Error
    {
        public const string NotFound     = "Error_NotFound";
        public const string Unauthorized = "Error_Unauthorized";
        public const string ServerError  = "Error_ServerError";
    }
    public static class Success
    {
        public const string Created = "Success_Created";
        public const string Updated = "Success_Updated";
        public const string Deleted = "Success_Deleted";
    }
    public static class Validation
    {
        public const string Required     = "Validation_Required";
        public const string MaxLength    = "Validation_MaxLength";
        public const string InvalidEmail = "Validation_InvalidEmail";
    }
}

Usage:

return NotFound(new { message = _loc.T(LocalizationKeys.Error.NotFound) });

Adding a New Language

1. Drop SharedResource.{culture}.resx into the Resources/ folder
2. Add it as EmbeddedResource in the .csproj
3. That is it — no Program.cs changes needed

CultureScanner detects it automatically on next startup.

IsRtl Behaviour

Uses CultureInfo.CurrentUICulture.TextInfo.IsRightToLeft — not a hardcoded language list. Works for any RTL language: Arabic, Urdu, Hebrew, Farsi, and any future addition.