fbognini.EfCoreLocalization 0.2.0

EFCore

A flexible, database-driven localization provider for ASP.NET Core using Entity Framework Core. This library eliminates the need for static resource files, allowing dynamic management of translations without application redeployment.

What's included

This package consists of three NuGet packages:

• fbognini.EfCoreLocalization - The core library that provides database-backed localization, including CSV export and import
• fbognini.EfCoreLocalization.Dashboard - An optional web dashboard to manage translations through a UI
• fbognini.EfCoreLocalization.Excel - An optional xlsx export and import format

Installation

Install the core library:

dotnet add package fbognini.EfCoreLocalization

Optionally, install the management dashboard:

dotnet add package fbognini.EfCoreLocalization.Dashboard

Optionally, install the Excel export and import format:

dotnet add package fbognini.EfCoreLocalization.Excel

Quick start

1. Configure your database context

Register EfCoreLocalizationDbContext to your services. You'll need to configure it with your database connection:

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<EfCoreLocalizationDbContext>(options => 
    options.UseSqlServer(connectionString, b => b.MigrationsAssembly("YourAppName")), 
    ServiceLifetime.Singleton, 
    ServiceLifetime.Singleton);

2. Register services

Add the localization services to your DI container:

builder.Services.AddLocalization();
builder.Services.AddEfCoreLocalization(builder.Configuration);

3. Apply migrations

Generate and apply the necessary database tables.

#Via .NET CLI:

dotnet ef migrations add Localization --context EfCoreLocalizationDbContext
dotnet ef database update --context EfCoreLocalizationDbContext

Via Package Manager Console in Visual Studio:

Add-Migration Localization -Context EfCoreLocalizationDbContext
Update-Database -Context EfCoreLocalizationDbContext

Alternatively, apply migrations programmatically at startup:

var app = builder.Build();

await app.ApplyMigrationEFCoreLocalization();

4. Configure middleware

Enable request localization using the database settings.

var app = builder.Build();

app.UseRequestLocalizationWithEFCoreLocalization();

Configuration

You can configure localization settings in your appsettings.json:

{
  "EfCoreLocalization": {
    "DefaultSchema": "localization",
    "ReturnOnlyKeyIfNotFound": true,
    "CreateNewRecordWhenDoesNotExists": true,
    "GlobalResourceId": null,
    "ResourceIdPrefix": null,
    "RemovePrefixsFromTypes": [],
    "RemoveSuffixsFromTypes": ["Dto"],
    "IgnoreResourceLocation": false,
    "RemovePrefixsFromLocations": [],
    "CacheExpirationMinutes": 30
  }
}

Or configure it in code:

builder.Services.AddEfCoreLocalization(options =>
{
    options.DefaultSchema = "localization";
    options.ReturnOnlyKeyIfNotFound = true;
    options.CreateNewRecordWhenDoesNotExists = true;
    options.CacheExpirationMinutes = 30; // Cache expires after 30 minutes, or null for infinite cache
});

Reference

Usage

Use standard ASP.NET Core interfaces (IViewLocalizer, IStringLocalizer<T>).

In your Razor views, inject IViewLocalizer and use it:

@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer

<h1>@Localizer["Welcome"]</h1>

Or in your code-behind/controllers:

public class IndexModel : PageModel
{
    private readonly IStringLocalizer<IndexModel> _localizer;

    public IndexModel(IStringLocalizer<IndexModel> localizer)
    {
        _localizer = localizer;
    }

    public void OnGet()
    {
        var message = _localizer["Welcome"];
    }
}

Customizing Resource IDs

By default, the Resource ID matches the type name (e.g., "IndexModel"). You can customize this using the LocalizationKeyAttribute:

[LocalizationKey("MyCustomResource")]
public class IndexModel : PageModel
{
    // ...
}

Dashboard

The Dashboard provides a UI to manage translations.

Setup

Add the dashboard middleware. If you're using MVC, make sure to register your controller routes first:

var app = builder.Build();

// For MVC apps, register routes before the dashboard
app.MapControllerRoute(
    name: "area",
    pattern: "{area:exists}/{controller=Home}/{action=Index}/{id?}");
        
app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

// Add the dashboard
app.UseEfCoreLocalizationDashboard();

app.MapRazorPages(); // or your other route mappings

The dashboard will be available at /localization by default. You can change the path:

