FluentLocalizer.Extensions.DependencyInjection 1.1.0

dotnet add package FluentLocalizer.Extensions.DependencyInjection --version 1.1.0
                    
NuGet\Install-Package FluentLocalizer.Extensions.DependencyInjection -Version 1.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FluentLocalizer.Extensions.DependencyInjection" Version="1.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="FluentLocalizer.Extensions.DependencyInjection" Version="1.1.0" />
                    
Directory.Packages.props
<PackageReference Include="FluentLocalizer.Extensions.DependencyInjection" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add FluentLocalizer.Extensions.DependencyInjection --version 1.1.0
                    
#r "nuget: FluentLocalizer.Extensions.DependencyInjection, 1.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package FluentLocalizer.Extensions.DependencyInjection@1.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=FluentLocalizer.Extensions.DependencyInjection&version=1.1.0
                    
Install as a Cake Addin
#tool nuget:?package=FluentLocalizer.Extensions.DependencyInjection&version=1.1.0
                    
Install as a Cake Tool

FluentLocalizer.Extensions.DependencyInjection

Version 1.1.0 adds a native net11.0 target alongside netstandard2.0, net8.0 and net10.0. Public APIs are unchanged; building this repository requires the .NET 11 SDK.

FluentLocalizer.Extensions.DependencyInjection provides ASP.NET Core and generic .NET hosting integration for FluentLocalizer. It registers ITranslator and related services in IServiceCollection, so you can consume translations from your application with minimal setup.

Install

For every public type and member in this package, see the API reference. The online guide covers ASP.NET Core, worker services and Blazor.

dotnet add package FluentLocalizer.Extensions.DependencyInjection

The JSON store examples also require FluentLocalizer.Store.Json:

dotnet add package FluentLocalizer.Store.Json

Basic registration

using FluentLocalizer;
using FluentLocalizer.Store.Json;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddLogging(); // required by WithLogger() outside a host

services.AddFluentLocalizer(options =>
{
    options.MissingKeyBehavior = MissingTranslationBehavior.ReturnConfiguredValue;
    options.MissingKeyFallbackValue = "[{key}]";
})
    .WithStore(new JsonFileStore(new JsonFileStoreOptions
    {
        ResourcesPath = "Locales",
        FallbackCulture = "en-US"
    }))
    .WithLogger();

var provider = services.BuildServiceProvider();
var translator = provider.GetRequiredService<ITranslator>();

var message = translator.Get("Welcome")
    .WithArg("name", "Ada")
    .Resolve();

Culture selection

You normally don't call WithCulture(...). translator.Get(key) uses CultureInfo.CurrentUICulture, the culture of your user interface, both to look up the template and to format it, with Resolve() and ResolveAsync() alike. Set the UI culture where your application decides the user's language, and every request follows it:

using System.Globalization;

var culture = CultureInfo.GetCultureInfo("it-IT");
CultureInfo.CurrentUICulture = culture; // Translation lookup and message formatting.
CultureInfo.CurrentCulture = culture;   // Standard .NET number/date formatting elsewhere in the app.

var message = translator.Get("Welcome").WithArg("name", "Ada").Resolve(); // Italian

WithCulture(...) exists only to force a culture that differs from the UI culture for one message, such as an email written in the recipient's language or a page that shows the same text in several languages:

var subject = translator.Get("Email:Subject").WithCulture(recipientCulture).Resolve();

It affects that request only and never changes CurrentUICulture or CurrentCulture. If you pass the same culture to every request, set CurrentUICulture instead: repeating WithCulture(...) hides the real culture of the application and ignores later language changes.

Get(key) captures the culture when it creates the builder, so create a new builder after changing it. Components that cache rendered text need their own update or rerender. On modern .NET, the ambient culture flows through task-based asynchronous operations.

For application-wide thread defaults, set CultureInfo.DefaultThreadCurrentUICulture and CultureInfo.DefaultThreadCurrentCulture at startup; these do not override explicitly set thread cultures. In ASP.NET Core, app.UseRequestLocalization(...) sets both cultures for each request, so Get(key) already follows the user's language; don't change the process-wide defaults per user.

See Microsoft's CurrentUICulture and CurrentCulture documentation.

Hosted service / worker example

If you are building a hosted service, worker, or background processor, you can register the translator once and inject it into your service class.

using FluentLocalizer;
using FluentLocalizer.Store.Json;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFluentLocalizer()
    .WithStore(new JsonFileStore(new JsonFileStoreOptions
    {
        ResourcesPath = "Locales",
        FallbackCulture = "en-US",
        ThrowOnMissingStore = true
    }));

builder.Services.AddHostedService<NotificationWorker>();

await builder.Build().RunAsync();

public sealed class NotificationWorker(ITranslator translator) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var message = translator
            .Get("Notifications:MessageCount")
            .WithArg("quantity", 3)
            .Resolve();

        Console.WriteLine(message);
        await Task.CompletedTask;
    }
}

This pattern is useful when the translator is reused across several services and you want the store configuration centralized in the host setup.

What gets registered

AddFluentLocalizer(...) registers an ITranslator implementation that is created from:

  • the ITranslationStore you provide
  • TranslationOptions from DI configuration
  • an optional ITranslationLogger

This makes the translator available throughout your app via dependency injection.

