Runic.Translations
0.13.0
See the version list below for details.
dotnet add package Runic.Translations --version 0.13.0
NuGet\Install-Package Runic.Translations -Version 0.13.0
<PackageReference Include="Runic.Translations" Version="0.13.0" />
<PackageVersion Include="Runic.Translations" Version="0.13.0" />
<PackageReference Include="Runic.Translations" />
paket add Runic.Translations --version 0.13.0
#r "nuget: Runic.Translations, 0.13.0"
#:package Runic.Translations@0.13.0
#addin nuget:?package=Runic.Translations&version=0.13.0
#tool nuget:?package=Runic.Translations&version=0.13.0
Runic.Translations
Run compiled translations in .NET applications with immutable locale snapshots, typed formatting, fallback, and atomic locale switching. The runtime is UI-framework independent, reflection-free, and compatible with NativeAOT.
Install
dotnet add package Runic.Translations --version <VERSION>
Replace <VERSION> with the current version shown on NuGet. The package targets .NET 10. For generated catalogs, install Runic.Translations.Build at the same exact version; it owns the generator, catalog item mapping, and optional non-C# artifacts.
Use a generated catalog
Given the project template's starter catalog with code.className set to AppText, the generator creates registration and typed accessors. text.Messages is the readable surface and names each message by its flattened key, so the starter message application.title is application_title. The encoded r_<hex> members stay available as the stable machine-facing contract. Each encoded segment is r_ followed by the hexadecimal UTF-8 bytes of its NFC-normalized text, and the encoded segments are joined with _.
using Example.Translations;
using Runic.Translations;
ITranslationManager manager = await AppTextCatalog.CreateManagerAsync(
initialLocale: "en");
var text = new AppText(manager);
Console.WriteLine(text.Messages.application_title);
await manager.SetLocaleAsync("de");
Console.WriteLine(text.Messages.application_title);
Each successful locale change replaces the complete immutable snapshot. Reads through manager.Current do not observe a partially updated catalog.
To start in the user's language, pass an ordered preference list, such as the operating system's user languages. The generated SupportedLocales lists the declared locales, and ResolveLocale(IEnumerable<string>) chooses one with the pinned CLDR likely subtags and parent locales: zh-TW matches a declared zh-Hant, de-CH matches de-DE, and nb matches no. CreateManagerFromPreferencesAsync, CreateManagerFromPreferences and ITranslationManager.SetLocaleFromPreferencesAsync take the same list (the one-tag CreateManager(null) and SetLocaleAsync are unchanged), and LocaleNegotiation.Negotiate applies the rules to any set of locales. The generated ESM runtime's negotiateLocale gives the same answer. A single requested tag that the catalog does not declare is matched by the same rules under the default ParentsThenDefault policy, and the snapshot reports how (LocaleResolution).
ITranslationManager manager = await AppTextCatalog.CreateManagerFromPreferencesAsync(["de-CH", "en"]);
Use catalogs from libraries
A library with its own public catalog takes an ITranslationContext, and the application registers every catalog in
one context. SetLocaleAsync prepares every catalog's snapshot and publishes them together:
TranslationContext translations = await TranslationContext.CreateBuilder()
.AddCatalog(AppTextCatalog.Registration)
.AddCatalog(GridTextCatalog.Registration) // a library's generated registration
.AddOverlay(TranslationOverlay.FromPacks("acme.grid", packSource,
addedLocales: [new TranslationOverlayLocale("fr")]))
.BuildAsync(initialLocale: "de");
var text = new AppText(translations); // generated constructor over a context
await translations.SetLocaleAsync("fr"); // every catalog switches together
translations.Catalogs reports, per catalog, the requested locale, the locale used and whether it was resolved
exactly, through a parent (es-419 for es-MX), to a related locale CLDR likely subtags match (de-DE for de-CH)
or to the default (LocaleResolution); translations.SupportedLocales lists the locales every catalog shows, and
SetLocaleFromPreferencesAsync chooses among them for a preference list. The latest SetLocaleAsync call wins over earlier ones still in flight, and contexts built from one
builder share their catalogs' providers, so a context per window or request is cheap. Overlays are checked key by key,
keep working when the library adds messages, and resolve locale-first. The text class now has a second one-parameter
constructor, so register it with a factory rather than by type in a DI container. See Catalogs from libraries and Ship translations in a library.
Right-to-left text
LocaleDirection.Get("ar") returns TextDirection.RightToLeft from pinned CLDR data, the same answer as the ESM
runtime's localeDirection and independent of the operating system's culture data. Text formatted in a right-to-left
locale isolates placeholders with Unicode MessageFormat 2's default bidi strategy (مرحبا {$name} formats as
مرحبا \u2068{name}\u2069), decided per call, so an RTL overlay of an LTR library catalog is isolated too; set
runtime.bidiIsolation to on or off in runic.json to choose, and u:dir on a placeholder to set its direction.
BidiText.RemoveIsolates(text) removes the isolates for plain-text output such as a terminal or a log. See Right-to-left text.
When to choose this package
Choose Runic.Translations for application runtime behavior: generated catalog data, locale resolution, formatting, structured content, translation references, and optional verified external packs. Choose Runic.Translations.Tooling when building an editor, compiler host, or workspace tool.
External packs are untrusted until their artifact version, catalog, locale, contract fingerprint, keys, argument contracts, and limits have been verified. Applications that require authenticity must also supply an integrity verifier; schema validation alone does not establish provenance.
Generated RMF2 catalogs use v5 pack factories and strict version/profile dispatch. A matching fingerprint demonstrates generated-contract compatibility; it is not a signature or authenticity proof. Unsupported artifact, grammar, profile, and ABI versions fail explicitly.
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). Code generated by release N runs on runtime N or later within the same minor before 1.0 (the same major from 1.0), so a library built with one release works in an application on a later runtime of that minor; a runtime older than the generated code fails explicitly (RTR0024). Packed libraries depend on Runic.Translations [N, next minor-0.0) before 1.0, for example [0.9.1, 0.10.0-0.0), and [N, next major-0.0) from 1.0.
Generated code calls the runtime through the Runic.Translations.Generated namespace: the CompiledRmf2* message model, TranslationsCompatibility and GeneratedCatalogSupport. These types are binary compatible for code that an earlier release of the same major generated, but they are not application API: their source may change in a minor, and they are marked [EditorBrowsable(Never)]. TextArgumentFormat.Fixed0–Fixed6/Percent0–Percent4 are likewise hidden. Generated readable surfaces implement IReadableMessages.
Open and closed sets: the markup bindings (InlineLinkBinding, InlineActionBinding, InlineIconBinding) are a closed set, so a switch over them is exhaustive. TranslationPackFailureReason, TranslationReferenceDiagnosticReason and the RMF2 document block names are open: handle a value you do not know.
- Runtime and generated C# example
- NativeAOT example
- RMF2 project guide
- Translate a Runic Views app
- Ship translations in a library
- Ship translation updates without a release
- External translation pack contract
- Issues and support
Licensed under the MIT License. See Third-Party Notices for bundled data attribution.
| 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
- No dependencies.
NuGet packages (4)
Showing the top 4 NuGet packages that depend on Runic.Translations:
| Package | Downloads |
|---|---|
|
Runic.Translations.Hosting
Registers a shared Runic Translations context, its catalogs and overlays with Microsoft.Extensions.DependencyInjection. |
|
|
Runic.Translations.Wpf
WPF inline and document rendering for compiled RMF2 messages. |
|
|
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.15.1 | 1,140 | 11/20/2026 | |
| 0.15.0 | 910 | 11/20/2026 | |
| 0.14.0 | 6,605 | 11/18/2026 | |
| 0.13.0 | 3,329 | 11/16/2026 | |
| 0.12.0 | 1,943 | 11/15/2026 | |
| 0.11.0 | 4,589 | 11/14/2026 | |
| 0.10.0 | 2,159 | 11/13/2026 | |
| 0.9.1 | 3,388 | 11/9/2026 | |
| 0.9.0 | 95 | 11/9/2026 | |
| 0.8.0 | 5,626 | 10/22/2026 | |
| 0.7.0-preview.4 | 517 | 10/17/2026 | |
| 0.7.0-preview.3 | 241 | 10/17/2026 | |
| 0.7.0-preview.2 | 228 | 10/15/2026 | |
| 0.7.0-preview.1 | 176 | 10/14/2026 | |
| 0.6.0-preview.7 | 76 | 10/12/2026 | |
| 0.6.0-preview.5 | 827 | 10/9/2026 | |
| 0.6.0-preview.4 | 376 | 10/8/2026 | |
| 0.6.0-preview.3 | 474 | 10/7/2026 | |
| 0.6.0-preview.2 | 544 | 10/7/2026 |