app.UseEfCoreLocalizationDashboard(pathMatch: "my-custom-path", options: dashboardOptions);

Authorization

By default, the dashboard only allows requests from localhost. You can customize this:

var dashboardOptions = new DashboardOptions
{
    Authorization = new[] { new YourCustomAuthorizationFilter() },
    AsyncAuthorization = new[] { new YourAsyncAuthorizationFilter() }
};

Export & import

Translations can be exported to a file, handed to a translator, and imported back, getting the counts of what was added, updated and deleted — numbers meant for your own audit log.

The file uses a wide layout: one row per key, one column per language.

CSV is built into the core package. For Excel, install the optional package and register the format:

dotnet add package fbognini.EfCoreLocalization.Excel

builder.Services.AddEfCoreLocalizationExcel();

Both are consumed through ITranslationsPortabilityService, which picks the format, applies the file and refreshes the localizer cache:

app.MapGet("/translations/export", (ITranslationsPortabilityService service, string? format) =>
{
    var translationsFormat = service.ResolveFormat(format);   // "csv", "xlsx", "excel", ".xlsx" or a file name

    var buffer = new MemoryStream();
    service.Export(buffer, new TranslationsExportFilter { ResourceIds = ["dashboard"] }, translationsFormat.Name);
    buffer.Position = 0;

    return Results.File(buffer, translationsFormat.ContentType, $"translations{translationsFormat.FileExtension}");
});

app.MapPost("/translations/import", async (ITranslationsPortabilityService service, IFormFile file) =>
{
    await using var stream = file.OpenReadStream();

    var result = service.Import(stream, new ImportTranslationsOptions(), file.FileName);

    logger.LogInformation("Import: {Created} keys created, {Updated} translations updated, {Deleted} keys deleted",
        result.TextsCreated, result.TranslationsUpdated, result.TextsDeleted);

    return Results.Ok(result);
}).DisableAntiforgery();

The same flow is available from the Dashboard, under Translations → Export / Import.

Import options

An empty cell means "no value supplied", never "delete": the stored translation is left untouched and counted in TranslationsSkipped. Deletions only ever happen through DeleteNotMatched.

Rejected rows do not stop the others: the rest is imported and every problem is reported in ImportTranslationsResult.Errors with its source row, its kind and a reason. Only a structurally unusable file throws — one whose language columns match no language at all.

Localizer cache

An import that changed something drops the localizer cache, so the new texts are served right away. The cache is per process: if you run more than one instance, set CacheExpirationMinutes so that the others pick the changes up as well. Adding a language still requires a restart, because the supported cultures are read once at startup.

How it works

The library stores translations in three main tables:

• Languages - The languages you support (e.g., "en-US", "it-IT", "fr-FR")
• Texts - The text keys you want to translate (identified by TextId and ResourceId)
• Translations - The actual translated text for each language

When you call Localizer["MyKey"], the library:

1. Looks up the current culture from CultureInfo.CurrentCulture
2. Searches for a translation matching the key and culture
3. Returns the translated text, or the key itself if not found (depending on your settings)

Caching

Translations are cached in memory to improve performance. By default, the cache never expires. You can configure cache expiration using CacheExpirationMinutes:

• Set to null (default): Cache never expires, translations are loaded once and kept in memory
• Set to a number (e.g., 30): Cache expires after the specified number of minutes, forcing a reload from the database

The cache is checked lazily - expiration is verified when accessing a resource, not on a timer.

Example project

Check out the SampleWebApp project in the repository for a complete working example.

Migrating from fbognini.i18n

This library is the successor of fbognini.i18n.

Replace the namespace fbognini.i18n with fbognini.EfCoreLocalization, then update the API and the settings.

The configuration section is now named EfCoreLocalization instead of I18nSettings, and the settings are flat.

The Languages, Texts and Translations tables kept the same structure: only the schema changed, Texts.Created became Texts.CreatedOnUtc, Translations.Updated became Translations.UpdatedOnUtc and the Configurations table is no longer used. The full step by step guide, including the SQL to copy the existing rows, is in the fbognini.i18n readme.

Requirements

• .NET 8.0 or later
• Entity Framework Core 8.0 or later
• A database provider compatible with EF Core

Acknowledgments

This code was freely inspired by AspNetCoreLocalization by damienbod.