DEV Community: Angelo Pirola

TinyLocalization: database-backed translations for .NET, without redeploying

Angelo Pirola — Tue, 03 Nov 2026 22:45:00 +0000

Every .NET developer has been there. A customer finds a typo in the Italian translation, and fixing it means editing a .resx file, rebuilding, and redeploying the whole application. For one word.

I wanted translations to behave like data, not like code. So I built TinyLocalization, a small open-source library that stores your translations in a database and plugs into the standard Microsoft.Extensions.Localization abstractions.

The repository is here: AngeloDotNet/TinyDatabaseLocalization.

What it does

The idea is deliberately simple: you keep using IStringLocalizer, but the strings come from a database table instead of resource files. You can add, fix or remove a translation at runtime, and the change is live without a redeploy.

Main features:

Standard API: works with IStringLocalizer, IStringLocalizer<T> and IStringLocalizerFactory, so existing code does not need to change.
Culture fallback: current culture, then parent cultures, then an optional global fallback, then the invariant culture.
Format arguments: localizer["Hello {0}", name] works as you would expect.
Four database providers: SQLite, SQL Server, PostgreSQL and MySQL.
FusionCache under the hood: fail-safe, timeouts, eager refresh and stampede protection.
Optional Redis: as a second-level cache and as a backplane for multi-instance invalidation.
One simple table: Translations, unique on (Resource, Key, Culture).

The stack

The library targets .NET 10 and is built on Entity Framework Core. Caching is handled by FusionCache, which I picked over a hand-rolled IMemoryCache wrapper for one reason: caching translations looks trivial until you meet cache stampedes, slow databases and multi-node invalidation. FusionCache already solved those problems, so I did not have to.

Tests are written with xUnit v3 and run against a real SQLite database and a real FusionCache instance, not mocks. Run them with dotnet test.

How a lookup works

This is the part I like most, because it is short:

EfStringLocalizer builds the culture chain, for example it-IT → it → global fallback → invariant.
For each culture, it asks FusionCache for the snapshot of that (resource, culture) pair.
On a cache miss, LocalizationDbContext runs one query that loads all keys of that resource and culture, and caches the result.
The first culture in the chain that contains the key wins.

Two details make a real difference:

Loading the whole resource/culture in one query means you do not hit the database once per string.
Empty cultures are cached too (negative caching). If you have no fr translations, you do not query for fr on every request.

Getting started

Install the package:

dotnet add package TinyLocalization

builder.Services.AddLocalizationDbContext<LocalizationDbContext>(options =>
{
    options.DatabaseType = DatabaseType.SQLite;
    options.ConnectionString = "Data Source=localization.db";
});

builder.Services.AddDefaultFusionCache();

builder.Services.AddDatabaseLocalization(options =>
{
    options.GlobalFallbackCulture = "en";
});

Then configure request localization in your pipeline as you normally would, and use the localizer:

public class HomeController(IStringLocalizer<HomeController> localizer) : Controller
{
    public IActionResult Index()
    {
        ViewData["Title"] = localizer["Welcome"];
        ViewData["Greeting"] = localizer["Hello {0}", User.Identity?.Name ?? "guest"];
        return View();
    }
}

The resource name for IStringLocalizer<T> is the full name of T.

A fair warning about the schema: the library ships no migrations. For a quick start, EnsureCreated() is fine. For production, create migrations in your own project and point the MigrationsAssembly option at them. I preferred this to forcing my migration history into your database.

Managing translations at runtime

Translations are edited through ILocalizationManager, which writes to the database and invalidates the cache in one go:

await manager.AddOrUpdateAsync(new Translation
{
    Resource = "MyApp.Controllers.HomeController",
    Key = "Welcome",
    Culture = "it",
    Value = "Benvenuto"
}, ct);

await manager.RemoveAsync("MyApp.Controllers.HomeController", "Welcome", "it", ct);
await manager.InvalidateResourceAsync("MyApp.Controllers.HomeController", ct);

An empty culture string means the invariant culture. Concurrent inserts of the same translation are resolved as updates, so two admins saving the same key at the same time will not crash anything.

One thing to remember: if you edit rows directly in the database, the application will not see the change until the cache entry expires (10 minutes by default) or you call InvalidateResourceAsync.

Scaling out with Redis

