Runic.Translations.Hosting 0.12.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Runic.Translations.Hosting --version 0.12.0
                    
NuGet\Install-Package Runic.Translations.Hosting -Version 0.12.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="Runic.Translations.Hosting" Version="0.12.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Runic.Translations.Hosting" Version="0.12.0" />
                    
Directory.Packages.props
<PackageReference Include="Runic.Translations.Hosting" />
                    
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 Runic.Translations.Hosting --version 0.12.0
                    
#r "nuget: Runic.Translations.Hosting, 0.12.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 Runic.Translations.Hosting@0.12.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=Runic.Translations.Hosting&version=0.12.0
                    
Install as a Cake Addin
#tool nuget:?package=Runic.Translations.Hosting&version=0.12.0
                    
Install as a Cake Tool

Runic.Translations.Hosting

Register one shared Runic Translations context, its catalogs and overlays with Microsoft.Extensions.DependencyInjection. An application and each library it uses add their catalogs; every catalog switches to one locale together.

Install

dotnet add package Runic.Translations.Hosting --version <VERSION>

Replace <VERSION> with the current version shown on NuGet. The package targets .NET 10 and depends on Runic.Translations and Microsoft.Extensions.DependencyInjection.Abstractions.

Register catalogs

The application passes its options once; each library registers its own catalog in its own registration method, without options. All calls share one set of registrations, and every catalog switches to one locale together:

using Microsoft.Extensions.DependencyInjection;

// The application
services.AddRunicTranslations(options => options.InitialLocale = settings.Language)
    .AddCatalog(AppTextCatalog.Registration, context => new AppText(context));

// A library
public static IServiceCollection AddAcmeGrid(this IServiceCollection services)
{
    services.AddRunicTranslations().AddCatalog(GridTextCatalog.Registration, context => new GridText(context));
    return services;
}

The options belong to the application: the application's InitialLocale applies whichever call runs first, and two calls that set an option to different values throw InvalidOperationException. A library therefore never passes options.

AddCatalog<TText> registers a generated text class over the context, with the context's lifetime. Register a text class once, in the library that owns its catalog: registering it again with another factory throws. Always use this factory overload. Since 0.9 the generated text class has two one-parameter constructors, XText(ITranslationManager) and XText(ITranslationContext), so a type registration such as services.AddSingleton<GridText>() fails with "ambiguous constructors" when the container can supply both. new GridText(null) still compiles and picks the manager constructor.

AddOverlay(TranslationOverlay) attaches application overrides to a library catalog, and AddOverlays several, such as the overlays a build compiles from runic.json overrides (AddOverlays(AppTextCatalog.Overlays)).

Singleton or scoped

Application Lifetime Why
Desktop (WPF, Avalonia, console) Singleton (default) The user picks one language for the whole process.
Web (ASP.NET Core) options.Lifetime = ServiceLifetime.Scoped Each request switches to its user's locale; with a singleton, one request's SetLocaleAsync would switch every concurrent request.
services.AddRunicTranslations(options => options.Lifetime = ServiceLifetime.Scoped);

app.Use(async (http, next) =>
{
    var translations = http.RequestServices.GetRequiredService<ITranslationContext>();
    await translations.SetLocaleAsync(http.Features.Get<IRequestCultureFeature>()!.RequestCulture.UICulture.Name);
    await next();
});

Scoped contexts share their catalogs' providers and composed snapshots, so a context per request costs a snapshot lookup per catalog, not a recomposition. ITranslationContextFactory.CreateAsync(locale) creates further contexts, for example one per window, in either mode.

Overlays and asynchronous initialization

Generated catalogs compose without I/O, so the context is built on first use. Overlay packs load asynchronously; with an overlay, initialize the context once after building the service provider, which keeps every library catalog that was added through AddCatalog:

var app = builder.Build();
await app.Services.InitializeRunicTranslationsAsync();   // loads and checks overlay packs without blocking
app.Run();

Resolving the context before that throws instead of blocking on I/O, which could deadlock a UI thread. Compiled overlays, the build-time overrides of runic.json overrides (AddOverlays(AppTextCatalog.Overlays)), load without I/O and need no initialization. In scoped mode, initialization composes the shared snapshots that every scope's context starts from. Do not build a TranslationContext yourself and register the instance: it would bypass the catalogs that libraries add, and resolving ITranslationContext throws when a catalog added through AddCatalog is missing.

See Catalogs from libraries.

Compatibility and status

This package targets .NET 10. Before 1.0 a minor release may contain breaking changes, each listed with upgrade steps in the release notes (see Versions before 1.0).

Licensed under the MIT License.

Product Compatible and additional computed target framework versions.
.NET 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Runic.Translations.Hosting:

Package Downloads
Runic.Translations.CommandLine

Translates Runic.CommandLine help, errors and faults with Runic Translations, with built-in English and German text.

Runic.Application.Views.Translations

Optional English and German text for Runic's own messages (validation, field errors, error sentences and shortcut labels of the page, dialog titles, error pages, standard menus), as a Runic Translations library catalog that follows the application's locale.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.14.0 0 11/18/2026
0.13.0 834 11/16/2026
0.12.0 744 11/15/2026
0.11.0 1,705 11/14/2026
0.10.0 820 11/13/2026
0.9.1 1,519 11/9/2026