Service Lifetime Registered by
ITranslator Singleton, created on first resolution AddFluentLocalizer
IOptions<TranslationOptions> Singleton AddFluentLocalizer (AddOptions + Configure, or Options.Create for the instance overload)
ITranslationStore Singleton WithStore
ITranslationLogger Singleton adapter to ILogger<Translator> WithLogger (optional)
  • AddFluentLocalizer lives in the Microsoft.Extensions.DependencyInjection namespace; the returned FluentLocalizerBuilder is in FluentLocalizer.Core, which you only import to name the type.
  • Resolving ITranslator without a registered store throws InvalidOperationException. Registering ITranslationStore or ITranslationLogger yourself is equivalent to WithStore/WithLogger.
  • Call AddFluentLocalizer once per container: a second call adds another ITranslator registration and the last one wins.
  • WithStore(instance): the caller owns and disposes the store. WithStore(factory): the container creates it lazily and disposes it (JsonFileStore, HttpJsonStore) when the provider is disposed.
  • The callback overload combines with other Configure<TranslationOptions> calls (including configuration binding of the simple properties). The instance overload registers that exact object; other Configure calls are ignored. Either way the options are read once, when the singleton translator is created.
  • WithLogger() requires ILogger<Translator>: hosts register logging, a bare ServiceCollection needs AddLogging(). The category is FluentLocalizer.Translator; levels map one-to-one to LogLevel.

Using a custom store factory

If you prefer to resolve the store from the service provider, you can register it lazily:

services.AddFluentLocalizer()
    .WithStore(sp => new JsonFileStore(new JsonFileStoreOptions
    {
        ResourcesPath = "Locales",
        FallbackCulture = "en-US"
    }));

Configuring options from DI

You can also configure TranslationOptions with the standard IOptions pattern:

services.AddFluentLocalizer(options =>
{
    options.DefaultArguments = new Dictionary<string, object?>
    {
        ["name"] = "Ada"
    };
});

Logging

To enable logging integration, call WithLogger(); it registers an adapter that bridges FluentLocalizer's ITranslationLogger to the standard .NET ILogger abstraction. This makes the integration compatible with the logging systems you already use in your application, including Serilog, Console, Debug, and other ILogger-based providers.

services.AddFluentLocalizer()
    .WithLogger();

In practice, this means you can keep using your existing logging pipeline and benefit from FluentLocalizer diagnostics without introducing a separate logging model.

Notes

This package is intentionally lightweight. It wires FluentLocalizer and your chosen store implementation into dependency injection containers.

API reference

Public types and members declared by FluentLocalizer, grouped by package and namespace. Includes constructors, overloads, properties, enum values, inherited library members and deprecated APIs. Standard inherited .NET members are omitted.

Version numbers shown for a type or member refer to the NuGet package named on that type.

Signatures use C# notation; parameter names, defaults, return values and relevant exceptions are described alongside each member. Every type states the version that introduced it; later additions and deprecations are marked on each member, and the changes between versions are listed in the changelog. The searchable WebUI API reference uses the same catalog and can show any earlier version; the changelog lists the changes of every release.

<a id="api-fluentlocalizerservicecollectionextensions"></a>

FluentLocalizerServiceCollectionExtensions

Kind: static class · Package: FluentLocalizer.Extensions.DependencyInjection · Namespace: Microsoft.Extensions.DependencyInjection · Since: 0.0.1

Static extension methods registering FluentLocalizer in IServiceCollection.

Registers ITranslator as a singleton. Register ITranslationStore before resolving the translator. WithLogger is optional; without a registered ITranslationLogger, translation logging is disabled.

Member Parameters, return value and behavior
static FluentLocalizerBuilder AddFluentLocalizer(this IServiceCollection services, Action<TranslationOptions>? configure = null) services is the DI collection and cannot be null (ArgumentNullException). configure optionally configures IOptions<TranslationOptions>. Returns a FluentLocalizerBuilder for store/logger registration.
static FluentLocalizerBuilder AddFluentLocalizer(this IServiceCollection services, TranslationOptions translationOptions) Registers the supplied translationOptions instance through IOptions and adds the translator. Returns a builder. Null services or translationOptions throw ArgumentNullException. Use a typed argument when passing null to avoid overload ambiguity.

Source

<a id="api-fluentlocalizerbuilder"></a>

FluentLocalizerBuilder

Kind: sealed class · Package: FluentLocalizer.Extensions.DependencyInjection · Namespace: FluentLocalizer.Core · Since: 0.0.1

Mutable registration builder returned by AddFluentLocalizer.

Despite its namespace, this type belongs to the dependency injection package. WithStore and WithLogger return the same builder. ILoggerAdapter is internal and is not part of the public API.

Member Parameters, return value and behavior
FluentLocalizerBuilder(IServiceCollection services) Wraps services for further registration. Normally created by AddFluentLocalizer; constructing it directly does not register ITranslator.
IServiceCollection Services { get; } The service collection supplied to the constructor; can be used for additional application registrations.
FluentLocalizerBuilder WithStore(ITranslationStore store) Registers store as a singleton ITranslationStore. A null store throws ArgumentNullException. The caller owns an externally created disposable instance.
FluentLocalizerBuilder WithStore(Func<IServiceProvider, ITranslationStore> factory) Registers a singleton store factory. factory receives the service provider on resolution. A null factory throws ArgumentNullException. The DI container owns disposable stores created by the factory.
FluentLocalizerBuilder WithLogger() Registers a singleton ITranslationLogger adapter using ILogger<Translator>. Configure Microsoft.Extensions.Logging services and providers so ILogger<Translator> can be resolved.

Source

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.0 80 11/16/2026
1.0.0 114 10/2/2026
0.1.0-alpha 102 9/30/2026
0.0.1 143 7/30/2026

Add a native .NET 11 target while retaining .NET Standard 2.0, .NET 8 and .NET 10 support. Public APIs and translation behavior are unchanged.