With a single instance, the in-memory cache is enough. With several instances behind a load balancer, you want an edit on node A to reach node B immediately. For that, use AddDistributedFusionCache (or AddDistributedLogsFusionCache if you want control over FusionCache log levels) and set RedisCacheConnectionString and RedisBackplaneConnectionString.

If you need to tell other systems that translations changed, implement ICacheInvalidationPublisher.

Sensible defaults

Everything is configurable, but the defaults are meant to be safe:

Cache duration: 10 minutes
FallbackToParentCultures: enabled
Missing key: returns the key itself (or an empty string if you set ReturnKeyIfNotFound = false)
Fail-safe: enabled, with a 120-minute maximum stale duration, so a database outage does not take your UI strings down with it
Factory timeouts: 100 ms soft, 1500 ms hard
Malformed format strings stored in the database are returned unchanged instead of throwing

That last one comes from experience: a typo in a translated string should never become a 500 error.

What is missing

The project is young, so let me be honest about the gaps:

No admin UI for editing translations. You build your own on top of ILocalizationManager.
No migrations shipped, as explained above.
No import/export tooling from existing .resx files yet.

If one of these matters to you, open an issue. Priorities follow real needs.

Conclusion

TinyLocalization will not replace .resx for every project, and that is fine. If your translations change often, are edited by non-developers, or must be fixed without a deploy, keeping them in a database with a solid cache in front is a very practical option, and you keep the standard .NET localization API.

The project is MIT licensed. If you want to try it, star it, or contribute, fork the repo, branch from develop, add or update tests, and open a pull request against develop.

A special thanks to Jody Donetti, the author of FusionCache. A big part of this library's resilience is his work.

And you, where do you keep your translations: .resx, JSON, or a database?

SagreEventi: an offline-first app for Italian food festivals

Angelo Pirola — Tue, 27 Oct 2026 10:00:00 +0000

October in Italy means chestnuts and new wine. Every weekend there is a sagra (a local food festival) somewhere, but finding them means jumping between town websites, social media groups and word of mouth. That is how SagreEventi was born: a place where people who go to these festivals can report them and browse them, without creating an account.

The code is open source (MIT license): AngeloDotNet/SagreEventi.SQLServer.

In this article I walk through what the app does, the main technical choices and the points where I stopped to think.

What it does

The idea is deliberately simple. Anyone can:

browse events: a home page with the upcoming events hanging from a festival bunting, a searchable catalog and a month-by-month agenda;
filter and sort by free text (accent-insensitive), city and period (in progress, upcoming, finished), in a grid or list view;
report a new event (name, city, dates, description) with a validated form;
take it with them: add the event to their calendar (.ics), open the city on a map, share it.

Users with the Admin or Editor role sign in with email and password (ASP.NET Core Identity, bearer tokens) and can edit existing events and moderate reports. Public registration is disabled: users are created by the seed at start-up.

What it does not do: it does not sell tickets and does not handle bookings. Keeping payments and ticketing out of scope simplified the project a lot.

The stack

API

ASP.NET Core (.NET 10) with Minimal API
Entity Framework Core + SQL Server
ASP.NET Core Identity with roles
Rate limiting, native OpenAPI, FusionCache

Client

Angular 21 (standalone components, signals, zoneless)
PrimeNG 21 with a custom Aura preset, PrimeIcons
Just Angular, PrimeNG and RxJS: no state library, no CSS framework

A note on method: the API is a handful of endpoints, so a new client is a weekend of work. There is a single contract and it can serve several clients. The project started with a Blazor WebAssembly client, which I later removed in favor of Angular + PrimeNG.

Why Angular 21 and not 22?

This choice is worth explaining. The latest PrimeNG release published under the MIT license is 21.1.x, which supports Angular 21. PrimeNG 22 adds Angular 22 support but introduces a license key (with a free Community tier that requires registration). To stay fully free and officially compatible, I pinned the client to Angular 21 and PrimeNG ^21.1.10. Before upgrading, it is worth rereading PrimeTek's current terms.

Moderation: trust reporters a little less

If anyone can add events, you need a filter. Every report has a state: InAttesa (pending, the default for anonymous users), Approvato (approved) or Rifiutato (rejected).

