Runic.Translations.Hosting
0.13.0
See the version list below for details.
dotnet add package Runic.Translations.Hosting --version 0.13.0
NuGet\Install-Package Runic.Translations.Hosting -Version 0.13.0
<PackageReference Include="Runic.Translations.Hosting" Version="0.13.0" />
<PackageVersion Include="Runic.Translations.Hosting" Version="0.13.0" />
<PackageReference Include="Runic.Translations.Hosting" />
paket add Runic.Translations.Hosting --version 0.13.0
#r "nuget: Runic.Translations.Hosting, 0.13.0"
#:package Runic.Translations.Hosting@0.13.0
#addin nuget:?package=Runic.Translations.Hosting&version=0.13.0
#tool nuget:?package=Runic.Translations.Hosting&version=0.13.0
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.
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 | Versions 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. |
-
net10.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.14)
- Runic.Translations (>= 0.13.0 && < 0.14.0-0.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Runic.Translations.Hosting:
| Package | Downloads |
|---|---|
|
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. |
|
|
Runic.Translations.CommandLine
Translates Runic.CommandLine help, errors and faults with Runic Translations, with built-in English and German text. |
GitHub repositories
This package is not used by any popular GitHub repositories.