Repository navigation
Releases
v0.15.1
Runic Translations 0.15.1
Install matching 0.15.1 packages from NuGet and npm: the eight NuGet packages
(Runic.Translations, .Build, .CommandLine, .Hosting, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
0.15.1 is a patch release of 0.15.0 with one fix to how external and overlay packs
are loaded. It changes no API. .NET applications get the fix by updating the
packages; code generated with 0.15.0 runs on the 0.15.1 runtime unchanged. Generated
ESM output carries its own runtime, so regenerate it with the 0.15.1 compiler (a
build with the 0.15.1 Vite plugin or dotnet-runic-translations does that).
Fixes
- Loading an external or overlay pack compares its markup contract with the catalog's entry by entry, in .NET and in
generated ESM, without writing out the version 2 form of a version 3 contract. Its time and memory now grow with the
size of the pack and the catalog. A version 3 contract must list canonical locales in ordinal order, as many as the
catalog's version 3 contract does. A pack that does not meet these rules, or that fails to load for any other
reason, is refused withTranslationPackException(ArgumentContractMismatchorMalformed) in .NET or an
RTR0023result in ESM, so the application's fallback runs. Upgrade if your application loads packs it did not
build itself; generated ESM output carries the runtime, so regenerate it with this release.
What's Changed
- After 0.15.0: ship the public API, baseline 0.15.0, next 0.16.0 by @ViktorJannicke in #301
- SDK release notes start at the previous SDK tag, never an editor tag (#278) by @ViktorJannicke in #299
- Release note for #278: the example names v0.15.0 for 0.16.0 by @ViktorJannicke in #302
- Bound contract expansion when loading a pack by @ViktorJannicke in #303
- Translations 0.15.1: release by @ViktorJannicke in #304
Full Changelog: v0.15.0...v0.15.1
v0.15.0
Runic Translations 0.15.0
Install matching 0.15.0 packages from NuGet and npm: the eight NuGet packages
(Runic.Translations, .Build, .CommandLine, .Hosting, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
0.15.0 is the Translations step of the 0.23 release train (Runic Command Line
0.14.0, then Translations 0.15.0, then the Runic SDK 0.23.0).
Runic.Translations.CommandLine 0.15.0 needs Runic Command Line 0.14.
This release makes generated .NET catalogs smaller and faster to load, keeps
the compiler and the language server fast in catalogs of 20,000 messages, and
shows in the Translations Editor what changed in the source of a stale
translation. It removes two paths that 0.14 deprecated: messages in your own
catalog that override command-line framework text, and language server protocol
revision 1. Packs for applications released before 0.15 now need --contract.
Until 1.0 a new minor may contain breaking changes. See
Upgrading from 0.14 and
Versions before 1.0.
Highlights
- Smaller generated .NET catalogs that load faster. Generated C# embeds
each locale as binary data and the message table as DEFLATE data (RMF2 runtime
ABI 5): for the Translations Editor's 1,000 messages in two locales the
embedded data shrinks from 79.7 to 46.1 bytes per message, a locale is ready
about 5 times sooner, and a message is built only when it is first formatted.
Accessors share one body per input type, so a NativeAOT executable grows by
about 130 bytes per message instead of 198. Rebuild to get it; the 0.15
runtime still runs code generated by 0.13 and 0.14
(details). - Fast in large catalogs. At 20,000 messages in 10 locales,
runic-translations validatetakes about 3.5 s instead of 50 s. The language
server validates a burst of edits once, in the background, and after an edit
compiles only what changed (about a quarter of a second for one translation
file), so hover and completion answer while you type. CI now holds the
language server to budgets on such a catalog
(fixes). - What changed in a stale translation's source. The Translations Editor
shows the source a translation was approved for next to the current one, with
the changes marked.review mark,xliff import, the editor and the language
server record that text in a new<catalog>.review-sources.jsonbeside the
review file, whose format is unchanged. The CLI also takes dotted message keys
(common.cancel)
(details). - Packages declare the catalog's languages. A Runic Desktop application
withoutRunicApplicationLocalesgets the languages of itsrunic.json, so
dotnet runic packagedeclares them in macOS, MSIX and Linux packages
(details).
Dotted message keys in the CLI (#225)
A message has one name for people: its logical key, the dotted path of its groups and name (common.cancel), as
validate and the editor show it. review mark --key now takes it as well as the canonical key that generated code
and the review file use (common_cancel). Both name the same message (RTR0018 keeps them unambiguous), and the
review file keeps storing the canonical key. A key that names no message is reported with the closest logical key
(Did you mean 'common.cancel'?), here and in overrides add --key and the compile server's message and
set-message.
The Translations Editor's bridge contract adds, without changing existing members, the logical path of each message
(EditorMessageEntry.path, ["common", "cancel"]) and of the message a diagnostic belongs to
(EditorDiagnostic.messagePath), for a namespace tree in the message list.
What changed in the source of a stale review (#225)
When a source message changes after its translation was approved, the Translations Editor now shows what changed: the
workflow panel of the stale translation shows the source it was approved for ("Source when marked") next to the
current one, with removed words struck through, added words highlighted and placeholders as chips, beside Confirm
translation and Mark needs review.
The text comes from a new companion of the review file, <catalog>.review-sources.json
(runic.translations.review-sources/1, schema review-sources-v1.schema.json, packed with Runic.Translations.Tooling
and written by runic-translations schema). review mark, xliff import, the editor and the language server's
Mark … reviewed record the MF2 source text of each entry they write there: one text per message key and source
fingerprint, shared by all locales. xliff import records the source the XLIFF file was translated from, also when it
has changed since the export. Texts no entry refers to are dropped on the next write.
<catalog>.review.json keeps the runic.translations.interchange-review/2 format unchanged, because the 0.14 readers
refuse unknown members and schemas; 0.14 and 0.15 tools keep working on the same files. An entry recorded without a
text (by an older tool) shows the stale hint without the comparison.
The editor's bridge contract adds, without changing existing members, EditorReviewSnapshot.recordedSources (the
recorded text of each stale entry, by key and source fingerprint).
Runic packages declare the catalog's languages (#264)
When a Runic Desktop application does not set RunicApplicationLocales, Runic.Translations.Build adds the languages
of its runic.json as RunicApplicationLocale items: baseLocale first, as the development language, then
locales, without pseudoLocales. dotnet runic package then declares them in the macOS, MSIX and Linux packages,
and the macOS development bundle of dotnet run lists them in CFBundleLocalizations, so macOS shows its own text in
the user's language without the languages being listed twice. The items are added during evaluation, which is how
dotnet runic package reads the project. A project that sets the property keeps its value, the project's own items
still give a language its name and description, several runic.json files add their languages in order, and
RunicTranslationsFillApplicationLocales set to false turns this off.
Smaller generated .NET catalogs that load faster (RMF2 runtime ABI 5)
Generated C# embeds each locale in a compact binary encoding instead of JSON, and the message table as DEFLATE data
(RMF2 runtime ABI 5, D077.16). For the Translations Editor's 1,000 messages in two locales the embedded catalog data
shrinks from 79.7 to 46.1 bytes per message; a NativeAOT executable no longer links the JSON reader for generated data
(about 34 KB less) and grows by about 130 bytes per message instead of 143. A locale is ready about 5 times sooner on
first use (the editor's English: 1.6 ms → 0.31 ms), and each message is built only when it is first formatted, so a
message that is never shown keeps about 40 bytes instead of about 490 (the editor: 330 KB less memory after first use,
at about 0.15 µs on each message's first format).
Rebuild to get it: Runic.Translations 0.15 runs catalogs generated for RMF2 ABI 3, 4 and 5, so libraries built with
0.13 or 0.14 keep working, and Runic.Translations.Build 0.15 still generates ABI 4 for a project that references a 0.14
runtime. The binary encoding is specified byte for byte in
RMF2 execution profile v2;
packs and ESM output stay JSON.
Upgrading from 0.14
Update every Runic Translations package, NuGet and npm, to 0.15.0 together, and
Runic Command Line to 0.14.
- Runic Command Line 0.14.
Runic.Translations.CommandLine0.15 pairs with
Runic.CommandLine 0.14: its package depends onRunic.CommandLine
[0.14.0, 0.15.0-0.0), so update both together; 0.14.x of the adapter stays
on Command Line 0.13 (#243). Command Line 0.14 retires thefaults.RCLI4001
key: theRCLI4001fault (a prompt that cannot be asked) always shows its
diagnostics.prompt-*text, so every framework key now has a message in the
built-in English and German catalogs. To change that text, override
diagnostics.promptRequiresTerminal,diagnostics.promptJsonOutputand
diagnostics.promptDisabled(inputprompt) in
translations/overrides/runic-command-line/<locale>.rmf2, and delete a
faults.RCLI4001message. Its strict JSON reader (CommandJsonEnvelopeReader
and theRunic.CommandLine.Testinghelpers built on it) now rejects a frame
with a duplicate member name anywhere, also inside members it does not know,
withduplicate-property; write each member name once per object. See the
Command Line 0.14 release notes. - Breaking: a message in your own catalog no longer overrides command-line
framework text. 0.14 deprecated this second override path; 0.15 removes it.
TranslationCommandTextResolverasks your application's catalog only for your
own keys (DescriptionKeytext), so a message named after a
runic-command-linekey, such ashelp { usage = Synopsis }, has no effect,
and the built-in framework text is shown. The resolver no longer writes its
trace warning. WarningRTR0107now says tha...
v0.14.0
Runic Translations 0.14.0
Install matching 0.14.0 packages from NuGet and npm: the eight NuGet packages
(Runic.Translations, .Build, .CommandLine, .Hosting, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
0.14.0 is released on its own, without a release train.
Runic.Translations.CommandLine 0.14.0 needs Runic Command Line 0.13, as
0.13.0 did.
This release brings the language server's refactorings to every LSP editor and
makes Translations much smaller in a NativeAOT executable. It also fixes paths
on Windows, keeps pseudo-locales out of locale fallback, and lets the
Translations Editor publish for Windows and macOS from any machine.
Until 1.0 a new minor may contain breaking changes. See
Upgrading from 0.13 and
Versions before 1.0.
Highlights
- Refactorings in every LSP editor. With
"runicProtocol": 2in its
initializationOptions, a client gets F2 rename of MF2 inputs, slots and
resources, Extract Group and Inline Resource as code actions, and command
edits the server applies itself, without client code of their own: in Neovim,
Helix, JetBrains IDEs with LSP4IJ and Visual Studio 2026's LSP client. Without
the opt-in the server behaves as in 0.13
(details). - Smaller NativeAOT executables. On linux-x64 a console application with
the editor's catalog (872 messages in English and German) shrinks from
4.39 MB to 3.17 MB: Hot Reload no longer links reflection, locale data is
compressed, and a message adds about 200 bytes instead of 550. The markup
contract is compressed too, and overlays are linked only when the
application creates one
(details). - CLDR data as data, and an opt-in subset. The CLDR locale tables and
plural rules are compact data instead of code, about 80 KB less in a NativeAOT
executable.<RunicTranslationsCldrSubset>true</RunicTranslationsCldrSubset>
embeds only the CLDR data of the catalog's languages instead of the full 52 KB
(details). - Fixes. A pseudo-locale is chosen only by its own tag, so a Debug build no
longer formatsen-XAtext foren-US(#212). On Windows the Vite plugin
updates an edited message in place again (#210), and the tools attribute each
resource file to the right one of severalsourceRoots. The Translations
Editor publishes for Windows and macOS from Linux, without its smoke test
(details).
Refactorings through standard LSP in the language server (#204)
runic-translations lsp now offers its refactorings through the standard
LSP features every editor has, after a client opts in to the Runic protocol
revision 2 with initializationOptions.runicProtocol: 2
(#205,
#206):
- F2 renames MF2 caller inputs and slot references in every locale's
resource, as well as resources and locals, withprepareRenameshowing the
current name. In a workspace with application sources, a resource rename asks
whether to rename in resource sources only, instead of refusing; Runic still
does not update call sites. - Extract Group and Inline Resource are
refactor.extractand
refactor.inlinecode actions: "Extract group 'shop' to shop/en.rmf2" on a
group's name, and one "Inline into ../en.rmf2" per ancestor resource of the
same locale. - The
runic.*refactoring commands apply their edits through
workspace/applyEdit. - The server registers its file watchers with clients that support it, reports
its version inserverInfo, and answers unknown requests withMethodNotFound
and failed ones withRequestFailed.
So Neovim, Helix, JetBrains IDEs with LSP4IJ and the next Visual Studio
extension get the refactorings without client code of their own. The
language server guide
lists protocol 2 and has setups for these editors. Without the opt-in the server
behaves as in 0.13, so editor extensions from runic-editors 0.21 keep working;
0.15 is planned to remove that behaviour.
Smaller NativeAOT executables (#216, #217, #218)
Translations adds much less to a trimmed or NativeAOT executable. On linux-x64, the editor's catalog (872 messages in
English and German) in a console application shrinks from 4.39 MB to 3.17 MB:
- Hot Reload no longer links reflection (#216). The Hot Reload check (
MetadataUpdater.IsSupported) is now a
constant in a trimmed publish, so the trimmer removes the catalog tracking and the reflection it used: about 350 KB.
A Debug build anddotnet watchstill apply edited catalog text in place, as before. The runtime's argument checks
no longer callEnum.IsDefined. - Locale data is compressed (#217). A generated catalog embeds each locale's messages as DEFLATE data, about a
tenth of the size (the editor's catalog: 505 KB to 37 KB), and inflates a locale once, on its first use. On the
editor's 256 KB English locale this adds about 0.8 ms and a transient 300 KB buffer to the first access. - Messages are data, not code (#218). A generated catalog describes its messages' keys and inputs in one message
table that the runtime reads in a loop, and each accessor calls one shared formatting body. A message adds about
200 bytes to the executable instead of 550 (the editor's catalog: 389 KB less). On the editor's catalog the first
provider and the first key access take about 0.1 ms longer together.
tests/aot-size measures a NativeAOT probe with a generated catalog, and CI checks its size budgets.
Smaller CLDR data in NativeAOT executables (#219)
- CLDR tables and plural rules are data (D072.2). The runtime's pinned CLDR locale tables and plural rules were
compiled to about 70 KB of code. They are now compact data that the runtime decodes on first use, and plural rules
are interpreted from bytecode. The results are identical for every CLDR locale and plural category. A NativeAOT
executable shrinks by about 80 KB. The first use costs about 50 µs more once, and a plural selection about 45 ns. - Opt in to your catalog's CLDR data only (D072.6). Set
<RunicTranslationsCldrSubset>true</RunicTranslationsCldrSubset>
in an application that never adds a locale of another language at run time. The build then embeds only the CLDR
number, date, list and relative-time data of the catalog's languages, and a trimmed or NativeAOT publish drops the
full 52 KB. A locale outside the subset, such as one a pack adds, formats as a locale without CLDR data, with lists
and relative times in CLDR root's language-neutral patterns (a, b, c,-1 d). It is reported once (Runic-Translationsevent 4).
RunicTranslationsCldrLocaleitems add locales. The default is unchanged. See theRunic.Translations.BuildREADME.
Upgrading from 0.13
Update every Runic Translations package, NuGet and npm, to 0.14.0 together.
Runic Command Line stays at 0.13.
- Generated catalogs need the 0.14 runtime. C# that
Runic.Translations.Build
0.14 generates againstRunic.Translations0.14 requires RMF2 runtime ABI 4,
and fails withNotSupportedExceptionon an earlier runtime: reference both
packages at the same version. The 0.14 runtime still runs the ABI 3 code that
0.13 generated, so libraries packed with 0.13 keep working on it
(details). - Libraries packed with
Runic.Translations.Build0.13 depend on
Runic.Translations[0.13.0, 0.14.0-0.0), so an application on the 0.14.0
runtime gets NuGet warningNU1608. Pack a library update with 0.14.0, as for
every Runic Translations minor (see
Versions). - Language server clients opt in to protocol 2. A client that sends
"runicProtocol": 2ininitializationOptionsgets the standard rename and
code actions; one that doesn't, such as the editor extensions from
runic-editors 0.21, gets the 0.13 behaviour. 0.15 is planned to remove it, so
move custom clients to protocol 2 during 0.14
(language server guide). - Deprecated: framework text from your own catalog in Runic.Translations.CommandLine.
A message in your application's catalog named after arunic-command-line
key, such ashelp { usage = Synopsis }, still overrides that command-line
text in 0.14, but the build now reports it as warningRTR0107, and
TranslationCommandTextResolverwrites a trace warning once when it uses
one. Runic Translations 0.15 removes this second override path: the resolver
then asks your catalog only for your own keys (DescriptionKeytext), and
the framework text returns. To migrate, move each such message, unchanged,
totranslations/overrides/runic-command-line/<locale>.rmf2, add
{ "catalog": "runic-command-line", "from": "Runic.Translations.CommandLine" }
tooverridesinrunic.json, and registerAppTextCatalog.Overlayswith a
context-based resolver (new TranslationCommandTextResolver(context, AppTextCatalog.CatalogId),
theTranslationContextBuilderconstructor, orAddRunicCommandLineTranslations());
the snapshot and manager constructors ignore overlays. The build then che...
v0.13.0
Runic Translations 0.13.0
Install matching 0.13.0 packages from NuGet and npm: the eight NuGet packages
(Runic.Translations, .Build, .CommandLine, .Hosting, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
0.13.0 is the Translations release of the 0.21 release train: Runic Translations
0.13.0, then Runic SDK 0.21.0, then the editor extensions from runic-editors
0.21.0. Runic Command Line is not part of this train:
Runic.Translations.CommandLine 0.13.0 needs Runic Command Line 0.13, as
0.12.0 did. Translations 0.13.0 and Runic SDK 0.21.0 were restored, built and
run together with warnings as errors before either was published.
This is a small release ahead of 1.0. It hardens in-page translation editing on
the dev server, and it applies the API review for 0.13: three names change, so
code and scripts that use them need an edit. It adds no features.
Until 1.0 a new minor may contain breaking changes. See
Upgrading from 0.12 and
Versions before 1.0.
Highlights
- In-page editing is harder to reach from elsewhere. With
server.allowedHosts: truethe dev server's editing API checksHostitself,
and on Linux it accepts a write only from the user running the dev server
(details). - Three renames from the API review:
TranslationContextBuilder.AddCatalog,
runic-translations xliff import --inputandRUNIC_DEV_ALLOWas the only
name of the editing allow list (details).
Upgrading from 0.12
Update every Runic Translations package, NuGet and npm, to 0.13.0 together.
Runic Command Line stays at 0.13.
- Libraries packed with
Runic.Translations.Build0.12 depend on
Runic.Translations[0.12.0, 0.13.0-0.0), so an application on the 0.13.0
runtime gets NuGet warningNU1608. Pack a library update with 0.13.0, as for
every Runic Translations minor (see
Versions).
Breaking changes
-
Runic.Translations:TranslationContextBuilder.Add(registration, options)is
nowTranslationContextBuilder.AddCatalog(registration, options), the name that
IRunicTranslationsBuilder.AddCatalogofRunic.Translations.Hostingalready
has for the same operation. Replace.Add(with.AddCatalog(where a
TranslationContext.CreateBuilder()chain registers a catalog; the arguments
and the behaviour are unchanged. Code compiled against 0.12 fails with
MissingMethodExceptionuntil it is rebuilt. -
@runic-artifex/vite-plugin-runic-translationsno longer reads
RUNIC_TRANSLATIONS_EDIT_ALLOW, the former name of the in-page editing API's
allow list. SetRUNIC_DEV_ALLOWinstead, which takes the same entries and
which vite-plugin-runic also reads for Runic Inspect. When the old variable is
set, the dev server logs a warning and ignores it. -
runic-translations xliff importtakes the XLIFF document with--input <path>
instead of--source <path>, which read like a filter on the source-language
text next to--source-changed.--sourcestill works as a hidden alias until
2.0; giving both is an invocation error (exit code 2).
Behaviour and output changes
@runic-artifex/vite-plugin-runic-translations: withserver.allowedHosts: true, the in-page editing API checksHostitself and answers only IP
addresses,localhostand allow-listed host names. On Linux, a write from
loopback is accepted only when the client belongs to the user running the dev
server; macOS and Windows log that they cannot tell local users apart. Reads,
allowed remote clients and the existing write guards are unchanged.
Release engineering
- The Svelte and SvelteKit packages and the translations editor build with
@sveltejs/adapter-static4.0.1, which fixes GHSA-jf9x-2fg2-hx4w. It is a
development dependency only: the published packages don't depend on it, and
the advisory concerns route config generated for Vercel.
What's Changed
- Post-release 0.12.0: validate against 0.12.0, next candidate 0.13.0 by @ViktorJannicke in #192
- Pin the train gate to runic-sdk main after runic-sdk#1036 by @ViktorJannicke in #193
- adapter-static 4.0.1 (GHSA-jf9x-2fg2-hx4w) by @ViktorJannicke in #194
- vite-plugin-runic-translations: Host check and server-user writes for in-page editing by @ViktorJannicke in #195
- API review for 0.13: AddCatalog, xliff import --input, drop RUNIC_TRANSLATIONS_EDIT_ALLOW by @ViktorJannicke in #196
- Translations 0.13.0: in-page editing hardening and API-review renames (0.21 train) by @ViktorJannicke in #197
- Pin the train gate to runic-sdk main after #1074 (0.21 train) by @ViktorJannicke in #198
- Pin the train gate to runic-sdk#1075 (0.21 train) by @ViktorJannicke in #199
Full Changelog: v0.12.0...v0.13.0
v0.12.0
Runic Translations 0.12.0
Install matching 0.12.0 packages from NuGet and npm: the eight NuGet packages
(Runic.Translations, .Build, .CommandLine, .Hosting, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
0.12.0 is the Translations release of the 0.20 release train: Runic Translations
0.12.0, then Runic SDK 0.20.0, then the editor extensions from runic-editors
0.20.0. Runic Command Line is not part of this train:
Runic.Translations.CommandLine 0.12.0 needs Runic Command Line 0.13, as
0.11.0 did. Translations 0.12.0 and Runic SDK 0.20.0 were restored, built and
run together with warnings as errors before either was published.
This release is about working on translations in the running page. Under
vite dev an edited message now updates in place instead of reloading the
page, a page can read and write a message through the dev server, and an
inspector can tell which message an element shows; Runic SDK 0.20's Runic
Inspect uses all three to edit translations on the page. Go to Definition on
m.key() opens the message's source, and the VS Code and Visual Studio
extensions now release from runic-editors.
Until 1.0 a new minor may contain breaking changes. This release removes no
API; it changes how the dev server handles edits. See
Upgrading from 0.11 and
Versions before 1.0.
Highlights
- Edited messages update in place under
vite dev, keeping the page's
state; changes that need it still reload, with the reason logged
(details). - A write API for in-page translation editing on the dev server: read a
message in every locale and write one locale's text back, source-preserving
and loopback only by default
(details). - Message markers tell an inspector which message an element on the page
shows (details). - Go to Definition from
m.key()opens the message in the base locale's
source file, through a declaration map and with no extension
(details). - The editor extensions release from
runic-editors; Translations
releases no longer carry.vsixfiles
(details).
Edited messages update in place during development
(#176)
Under vite dev, @runic-artifex/vite-plugin-runic-translations no longer
reloads the page when a message's text changes. It compares each regeneration
with the previous one:
- Text edits update in place: a message's text in any locale, a plural or
selector variant, text inside inline markup or a document, and the
pseudo-locales. The browser fetches only the edited messages' modules, which
hand their new text to the modules the page already holds; the runtime, the
catalog's resolvers and installed overlays stay, and so does the page's state.
The SSR environment gets the same update. This includes the application's
overrides of library catalogs regenerated withdependencies: "auto". - The page formats again through a new global text-change channel,
globalThis[Symbol.for("runic.translations.text")]
({ version: 1, revision, listeners }), documented in
the ESM guide.
useMessageLocalefrom@runic-artifex/translations-sveltefollows it, so
Svelte and SvelteKit applications without runic-sdk update in place; runic-sdk's
text helpers follow it from their next release. The shared locale channel is
unchanged. - Everything else reloads, with the reason logged: added, removed or renamed
messages, changed inputs, markup or content kinds, added or removed source
files and runic.json changes, for example
[runic-translations] page reload: messages were added, removed or renamed in catalog 'app'.
The plugin now sends the reload itself, once per environment. - A page that follows no text changes reloads, as before, rather than
showing stale text. - A compile error keeps the last good text under Vite's error overlay; the
next good save updates in place. - Rapid saves of one or several files are compiled in turn and the last one
always wins, including a save that Vite's watcher drops because it follows
another within 50 ms. - Manifest mode (a
dotnet buildthat owns generation) gets the same
comparison, so edits it regenerates update in place too.
The dev server no longer watches the generated .d.ts files, which the plugin
writes only when their content changes. Framework plugins that reload on every
.d.ts change, such as Analog's, no longer turn each message edit into a reload.
Production builds are unchanged: vite build produces the same bytes as with
0.11.0 for the same inputs, and the generated ESM is the same.
A write API for in-page translation editing
(#178)
Under vite dev, @runic-artifex/vite-plugin-runic-translations offers
/__runic-translations/message, so a page can edit a translation in place:
runic-sdk's Runic Inspect selects a text, shows its message in every locale and
writes the edit back.
GETreads a message of the application's catalog, or of a library
catalog regenerated withdependencies: "auto", in every locale: its text as
authored, its inputs and plural or selector variants, where each locale
defines it, and the SHA-256 of the file a write changes.POSTwrites one locale's whole message text (plural, selector, markup
and document messages as their whole source). It is compiled with the rest of
the catalog first and refused with its diagnostics (422) when it does not
compile; a file that changed since it was read is refused (409) with the
current message. The page then updates in place, as on a save.- Source-preserving: the write goes through
runic-translations serve,
which gainsmessageandset-messagerequests, and the Translations Editor's
writer, so only the message's text changes and the file keeps its formatting,
comments, line endings and order. A locale without the message gets it
inserted beside the base locale's. - Library catalogs: a write goes to the application's override,
translations/overrides/<catalog>/<locale>.rmf2, by the rules of
runic-translations overrides add --key(with its review entry, and listing the
catalog in runic.jsonoverrideswhen needed); the installed package is never
written. - On by default, loopback only: the API exists only on the dev server and
accepts same-origin requests from the same machine.inPageEditing: { allow: [...] }or theRUNIC_DEV_ALLOWenvironment variable admit other hosts and
networks (addresses, IPv4/IPv6 CIDR such as a Tailscale network, host names).
RUNIC_DEV_ALLOWis the same setting vite-plugin-runic 0.20 reads for Runic
Inspect, so one variable covers both plugins;RUNIC_TRANSLATIONS_EDIT_ALLOW
is accepted too;
inPageEditing: falseturns it off. Vite's host check still applies. Production
builds are byte for byte the same with or without it.
See "In-page editing API" in the plugin's README and
In-page translation editing.
Go to Definition from m.key() to the message's source
(#177)
generate --emit-esm writes a declaration map, messages.d.ts.map, beside
messages.d.ts. Go to Definition on m.key(), or on an input name in its
argument object, now opens the message's entry in the base locale's .rmf2 or
.mf2 file at the line of its key, in any editor whose TypeScript support
follows declaration maps (VS Code and Visual Studio through tsserver), with no
extension. Before, it stopped in messages.d.ts.
- The map points at the entry whose text the base locale uses. In a library
catalog that the Vite plugin regenerates withdependencies: "auto", an
overridden key opens the application's override file and every other key the
library's packed source. @runic-artifex/vite-plugin-runic-translationswrites the matching
virtual.d.ts.mapanddependencies/<catalog>.d.ts.map, so imports from
virtual:runic-translations/<catalog>navigate the same way.- The JavaScript output is unchanged.
messages.d.tsgains one
//# sourceMappingURLline. The map'ssourcesare relative paths, and
web-module-manifest-v3.jsondoes not list the map, so plugins that predate
it still load the catalog.
See Editor navigation.
The editor extensions release from runic-editors
(#181)
The VS Code and Visual Studio 2026 extensions moved, with their history, to
Runic-Artifex/runic-editors,
which builds, tests and releases them on its own. The VS Code extension there is
becoming one Runic extension for Translations and the Runic SDK
(runic-editors#2).
- Translations releases no longer carry
.vsixassets. From 0.12.0 the
GitHub release has the NuGet and npm packages an...
v0.11.0
Runic Translations 0.11.0
Install matching 0.11.0 packages from NuGet and npm: the eight NuGet packages
(Runic.Translations, .Build, .CommandLine, .Hosting, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
0.11.0 is the Translations release of the 0.19 release train: Runic Command Line
0.13.0, then Runic Translations 0.11.0, then Runic SDK 0.19.0. The three were
restored, built and run together with warnings as errors before any of them was
published. Runic.Translations.CommandLine 0.11.0 needs Runic Command Line
0.13, and Runic SDK 0.19's Runic.Application.Views.Translations needs
Runic Translations 0.11.
Until 1.0 a new minor may contain breaking changes; this release has the ones in
Upgrading from 0.10. See
Versions before 1.0.
Command-line text for Runic Command Line 0.13
The adapter supports exactly one Command Line minor, now 0.13: it depends on
Runic.CommandLine [0.13.0, 0.14.0-0.0), and compiles the
runic-command-line catalog that Command Line 0.13.0 packs. Command Line 0.13
adds and removes no framework text key and changes no English or German
template, so the adapter's text is the same as in 0.10. What changes is what
the framework passes into that text and which notes help shows:
-
Arguments are named by their placeholder
(runic-cli-sdk#98).
The missing-argument error names the argument as the usage line does, by its
ValueNameor else its name in angle brackets, and help lists arguments the
same way:Das Argument <Container-Pfad> fehlt. Aufruf: tool /link <Richtlinie> <Container-Pfad> [Optionen] Weitere Informationen erhalten Sie mit "tool /link /?".The German template
Das Argument {$argument} fehlt.is unchanged; before,
the same error readDas Argument container-path fehlt.. -
Related options are named by their spelling. The
[requires: …]and
[conflicts: …]notes name the option as the app's syntax spells it:
[erfordert: /factor]and[schließt aus: /l]with the Windows slash syntax,
[erfordert: --factor]and[schließt aus: -l]with the portable one, instead
of the option IDs (factor,list). -
Flags show no default
(runic-cli-sdk#99).
An option that takes no value has no[Standard: False]note any more. Value
options keep theirs ([Standard: 1.5]). -
Extended help through a key
(runic-cli-sdk#97).
[Command]and[CommandGroup]takeLongDescriptionKey, resolved like
DescriptionKeythrough the application's catalog, withLongDescriptionas
the fallback. The keycommands.store-show-detailsis the message
commands.storeShowDetails; its paragraphs and indented lines are kept.
CommandTextContext.ValidateDescriptionKeysreports an unresolved one as
RCLI0023, as it does forDescriptionKey. -
JSON diagnostics carry the binding ID (
RCLI1005and other usage errors
about one argument or option). Theirargumentshold the placeholder
(["<Container-Pfad>"]), themessageis translated as before, and the new
bindingmember holds the stable ID ("container-path"), which no value name,
syntax or culture changes.
The tests of Runic.Translations.CommandLine check each of these in German.
Tool
dotnet-runic-translations runs on Runic Command Line 0.13. Its help lists
arguments by their placeholder, as its usage line does: runic-translations locale add --help shows <tag> under Arguments: instead of tag. Its options
declared no flag defaults and no requires or conflicts, so nothing else in its
help changes.
Upgrading from 0.10
- Command-line apps that use
Runic.Translations.CommandLine: update
Runic.CommandLine(and.Spectre,.Processes,.Testing) to 0.13
together with every Runic Translations package to 0.11.0. With Command Line
0.12 the adapter no longer restores withoutNU1608. - Tests that compare German or English CLI output see the rendered text
change:Das Argument <name> fehlt.instead ofDas Argument name fehlt., the
placeholders underArgumente:, the option spellings in[erfordert: …]and
[schließt aus: …], and no default note for flags. - Scripts that read the argument ID from a JSON diagnostic's
arguments
readbindinginstead;argumentsnow holds the placeholder. - Overrides of
runic-command-lineneed no change: no message changed its
inputs.
Release engineering
- CI builds against Runic Command Line 0.13.0 through the train feed
(eng/train-feed.mjs) until it is published; such a run is not publishable.
What's Changed
- Post-release 0.10.0: ship API baselines, validate against 0.10.0 by @ViktorJannicke in #172
- Translations 0.11.0: Command Line 0.13.0 adapter (0.19 train) by @ViktorJannicke in #173
- Pin the train gate to runic-sdk main after #937 (0.19 train) by @ViktorJannicke in #174
Full Changelog: v0.10.0...v0.11.0
v0.10.0
Runic Translations 0.10.0
Install matching 0.10.0 packages from NuGet and npm: the eight NuGet packages
(Runic.Translations, .Build, .CommandLine, .Hosting, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
0.10.0 is the Translations release of the 0.18 release train: Runic Command Line
0.12.0, then Runic Translations 0.10.0, then Runic SDK 0.18.0. The three were
restored, built and run together with warnings as errors before any of them was
published. Runic.Translations.CommandLine 0.10.0 needs Runic Command Line
0.12, and Runic SDK 0.18's Runic.Application.Views.Translations needs
Runic Translations 0.10.
Until 1.0 a new minor may contain breaking changes; this release has the ones in
Upgrading from 0.9. See
Versions before 1.0.
German command-line text for Runic Command Line 0.12 (#168)
Runic.Translations.CommandLine 0.9.1 required Runic Command Line
[0.9.1, 0.10.0). With Command Line 0.10 or 0.11, restore reported NU1608
(an error with warnings as errors, also in test projects), and the usage hint
that Command Line 0.10 added ("Run "tool greet --help" for more information.")
stayed English. 0.10.0 fixes both:
-
Lockstep with Command Line. The adapter supports exactly one Command Line
minor, now 0.12: it depends onRunic.CommandLine[0.12.0, 0.13.0-0.0).
Every Command Line minor is followed in the same train by a Translations
release for it, and patches add no keys. Both the adapter's README and this
repository's README carry the version table.Runic.Translations.CommandLine Runic.CommandLine 0.10.x 0.12.x 0.9.x 0.9.x -
The text comes from Command Line. Runic Command Line 0.12 packs the
runic-command-linecatalog sources (runic.json,en.rmf2,de.rmf2) and
its key listtext-keys.jsonundertranslations/, and its own CI checks
that every key has English and German. The adapter compiles exactly the text
of the Command Line release it is built against and reads each key's
argument names from that release'sCommandTextKeys, so a key and its German
cannot drift apart. Its own copy of the text and of the argument table is
gone. -
Every Command Line 0.12 key has English and German, including the usage
hint (hints.usage), the help link (hints.help-link), the redaction notes
(redaction.*), the empty command line (diagnostics.missing-command), the
exit-codes heading (help.exit-codes) and the process faults
(faults.RCLI6001tofaults.RCLI6011).faults.RCLI4001keeps the more
specificdiagnostics.prompt-*text, as before. A test compares the compiled
catalog withtext-keys.json, key for key. -
German wording follows Command Line 0.12. The usage errors name what they
are about, for exampleDie Option '--bogus' ist unbekannt.instead of
Unbekannte Option. (--bogus). Since Command Line 0.10 a usage error in human
output has noRCLIcode prefix (--format jsoncarries it) and ends with the
usage line and the hint:Die Option '--unknown' ist unbekannt. Aufruf: localized greet <name> [Optionen] Weitere Informationen erhalten Sie mit "localized greet --help". -
AddRunicCommandLineTranslations(applicationCatalogId)(new, in
Runic.Translations.CommandLinethroughRunic.Translations.Hosting) adds
runic-command-lineto the application's shared context and registers an
ICommandTextResolverover it, so oneSetLocaleAsyncswitches the
application's text and the command line's together, with the context's
overrides applied. The adapter package now depends on
Runic.Translations.Hostingand, through it, on
Microsoft.Extensions.DependencyInjection.Abstractions. -
A locale the framework text lacks is reported. When the application's text
has the requested language andrunic-command-linedoes not, the resolver
writes onewarning:line to standard error and a trace warning, as
runic-viewslogs event 1261. An override file
(translations/overrides/runic-command-line/<locale>.rmf2) adds the locale. -
Lead with a context. The READMEs now lead with
new TranslationCommandTextResolver(context, AppTextCatalog.CatalogId). The
snapshot and manager constructors use the built-in text without the
context's overlays, so a build-time override ofrunic-command-lineis
ignored there; they are unchanged.
Framework text
is a new guide: both framework catalogs (runic-command-line and Runic SDK's
runic-views), how to register and override them, what stays English, a test
self-check, and the German style guide and glossary.
Dependency ranges
- Hosting and Wpf are bounded to the Translations minor.
Runic.Translations.HostingandRunic.Translations.Wpfdepended on any
Runic.Translationsfrom their own version up, so an application could update
Runic.Translationsto a new minor and keep an older Hosting without a
warning. They now depend on[0.10.0, 0.11.0-0.0), as
Runic.Translations.CommandLineand every library packed with
Runic.Translations.Builddo; a mismatch isNU1608at restore. - One bound form. Every dependency on a package released in lockstep
(Runic.Translations,Runic.Translations.Hosting,Runic.CommandLine) is
[F, next minor-0.0)before 1.0 and[F, next major-0.0)from 1.0. The
Command Line range is no longer written by hand: the same pack step that bounds
Runic.Translationsderives it from the tested version, and the pre-push
manifest check rejects any other form.
Tool
dotnet-runic-translations --version, theservehandshake and SARIF reports
(tool.driver.version) carry the package version, such as0.10.0. They said
0.2in every earlier release.- The tool runs on Runic Command Line 0.12. Its usage errors in human output
have no code prefix any more;--format jsonstill carries every
RTR/RTRSUPcode.
Translations Editor
The editor (not part of the packages) is built on Runic SDK 0.17.1, NuGet and npm,
with CsWebUi and CsWebUi.Native [2.5.0-beta.4.9, 3.0.0), the floor of
Runic SDK 0.17.1's CS-WebUI host; its exact 2.5.0-beta.4.8 pin was a
downgrade there (NU1605). Its tool manifest names dotnet-runic-translations
0.10.0, and a test keeps it at the release version.
Upgrading from 0.9
- Command-line apps that use
Runic.Translations.CommandLine: update
Runic.CommandLine(and.Spectre,.Processes) to 0.12 together with
every Runic Translations package to 0.10.0. With Command Line 0.9 the adapter
no longer restores. - Overrides of
runic-command-line: some messages changed their inputs with
Command Line 0.12 (for examplediagnostics.unknownCommandnow takes
$command, anddiagnostics.invalidChoiceHiddentakes$help). The build
checks every override against the packed catalog and reports an override that
no longer fits (RTR0016/RTR0065), or names a removed key (RTR0103). - Tests that compare German or English CLI output see the new wording and
the usage line and hint after each usage error. - Applications that reference
Runic.Translations.Hostingor
Runic.Translations.WpfupdateRunic.Translationsto the same minor; a
0.9 runtime under a 0.10 Hosting isNU1608.
Release engineering
- CI builds against the Command Line release of the train before it is
published (the train feed,eng/train-feed.mjs); such a run uploads a
train-feedartifact, and Publish preview refuses it. - Publish preview runs the train compatibility gate (row P-tr of runic-sdk's
train-compat.yml) against exactly the packages it publishes, and publishes
only when it passes.
What's Changed
- Post-release 0.9.1: ship API baselines, validate against 0.9.1 by @ViktorJannicke in #167
- Translations 0.10.0: Translations.CommandLine for Command Line 0.12 (TR1) by @ViktorJannicke in #169
- Pin the train gate to runic-sdk main after #889 and #893 by @ViktorJannicke in #170
- Lock files: Command Line 0.12.0 as published on nuget.org by @ViktorJannicke in #171
Full Changelog: v0.9.1...v0.10.0
v0.9.1
Runic Translations 0.9.1
Important
Use 0.9.1, not 0.9.0. 0.9.0 was published only partially: Runic.Translations
0.9.0 and Runic.Translations.Build 0.9.0 reached nuget.org, and then nuget.org
rejected Runic.Translations.CommandLine 0.9.0, so no other package, npm package,
tag or GitHub release of 0.9.0 exists. A library packed with
Runic.Translations.Build 0.9.0 depends on Runic.Translations [N, 0.10.0-0),
an upper bound nuget.org rejects ("The package manifest contains an invalid
Version"), so such a library cannot be pushed to nuget.org. Reference 0.9.1 of
every package and pack libraries with Runic.Translations.Build 0.9.1. 0.9.1 is
the first complete release of the 0.9 feature set below.
Install matching 0.9.1 packages from NuGet and npm: the eight NuGet packages
(Runic.Translations, .Build, .CommandLine, .Hosting, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
Runic.Translations.Hosting is new in this release. Tested with Runic Command
Line 0.9.1 (security fixes); Runic.Translations.CommandLine requires the
tested minor, [0.9.1, 0.10).
0.9.1 covers the gaps in 0.8. Libraries can ship their own text, and an
application overrides single strings, adds locales and switches one locale for
every catalog, in .NET and on the web. Plurals, ordinals, lists and relative
time support every CLDR locale. Locale negotiation follows CLDR. Dates use the
local time zone. Numbers follow the regional locale and its native digits.
:currency, :unit and compact notation are new, and right-to-left text is
isolated. Translators get XLIFF profile 3 with placeholders and plurals, a
review file, QA warnings, coverage reports, .resx and i18next importers, and
pseudo-locales. The ESM m object is tree-shakable.
0.9.1 changes formatted output and behaviour in several places. Read
Upgrading from 0.8 before updating. Each pull request's
description and the PublicAPI files list the changes in full. Until 1.0 a new
minor may contain breaking changes, and this release still has some; output
changes are allowed until the first 1.0.0-rc.N. See
Versions before 1.0.
Fixed since 0.9.0
- Dependency range that nuget.org accepts.
Runic.Translations.Buildnow
writes the upper bound-0.0([N, next minor-0.0)before 1.0,[N, next major-0.0)from 1.0) instead of-0. nuget.org accepts a prerelease label that
starts with a digit only in a SemVer 2.0 version, so it rejected every package
carrying 0.9.0's0.10.0-0bound,Runic.Translations.CommandLine0.9.0
included.-0.0still sorts below every prerelease of the next breaking release
that nuget.org can host, so the range keeps those previews out as before. - Release check. Package verification in CI and the publish workflow, also its
dry run, now apply nuget.org's version rules to every.nupkgand.snupkg,
including libraries packed with the candidateRunic.Translations.Build, and
stop before the first push when a package or dependency version would be
rejected.
Upgrading from 0.8
Update every Translations package, the npm packages and the
dotnet-runic-translations tool to 0.9.1 together, then rebuild. If you already
updated Runic.Translations or Runic.Translations.Build to 0.9.0, update them to
0.9.1 as well and pack your libraries again. The build
regenerates catalog code, and a web build regenerates its output folder. Generated
ESM message modules now import formatMessage from runtime.js, so regenerate
the whole output folder and never mix files from two releases
(#143).
Formatted output changes
Formatted strings change for existing messages. Snapshot tests of formatted text
and stored formatted strings need updating.
- Dates and times. Localized
:datetimestyles use the local time zone
instead of UTC. Date and time styles have the same CLDR length in .NET and ESM:
short dates show the full year,longdates have no weekday, and times show no
zone name. UsetimeZone=utcto keep UTC
(#130). - Percentages use the locale's percent pattern, so German writes
50 %
(#130). - Regional formatting. Numbers, percentages and dates follow the requested
regional locale (de-CH,en-GB) when it has the same language and script as
the text. A user who requestsde-CHand getsdetext sees Swiss numbers and
dates. Unicode extensions of the requested tag are ignored, except-u-nu. A tag
that spells out the default script (de-Latn-CH,en-Latn-US) formats with its
region's conventions
(#130,
#148). - Native digits. Numbers, percentages, dates, times and relative time use the
locale's CLDR default digits: Bengali১২,৩৪,৫৬৭.৫, Persian۵۰٪, Arabic (Egypt)
٤/١١/٢٠٢٦. Request a tag with-u-nu-latn(ar-EG-u-nu-latn) for Latin
digits.{$n :integer useGrouping=never}also writes the locale's digits and
minus sign (Persian−۱۲۳۴, Swedish−1234). Use:stringfor codes that
must stay ASCII
(#148). - Pinned number data. Number symbols, grouping and percent patterns come from
pinned CLDR 48.2 data in both runtimes. They no longer vary with the platform's
ICU or withInvariantGlobalization. Negative zero is written without a sign.
es-419/es-MX/es-AR,pt-PTandru-UAuse their own CLDR
minimumGroupingDigits
(#131,
#148). - .NET full dates use CLDR's weekday case (Latvian
trešdiena, Mongolian,
Turkmen, …) andzh-TW's day periods (凌晨,晚上), as the web runtime does.
With ICU 78 or later, the .NETsv-AXmedium date is4.11.2026, as on the web.
Older ICU, including Windows and distribution libicu 72–77, still writes
4 nov. 2026
(#148). - Relative time follows CLDR fully. Patterns are chosen per plural category
and by past or future, and the number uses the locale's separators and digits.
For example,in 1.5 Tagenbecomesin 1,5 Tagen,in 1000 daysbecomes
in 1,000 days, andin 1.0 daysbecomesin 1 day.numeric=autoprints
words for ±2 and for every unit, not onlyday("the day before yesterday",
"next month")
(#131,
#148). - Right-to-left isolation. Catalogs that declare a right-to-left locale
isolate placeholders with MessageFormat 2's default bidi strategy. Formatted
strings now contain the invisible characters FSI, LRI or RLI before a
placeholder and PDI after it. The English fallback for an Arabic request is also
isolated. English text in anen/arcatalog is not. Choose the behaviour with
runtime.bidiIsolation(default,on,off) inrunic.json. Remove the
characters for comparisons with the newRemoveIsolateshelpers. LTR-only
catalogs don't change
(#146). - XLIFF export writes profile 3, so exported files differ from 0.8. See
Translator workflow below
(#134).
Locale negotiation
resolveLocaleandSetLocaleAsyncwithParentsThenDefaultmatch through
CLDR likely subtags and parent locales. A tag that fell back to the default
locale in 0.8 may now match a declared locale:zh-TWresolves tozh-Hant,
de-CHtode-DE(reported as the newLocaleResolution.Related),nb,nnand
noto each other, and legacy codes such asiw,tl,moandshto their
replacements
(#131).- Closer matches win. When a catalog declares a locale that is closer than
the truncated tag, that locale is chosen. For example,zh-TWpickszh-Hant
when the catalog declares bothzhandzh-Hant. Ties are broken along the
request's CLDR parent chain (en-US-posix→en-US)
(#131). - Same-script rule. Removing subtags no longer reaches a locale of another
script.zh-TWwith onlyzhdeclared, orsr-Latn-RSwith onlysr, now
gets the default locale or the next preference
(#131). - POSIX tags such as
de_DEare accepted and normalised, andundis
ignored (#131). - Preference lists use their own
*FromPreferencesmethods.
SetLocaleFromPreferencesAsync(manager and context) and the generated
CreateManagerFromPreferences/CreateManagerFromPreferencesAsynctake an
ordered list. They are not overloads ofSetLocaleAsyncorCreateManager,
which still take one tag, because an overload resolved differently for C# 12
callers.negotiateLocale(preferences)(ESM),LocaleNegotiationand the
generatedSupportedLocalesandResolveLocale(IEnumerable<string>)(.NET) are
new ([#131](https://github.com/Runic-Artifex/run...
v0.8.0
Runic Translations 0.8.0
Install matching 0.8.0 packages from NuGet and npm: the seven NuGet packages
(Runic.Translations, .Build, .CommandLine, .Tooling, .Wpf,
.Templates and the dotnet-runic-translations tool) and the three npm
packages (@runic-artifex/vite-plugin-runic-translations,
@runic-artifex/translations-svelte and @runic-artifex/translations-sveltekit).
Tested with Runic Command Line 0.9.0.
0.8.0 is the first plain version: Runic Translations no longer uses
-preview.N suffixes. Until 1.0 a new minor may contain breaking changes, each
listed here with its upgrade steps, and a patch only fixes or adds. Releases are
still previews, marked as GitHub prereleases. 1.0.0 will be preceded by
1.0.0-rc.N releases. See
Versions before 1.0
and Versioning and support from 1.0.
This release settles the API for 1.0. Runic.Translations.Tooling becomes a
stable package with a smaller public surface: the command plumbing, workspace
transactions, MF2 syntax tree and language service are internal. Generated-code
support moves to Runic.Translations.Generated. The MSBuild names get a
Runic prefix, and old names fail with RTR0086. The npm packages require
Vite 8.3.3 and Svelte 5.57.1, accept Node 26 and have one import path per
export. runic-translations selects its output with --format, uses the Runic
exit codes and its own diagnostic codes, and reads @file response files
through Runic Command Line 0.9.0. JSON schemas now describe its payloads. See
Upgrading, Behaviour changes and
Security.
Upgrading
Update every Translations package and the dotnet-runic-translations tool to
0.8.0 together: Runic.Translations.Build reads the tool's new exit codes (see
Command-line tools). Rebuild after updating; the build
regenerates catalog code into the new generated-code namespace. Package
validation, the PublicAPI files and each pull request's description list the
changes in full; the tables below cover what application code usually touches.
Build properties and build errors
- Every MSBuild property, item and metadata name of
Runic.Translations.Build
starts withRunic. A project that still sets an old name fails with
RTR0086,
which names the replacement
(#110). TranslationsEmitTypeScript,TranslationsEmitTemplateManifestand
TranslationsEmitCppare removed: they selected emitters that do not exist.
Setting one fails withRTR0086
(#110).- MSBuild errors carry their code (
RTR0020,RTR0002,RTR0086) as the
error code instead of in the message text
(#110). Runic.Translations.Buildtreats tool exit code 2, not 1, as translation
diagnostics. A Build package from an earlier release run with the 0.8.0 tool
still fails the build on translation errors, but adds a generic "exited with
code 2" error
(#104).
| Before | After |
|---|---|
TranslationsGenerateOnBuild, TranslationsEmitJson, TranslationsEmitEsm |
RunicTranslationsGenerateOnBuild, RunicTranslationsEmitJson, RunicTranslationsEmitEsm |
TranslationsOutputPath, TranslationsOutputStamp, TranslationsWebOutputPath |
RunicTranslationsOutputPath, RunicTranslationsOutputStamp, RunicTranslationsWebOutputPath |
TranslationsToolCommand, TranslationsToolAdditionalArguments |
RunicTranslationsToolCommand, RunicTranslationsToolAdditionalArguments |
TranslationsXamlCatalog, TranslationsXamlReferencedCatalogs, TranslationsValidateXaml (property and item metadata) |
RunicTranslationsXamlCatalog, RunicTranslationsXamlReferencedCatalogs, RunicTranslationsValidateXaml |
Items TranslationProject, TranslationMf2, TranslationXaml, TranslationsToolInput |
RunicTranslationProject, RunicTranslationMf2, RunicTranslationXaml, RunicTranslationsToolInput |
Output items @(TranslationsGeneratedFile) |
@(RunicTranslationsGeneratedFile) |
RunicTranslationsBuildPropsImported, RunicTranslationsBuildTargetsImported |
_RunicTranslationsBuildPropsImported, _RunicTranslationsBuildTargetsImported (internal) |
TranslationsEmitTypeScript, TranslationsEmitTemplateManifest, TranslationsEmitCpp |
Removed; delete them (RTR0086) |
RTR0020: … in the message text, no code |
Error code RTR0020 (also RTR0002, RTR0086) |
Runtime and generated code
- Generated-code support moved to
Runic.Translations.Generated
(CompiledRmf2*,TranslationsCompatibilityand the new
GeneratedCatalogSupportwith the factories generated catalogs call). It is
hidden from IntelliSense and stays binary compatible for code an earlier
release of the same major generated, but it is not application API.
Regenerate after upgrading; the build does this
(#109). - Generated readable surfaces implement the new
IReadableMessages
(#109). ITranslationManager.SnapshotPublishedreplacesITranslationSnapshotNotifier.
Custom managers raise it for locale switches and refreshes
(#109).TranslationPackExceptioncarries itsReasonandRejectionId
(RTR0023/<reason>) and the constantDiagnosticId; the
TranslationPackFailurehelpers for a pack exception are removed
(#109).- Transport writers emit version 2 only, in .NET and in generated ESM.
Version 1 stays readable
(#109). MarkupBindingandInlineMarkupBindingare a closed set: they cannot be
derived from outside the package
(#109).- The RMF2 document block set (
runic:p,runic:h,runic:ul,runic:ol,
runic:li) is open: a later minor may add blocks. Custom document or WPF
markup factories must handle an unknown block name by failing or falling back;
the built-in renderers fail closed
(#106). Rmf2MarkupContract.DeclaresMarkup(name)reports whether a linked contract
declares a markup name, such as a customshop:badge, so an adapter can check
its custom factories against the contract it was given (additive,
#113).
| Before | After |
|---|---|
Runic.Translations.CompiledRmf2*, Runic.Translations.TranslationsCompatibility |
Runic.Translations.Generated.CompiledRmf2*, Runic.Translations.Generated.TranslationsCompatibility (regenerate) |
CompiledTranslationDefinition.FromRmf2Inputs, CompiledTranslationLocale.CreateDeferred/ReadRmf2Values, TextArgument.CreateRmf2, TranslationPackContract.CreateRmf2V5, TranslationPackMessageContract.FromRmf2Inputs |
GeneratedCatalogSupport.CreateDefinition, CreateDeferredLocale/ReadValues, CreateArgument, CreatePackContract, CreatePackMessageContract |
TranslationsCompatibility.MessageGrammarVersion |
Removed (unused; the pack grammar is 5) |
new CompiledTextMessage(…), new CompiledTextMessageNode(…), new CompiledTextMessageVariant(…); TextPatternFormatter, TextMessageSelector, TextRelativeTimeFormatter |
Internal; build v5 messages with CompiledRmf2Message and CompiledTextMessage.FromRmf2 |
TranslationReference.CreateVersion1(…) |
Removed; write version 2 with the constructor (upgrade receivers first) |
Generated ESM createTextReference(key, inputs, { version: 1 }) |
Removed (throws RangeError); write version 2 |
TranslationPackFailure.GetReason(packException), GetRejectionId(e), GetDiagnosticId(e), TranslationPackFailure.DiagnosticId, RejectionIdPrefix |
e.Reason, e.RejectionId, TranslationPackException.DiagnosticId; TranslationPackFailure.GetReason(Exception) is unchanged |
class MyBinding : InlineMarkupBinding |
Not allowed (closed set) |
ITranslationSnapshotNotifier.SnapshotPublished |
ITranslationManager.SnapshotPublished (custom managers implement it) |
TranslationTransport.Version (const) |
Static property, same value |
renderer.ToPlainText(content, allowActionLabels: true) |
renderer.ToPlainText(content, new Rmf2PlainTextOptions { AllowActionLabels = true }) |
options.MissingKey = … after construction |
new TranslationOptions { MissingKey = … } (init-only) |
diagnostic.Reason == "unknown-key" |
diagnostic.Reason == TranslationReferenceDiagnosticReason.UnknownKey (open enum, Unknown = 0) |
| A custom block factory that assumes the five built-in blocks | Handle an unknown block name: the block set is open |
WPF
TranslationSourcetakes the generatedIReadableMessagesinstead of
object, so passingtextinstead oftext.Messagesno longer compiles. It
followsITranslationManager.SnapshotPublishedonly, so a custom manager no
longer needsInvalidate()after a refresh
(#109).WpfInlineRendererandWpfDocumentRendereraccept an already linked
Rmf2MarkupContract, so an app with an inline and a document renderer links
its catalog's cont...
v0.7.0-preview.4
Runic Translations 0.7.0-preview.4
Behaviour changes
:integerand:numbernow group digits by default, as Unicode
MessageFormat 2 andIntl.NumberFormatdo.{$n :integer}with 1234 used to
format as1234in every locale; it is now1,234in English and1.234in
German, and{$h :number}with 12345.5 is12,345.5instead of12345.5.
To keep the old output, writeuseGrouping=never
({$n :integer useGrouping=never}), which also keeps an integer's
invariant-1234. Rebuild C# and regenerate ESM output to pick up the change
(#98).useGroupingis available on:integerand:numberwith the MF2 values
auto(default),always,neverandmin2.autogroups by the content
locale's CLDRminimumGroupingDigits, now part of the pinned CLDR 48.2
subset: Spanish and Italian keep1234and group12.345, the other
supported locale families group1,234.min2groups only from five
digits,alwaysfrom four. The .NET and ESM runtimes apply the same rule; a
new cross-runtime corpus,rmf2-grouping-conformance.json, checks them
againstIntl.NumberFormat.autoandmin2used to beRTR0065on
:integer, and anyuseGroupingwasRTR0065on:number(#98).- Unless
useGrouping=never, a negative:integeruses the locale's minus
sign, asIntl.NumberFormatdoes:−5in Swedish and Norwegian, where it
used to be-5. Generated ESM now also writes the locale's minus sign for a
negative:number, as .NET already did (#98). - In a .NET process with
InvariantGlobalization,:integerand:number
format with the invariant symbols (1,234) instead of throwing
TranslationFormatException: such a process has no locale data.:number
used to throw there, and:integernow needs the locale for its default
grouping (#98).
Svelte and Vite apps
- A tag the project declares in
runic.jsonrenders without restating its
contract in TypeScript.createInlineRendererandcreateDocumentRenderer
pass a project tag without a binding to the factory'selement, like a
built-in tag, soLocalizedInlinerenders it with thecustomsnippet of
the same name:createInlineRenderer(inlineFactory)and
custom={{ "nm:highlight": highlight }}are enough. They used to throw
No renderer linked for 'nm:highlight'unless the application passed a
binding with a restated contract. A binding still replaces the factory for
its tag. The DOM renderers still require a binding for each custom tag and
now say so (No DOM renderer linked) instead of creating an unknown element
(#96). - The generated runtime exports
projectMarkup, the project's markup contracts
by name and typed inruntime.d.ts, forbindMarkup(projectMarkup["nm:highlight"], render).
The Vite quick start's "Svelte without SvelteKit" section shows a project
tag with a snippet. Regenerate ESM output to pick up the change (#96).
Generated C# catalogs
- Reading a locale of a generated catalog costs about a tenth of the memory it
did. The embedded data is now read as it streams, into the compact message
model, without a JSON document or per-message member dictionaries, and
equal names share one string. The compiler validated the messages when it
generated the catalog, so the runtime no longer validates them again; the
catalog still checks each against its definition. For a catalog of 1,287
messages,CreateManager("en")and one message allocated 11.3 MiB and kept
3.4 MiB live; it now allocates 1.3 MiB and keeps 0.95 MiB. Withde, which
also readsen, 19.8 MiB and 4.3 MiB became 2.2 MiB and 1.6 MiB. Published
with NativeAOT, the process's anonymous resident memory after formatting one
message fell from 14.1 to 3.6 MB (en) and from 21.4 to 5.1 MB (de), and
the executable shrank by 1 MB. Rebuild to pick up the change; the generated
code is unchanged
(#97). CompiledTranslationLocale.ReadRmf2Valueschecks the shape, kinds, types and
limits of the data, but no longer the message semantics. It is for
generated code; build aCompiledRmf2Messagewith its constructor to
validate a model from another source (#97).- RMF2 number literals are read without a regular expression, so the runtime
no longer builds one (#97).
What's Changed
- Ship 0.7.0-preview.3 and start 0.7.0-preview.4 by @ViktorJannicke in #94
- Publish the 1.0 versioning and support policy by @ViktorJannicke in #95
- Group :integer and :number digits by useGrouping as MF2 specifies by @ViktorJannicke in #99
- Read generated catalog locales as a stream without revalidating them by @ViktorJannicke in #100
- Render project markup tags without a restated contract by @ViktorJannicke in #101
- Export localeDirection from the generated ESM runtime (W315-019) by @ViktorJannicke in #102
Full Changelog: v0.7.0-preview.3...v0.7.0-preview.4