GetEventi returns only approved events.
Neither the client nor the server trusts the state sent by a client: the stato field is output only.
Whoever reports an event sees it as pending on their own device (the «Le mie» section). If the event is rejected, the reporter is not notified: it keeps showing as pending. The rejection reason is a note visible only to Admin and Editor.
Events reported by Admin/Editor are published immediately.
From /gestione/revisione you can approve or reject reports in bulk (up to 100 at a time) and withdraw an event that was already approved.

A detail I like: the API has no DELETE. A withdrawn event becomes a rejected, concluded event, and clients use that to delete their local copy at the next sync. A background service automatically concludes events whose end date has passed (the interval is configurable with Eventi:ScadenzaIntervalloMinuti), and a concluded event can no longer be edited by anyone.

Offline-first and sync

At festivals, especially in the countryside, mobile coverage is often a gamble. That is why the Angular client keeps a local copy of the events (in localStorage) and reconciles it with SQL Server using a three-step protocol:

Push: events created or edited on the device (marked as pending) are sent with PUT /api/Eventi/UpdateEventi.
Pull: changes made by others are fetched with GET /api/Eventi/GetEventi?since=<cursor>, where the cursor is the latest modification time returned by the server.
Merge: server data replaces local data, unless the local copy is pending and newer. Concluded events are removed.

A sync runs at start-up, when the browser comes back online and when you press the button in the top bar, which also shows how many changes are waiting.

An event looks like this (JSON, camelCase):

{
  "id": "0b1e9e8e-5c0f-4a5e-8d0e-6b1a2f6c9a11",
  "nomeEvento": "Sagra della castagna",
  "cittaEvento": "Soriano nel Cimino",
  "dataInizioEvento": "2026-10-24T00:00:00",
  "dataFineEvento": "2026-10-26T00:00:00",
  "descrizioneEvento": "Caldarroste, vino novello e musica dal vivo.",
  "eventoConcluso": false,
  "dataOraUltimaModifica": "2026-10-22T18:30:00.000Z",
  "stato": "Approvato"
}

The server sets dataOraUltimaModifica on every write: the value sent by the client is only used to decide which version is newer.

Security: public APIs, but not defenseless

Anonymous write endpoints call for a few precautions:

Per-IP rate limiting on writes and login, with a maximum of 20 events per request.
Changes to existing events only with an Admin/Editor token: anyone else gets 403. New events in the same request are still inserted.
Length limits on fields (name 200, city 100, description 4000, and so on): longer values get 400.
X-Forwarded-* headers are trusted only from the Docker network, and nginx overwrites X-Forwarded-For, so the per-IP limits cannot be dodged.
CORS limited to the origins listed in Cors:Origins, and a restricted AllowedHosts.

The integration test suite (xUnit with in-memory SQLite) covers events, moderation, users, login, rate limits, forwarded headers, CORS and malicious input.

Docker in one command

docker-compose.yml starts four containers on a private network:

Service	Role
`sqlserver`	SQL Server 2022, data in the `sqldata` volume
`api`	The API on port 8080 (internal only), non-root user, health check on `/healthz`
`web`	The built Angular client, served by an unprivileged nginx
`proxy`	A dedicated nginx: the only public entry point (80/443), terminates HTTPS

The client and the API share one origin, so production needs no CORS and apiBaseUrl stays empty in config.json: a single build runs in every environment.

To try it:

cp .env.example .env     # fill in the variables
# create deploy/certs/fullchain.pem and privkey.pem (a self-signed certificate is fine for a trial)
docker compose up --build

Then open https://localhost and sign in with ADMIN_EMAIL / ADMIN_PASSWORD from the .env file. EF Core migrations run at start-up and the Admin user is created.

A fair warning: the Docker files are written but not yet tried on a real Docker host. The manual checks to run are in the repository's TEST-MANUALI.md file. The compose file is meant for trials and small deployments: for production you need real certificates, a managed or backed-up SQL Server and a secret store instead of .env.

Running it locally (without Docker)

You need the .NET 10 SDK, a SQL Server instance and Node.js (^20.19, ^22.12 or ^24).

git clone https://github.com/AngeloDotNet/SagreEventi.SQLServer.git
cd SagreEventi.SQLServer/src/SagreEventi.Web.Server
dotnet run

The connection string and the first users go in appsettings.local.json (git-ignored). Then the client:

cd src/SagreEventi.Web.Angular
npm install
npm start

