Runic.Translations 0.11.0

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

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()
    .Add(AppTextCatalog.Registration)
    .Add(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.

Licensed under the MIT License. See Third-Party Notices for bundled data attribution.

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.
  • 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.9.0 is deprecated because it has critical bugs.
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
Loading failed