Open http://localhost:4200: in development, requests to /api are forwarded to https://localhost:5001, so there is nothing else to configure.

What is missing (and what comes next)

The roadmap is as honest as the rest:

try the Docker stack on a real host and tick off the manual checks;
an installable offline app shell (service worker);
server-side search and pagination once the catalog grows;
automated tests for the Angular client's sync logic (the API already has its own);
geolocation: events near you.

Conclusion

SagreEventi is a small project, but it brings together quite a few concrete topics: public APIs with moderation, offline sync, roles, rate limiting, deployment behind a reverse proxy. If you need inspiration for an app with a .NET API and an Angular client, the repository can be a good starting point.

If the project is useful to you, a ⭐ on GitHub helps others find it. Issues and pull requests are welcome (starting from the develop branch).

And you, how do you handle offline sync in your apps? Let me know in the comments.

Hacktoberfest 2025

Angelo Pirola — Sat, 11 Oct 2025 07:00:00 +0000

Hacktoberfest 2025: One Brick at a Time! I'm thrilled to have helped make open source a better place with Hacktoberfest.

Every pull request, no matter how small, is a step toward a more collaborative and innovative future.

How to easily integrate and extend authentication in ASP.NET Core projects, using ASP.NET Core Identity

Angelo Pirola — Fri, 01 Aug 2025 07:23:02 +0000

A few weeks ago, we ported the project shown in this post to make it more dynamic and easier to implement and maintain.

📢 A new GitHub repository has been created, available here, and still under development/implementation.

⚠️ Important
This library is still under development of new implementations and in the process of creating the related documentation.

🧩 Features

Minimal API: Built using .NET 8 Minimal API for a lightweight and efficient implementation.
Entity Framework Core: Uses EF Core for data access, making it easy to integrate with your existing database.
Modular: The library is designed to be modular, allowing you to add or remove features as needed.
Dynamic: Supports dynamic management of users, roles, claims, forms, licensing and policies.
Flexible Configuration: Easily configurable via appsettings.json to suit your application's needs.
Outbox Pattern: Implement the transactional outbox pattern for reliable email sending.

This allows for modular management of the original library available in this GitHub repository based on the project's needs, without having to configure everything immediately.

Contributions are also welcome.

Please report issues and pull requests on the repository, and don't forget to ⭐ on GitHub if you find this project useful to show your support and help others discover it!

How can dynamically add separate API endpoints

Angelo Pirola — Thu, 05 Jun 2025 05:30:00 +0000

The example in the github repository below shows a simple implementation on how you can add API endpoints (and their dependencies, via dependency injection) by linking external class library projects or adding their Nuget packages (if the class libraries are released as a Nuget package).

GitHub Repository

Comments and/or suggestions are always welcome.

How to connect two microservices with RabbitMQ and Rebus

Angelo Pirola — Mon, 26 May 2025 05:30:00 +0000

The example in the github repository below shows a simple implementation of two microservices (.NET 8 Web Api) communicating with each other via RabbitMQ and Rebus.

GitHub Repository

Comments and/or suggestions are always welcome.

How to manage users, roles, and claims, using jwt token and asp.net core identity

Angelo Pirola — Thu, 06 Mar 2025 06:30:00 +0000

IMPORTANT: We recommend reading the updated article available at this link. Thank you.

After seeing how to protect minimal APIs with JWT tokens and Asp.Net Core Identity, in this article, I want to share a next step, which I found myself facing for personal needs, that is how to make the management of JWT token claims dynamic in order to manage roles, claims, modules and licenses.

To obtain a working example that uses this implementation, I created this project (wrapper extender of ASP.NET Core Identity) that uses a SQL server database and allows this dynamic management.

The implementation explained above is available as a Nuget package, available at this link, while the code is available in this repository, which will be enriched with additional features and documentation in the coming weeks.

The project is constantly evolving. Contributions are welcome. Feel free to file issues and pull requests on the repository and don't forget that if you find this project useful, put a ⭐ on GitHub to show your support and help others discover it!

How to use SignalR in a Blazor WebAssembly and Web API project

Angelo Pirola — Thu, 13 Feb 2025 06:30:00 +0000

This post was born from a personal need during the development of a notification system in a festival management application, which I am currently developing (the source can be found in this repository).

There will be a need to implement a notification service in the client part (frontend), but the notifications will have to be generated automatically by the backend part.

Faced with this need in the short term, I created this example repository, which contains two client projects (client and client2), and a server project (server).

By starting the server and client projects, you can have a demo of signalR generates notifications in a razor page, with the help of Mudblazor these notifications have a different color based on the severity.

In this example, it was chosen to use the "notify-client" endpoints generating the notification in grey and "notify-client-info" generating the notification in light blue.

To generate these notifications you can use swagger of the backend project, testing the endpoints that contain the nomenclature "notify-client"

Instead, by starting the server and client projects, you can have a demo of signalR that generates notifications in a Razor page, with the help of Mudblazor the notifications will all have the same color, in this case gray and in the backend part the endpoint to use will be the one called "notify-client2", alternatively you can use the button on the frontend "Send notification"

If you like my open source works don't forget to "follow me" on GitHub and/or click the repository's starred button.

How to secure minimal api microservices with asp.net core identity

Angelo Pirola — Fri, 03 Jan 2025 13:00:00 +0000

The project "MinimalApi.AuthJWTIdentity" demonstrates how to configure authentication and authorization using .NET Identity and JWT tokens shared between two microservices (web APIs).

Here is a detailed summary of the project:

Overview

Purpose: To provide an example of configuring authentication and authorization using .NET Identity and JWT tokens for two microservices.

Scope: The example includes minimal configuration and excludes advanced features like token refresh, role management, and claims. However, these features can be added with additional configuration.
Project Structure

Microservices:

Microservice01: Contains the Program.cs and appsettings.json files for its configuration.

Microservice02: Similar structure to Microservice01 with its own
Program.cs and appsettings.json.

MicroserviceAuth: Manages authentication and contains the main logic for user registration and login.

Main Files:

README.md: Describes the project and its purpose.

Program.cs of Microservice01: Sets up the microservice, adds authentication and authorization, and defines a secure endpoint.

Program.cs of Microservice02: Similar to Microservice01 with its own setup.

Program.cs of MicroserviceAuth: Manages user registration, login, and JWT token generation.

Configuration Files:

appsettings.json of Microservice01: Contains JWT settings and logging configuration.

appsettings.json of Microservice02: Similar to Microservice01 with its own configuration.

appsettings.json of MicroserviceAuth: Contains JWT settings and logging configuration for the authentication service.

Setup and Configuration

Each microservice has its own Program.cs file that sets up the web application, adds authentication and authorization services, and defines endpoints.

The appsettings.json files in each microservice contain the JWT token settings and logging configuration.

The MicroserviceAuth service handles user registration and login, generating JWT tokens for authenticated users.

Key Components

Authentication and Authorization: Implemented using .NET Identity and JWT tokens.

Microservices: Each microservice has its own setup and configuration, sharing the JWT token settings across the services.

Endpoints: Secure endpoints are defined in each microservice, requiring authentication to access.

This project provides a foundational example of using .NET Identity and JWT for securing microservices, with the potential for extending functionality with additional configuration.

GitHub Repository

Comments and/or suggestions are always welcome.

How to connect two microservices with RabbitMQ

Angelo Pirola — Fri, 27 Dec 2024 06:30:00 +0000

The example in the github repository below shows a simple implementation of two microservices (.NET 8 Web Api) communicating with each other via RabbitMQ queues.

If you want a two-way communication instead, we recommend reading the article example of Microservice Communication with RabbitMQ and MassTransit (click here to read the article)

GitHub Repository

Comments and/or suggestions are always welcome.

How to create a simple appointment calendar

Angelo Pirola — Thu, 19 Dec 2024 06:30:00 +0000

The example in the github repository below shows how to create a simple appointment calendar (currently they are generated hard coded, but there is a comment (to read the comment click here) in case you want to retrieve them from an external API service.

GitHub repository

Comments and/or suggestions are always welcome.

Docker configurations for .NET applications and more

Angelo Pirola — Thu, 12 Dec 2024 06:30:00 +0000

This repository contains Docker configurations, including Docker Compose files and Dockerfiles, to simplify the configuration and deployment of containerized applications.

It provides a consistent and reproducible environment for development, testing, and production. Configurations are designed to be easily customizable and extensible to suit various use cases and application requirements.

GitHub Repository