Runic DevKit for VS CodeBefore 1.0, a minor release can still change commands and settings; the release notes list every change. Install
One extension for the Runic SDK and Runic Translations:
Moving from Runic or Runic MF2 TranslationsThis extension has had three identities:
0.22 only renames the extension, before its first Marketplace listing: its
commands, settings, views and Command Palette titles stay the same. Since 0.20
Translations-only workspaces use the same extension; the Runic SDK views stay
hidden there. VS Code treats each identity as another extension, so a
From Runic MF2 Translations, settings and commands also moved to the
The Command Palette titles are unchanged ( Runic SDK featuresWorkspace detectionA workspace folder has a Runic SDK project when a Dev Session:
|
| Command | What it does |
|---|---|
| Runic: Start dotnet runic dev | The development server and the Window |
| Runic: Start dotnet runic dev --no-window (frontend only) | The frontend; the debugger starts the Window |
| Runic: Stop dotnet runic dev | Ends the task, or a dev started in a terminal |
| Runic: Debug the Window (F5 with dotnet runic dev --no-window) | The template's Window configuration, or the extension's |
| Runic: Open the Development Server | The session's development server in the browser |
| Runic: Open the dev Session File | obj/runic/dev-session.json |
| Runic: dotnet runic dev Actions… | The status bar item's choices |
| Runic: Run dotnet runic doctor | The Doctor view and Problems |
| Runic: Refresh ViewModels | Rereads the development source map |
| Runic: Open C# Member | From the ViewModels view |
| Runic: Refresh Translation Status | The Translations view |
| Runic: Show Runic SDK Output | The Runic output (dev session changes, doctor) |
Install the tool
The extension runs the workspace's own runic-translations .NET tool, so the
language server always matches the project's Translations release. It does not
install or restore tools for you. In the repository (or solution) root:
dotnet new tool-manifest --output .config
dotnet tool install dotnet-runic-translations --version <VERSION>
dotnet tool restore
Use the same exact version as the project's Runic Translations packages, and
commit .config/dotnet-tools.json; collaborators then run only
dotnet tool restore. The tool needs the .NET 10 runtime. Projects created with
the runic-translations templates already contain the manifest.
Starting and status
Open a trusted workspace containing a restored local runic-translations .NET
tool. The extension starts dotnet tool run runic-translations -- lsp from the
nearest tool-manifest directory.
If the server cannot start (no tool manifest, an unrestored tool, a missing
.NET runtime), a notification says why once per workspace folder, with
Show output and How to install the tool; Runic: Restart Language
Server tries again. The status bar shows the server state for the active
.mf2, .rmf2 or runic.json file and, while the server runs, the catalog ID
and the file's locale (Runic: app · de). Select it, or run Runic: Show
Output, for the server log.
For SDK development, set runic.translations.serverAssembly to the built tool DLL;
runic.dotnetPath selects the installed .NET executable. Separate
workspace folders get separate server instances; the server's runic.* commands
(such as the Mark reviewed quick fix's) are registered once and run against
the folder of the file they name. Restarting reopens unsaved
buffers; stopping releases watchers and terminates the language-server client.
For grouped projects, declared sourceRoots inside the opened workspace are
covered by one canonical recursive watch plan, so mounted add/change/delete/rename
events outside the config directory are reconciled without duplicate nested
watchers. Open a common containing workspace for such mounts; roots outside that
boundary and symlink/reparse-point escapes are not watched.
Diagnostics, hover and runic.json
Diagnostics cover the whole catalog, not only open files: while any file of a
project is open, catalog errors and warnings in its closed translations and in
runic.json appear in the Problems view, and they are cleared when the last
file of the project closes. Each RTR code links to its entry in the
diagnostics reference
at the release tag of the tool. Hover over a message in a translation shows the
base-locale text with its comments and @param descriptions, and its review
state from the project's review file (<catalog>.review.json beside
runic.json, the file runic-translations review mark and the Translations
Editor write), marked stale when the source changed since it was recorded.
A stale review entry is reported as RTR0090; its quick fix Mark … reviewed
records the entry's state again for the source on disk in the review file. It is
offered, and runs, only while the files with the base message and the translation
have no unsaved changes. Review warnings, hover and quick fixes also work while
the catalog has errors elsewhere, such as a locale that misses keys.
RTR0095 (plural categories that fall to *) has a quick fix that adds the
missing variants as copies of the * variant.
runic.json files are validated and completed against the project schema
bundled with the extension, copied from the specification on every build. A
file that declares $schema uses that schema instead (VS Code downloads the
published URL); templates write the published project-v1.schema.json URI.
Commands and preview
| Command | What it does |
|---|---|
| Runic: Restart Language Server | Stops and starts the language server; reopens unsaved buffers |
| Runic: Show Output | The language server's log |
| Runic: Preview Message | The message preview panel |
| Runic: Change Preview Samples | Another @example sample set, or custom values |
| Runic: Change Preview Locale | The open panel's language, pseudo-locales included |
| Runic: Change Preview Regional Locale | The locale a user requests, such as de-CH for de text |
| Runic: Change Preview Time Zone | The zone timeZone=local formats in |
| Runic: Rename Input in Resource Sources | F2 on the input (protocol 2), or a pick list and an input box (0.13) |
| Runic: Rename Slot in Resource Sources | F2 on the slot reference (protocol 2), or a pick list and an input box (0.13) |
| Runic: Rename Resource in Resource Sources | F2 on the resource (protocol 2); renames in resource sources only |
| Runic: Extract Group to Directory | The Extract code action (protocol 2) |
| Runic: Inline Resource into Ancestor | The Inline code action (protocol 2), or a file dialog (0.13) |
| Runic: Export XLIFF | One XLIFF 2.1 document per translated locale |
| Runic: Import XLIFF (dry run) | What an import would do, written to the output |
| Runic: Override Library Message… | Adds a library message to the application's overrides |
| Runic: Show Translation Status | Coverage per locale |
| Runic: Import .resx or i18next Catalog | A dry run, then the import after you confirm |
| Runic: Refresh Translation Status | The Translations view |
Export XLIFF writes one XLIFF 2.1 document per translated locale into a
folder you choose, and Import XLIFF (dry run) reports what importing a
translated document would do, unit by unit, without writing anything (the
output goes to Runic: Show Output). Both use the project of the active file (the
nearest runic.json above it), or ask which project when no file of one is
active and the workspace has several. Both run the workspace's local
runic-translations xliff tool, the same code as the Translations Editor; apply
an import with runic-translations xliff import or the editor.
Library catalogs and overrides
An application overrides the text of a library catalog that an installed package packs (runic.json "overrides",
translations/overrides/<catalog>/<locale>.rmf2). The language server finds the library in the restore output
(obj/project.assets.json) or in node_modules, as the build and the Vite plugin do, and treats override sources as
overlays on it: an unknown key (RTR0103), changed inputs and markup in a plain-text message are reported as the build
reports them, completion offers the library's keys and inputs, hover shows the library's base text (and its text in the
file's locale, or the fallback of a locale the application adds), and Go to Definition opens the library's source as
a read-only document. A library update that changes the base text of an overridden message is reported (RTR0090).
Restore the project first; without the package the override sources report RTR0104. The extension watches the restore output
(obj/project.assets.json) and the package managers' install state and lockfiles, so the language server picks up a restore or an install
without a restart.
Override Library Message… asks for an installed library catalog, one of its messages and a locale (a library locale,
or another one the application adds; a typed tag is canonicalized, so de_ch becomes de-CH), then runs the workspace's local runic-translations overrides add: it adds the
message to translations/overrides/<catalog>/<locale>.rmf2, seeded with the library's text and with the base text as
comments, records that base text, lists the catalog in runic.json "overrides" when needed, and opens the file at the
message.
Show Translation Status shows runic-translations status for the project:
per locale the messages translated, served by a fallback locale, missing and
stale, the coverage, and whether missing translations are errors or warnings
(the locale's validation.translationCompleteness), the same report as the
command line and the Translations Editor. The status bar adds the coverage of
the active file's locale (Runic: app · de 87.5%, details in the tooltip); it
follows saved changes.
Import .resx or i18next Catalog migrates an existing catalog into the
project's .rmf2 sources with runic-translations import: it runs a dry run
first, shows its outcome per message in Runic: Show Output, and imports
after you confirm, optionally replacing the text of messages that already exist.
The Runic Translations commands in the Command Palette provide inert example previews,
group extraction/inlining for .rmf2, and explicitly source-only
input/slot/resource renames. Preview asks the server to execute the selected
semantic contract's verified .NET runtime plan and renders the returned inert runs. Links/actions are
inert, icons are placeholders and custom markup is labeled; no application
callbacks or application startup are involved. Custom renderer code is never
loaded by the extension.
Preview Message offers every @example sample set plus custom values. The
selected locale and values are remembered per message during the extension
session; reopening a preview reuses them. Change Preview Samples lets you
choose another example or edit custom values. Change Preview Locale switches
the open panel's language; it also lists the pseudo-locales that runic.json
configures (pseudoLocales: en-XA, ar-XB), which the server generates from
the base locale exactly as a --pseudo-locales build does (read-only).
Change Preview Regional Locale sets the locale a user requests, such as
de-CH for de text: numbers and dates then format as the runtime formats a
de-CH request that resolved to de. Change Preview Time Zone sets the zone
that timeZone=local, the default of :datetime styles, formats in (utc, an
IANA zone, or the host's). The panel names the requested locale, how it relates
to the shown locale (exact, parent or related), the locale numbers and dates
formatted in and the time zone, and lays the text out in the locale's direction.
The regional locale and time zone stay for the next message. Samples for the
128 most recently previewed message/locale combinations are retained. The panel refreshes from
the latest unsaved resource/configuration buffers and watched source changes.
Out-of-order requests and cancelled selections cannot replace a newer preview.
The LSP owns direct and grouped MF2 plus configuration synchronization. Existing C#, TypeScript, Svelte language services retain their files. Resource-source edits are not application-call-site refactors. In a workspace containing application or other non-resource sources or unindexable links, standard resource F2 asks before it renames in resource sources only (Translations 0.14), or refuses (Translations 0.13), where the explicit Rename Resource in Resource Sources command intentionally applies the narrower transaction. Use the native language service for generated API usages and review source-only input/slot operations against application bindings. Unsupported language operations must not be treated as a successful whole-application rename.
Refactorings: F2 and the light bulb
With Translations 0.14 (the language server's protocol 2, which the extension
requests with initializationOptions.runicProtocol: 2), the Translations
refactorings take the editor's standard paths, and the server applies their
edits. The host test runs them against dotnet-runic-translations 0.14.0:
- F2 renames a resource, an MF2 local, a caller input (on
$name, in every locale's resource) or a slot reference (on the value ofref=, also in therunic.jsonslot contracts). - The light bulb (Ctrl+.) on a group's name offers Extract group 'x' to x/en.rmf2; in a feature-local resource it offers Inline into ../en.rmf2, one action per ancestor resource of the same locale (this replaces the file dialog). VS Code deletes the inlined file as part of the edit. Visual Studio cannot delete files through LSP, so there the server empties the file and Runic DevKit for Visual Studio deletes it once it is saved (see its README).
- A resource rename in a workspace with application sources asks first, with
Rename in resource sources or Cancel (the server's
window/showMessageRequest). - The server builds a light-bulb refactoring's edit when VS Code resolves the action, and rejects it as outdated when files changed meanwhile, for example through the file watcher after a save. The extension then resolves the action once more; if that is outdated too, it says so in a warning (run the action again) instead of applying nothing silently (runic-editors#32).
The palette commands remain: Rename Input, Rename Slot and Rename
Resource in Resource Sources move the cursor to the symbol and open the F2
rename box; Extract Group to Directory and Inline Resource into Ancestor
open the code action of that kind. With Translations 0.13 they keep their 0.21
behaviour (a pick list and an input box, a file dialog for Inline), and F2
renames resources and MF2 locals only. The extension asks the server for
protocol 2 and falls back when it does not offer it; Runic: Show Output
logs Runic protocol 1 or 2 for each workspace folder.
VS Code and Visual Studio
Runic DevKit for Visual Studio has the same Runic SDK and Translations features, with Visual Studio's own menus, tool window and Error List. The Visual Studio README compares the two extensions feature by feature and lists what Visual Studio does not have yet.
Build and test
Build and test in the runic-editors development shell (see the repository
README), from the vscode directory:
bun install --frozen-lockfile
bun run check
bun run test
bun run build
bun run test:host
bun run package
The host check uses the installed code, or VSCODE_EXECUTABLE_PATH, with an
isolated profile, extension directory and a multi-root workspace of a copy of
fixtures/rmf2 (Translations only), of fixtures/sdk-app (a Runic SDK
project) and a second copy of fixtures/rmf2, whose own language server shows
that the folders share the server's runic.* commands. Each Translations fixture gets the repository's
.config/dotnet-tools.json, and dotnet tool restore installs that
dotnet-runic-translations release from NuGet, so the extension starts the
language server as it does in a user's workspace. The SDK fixture is never
built: the test writes the session file and the source map that dotnet runic dev and the build would, with a stand-in dotnet runic dev process whose death
the session must follow, and a stand-in dotnet answers dotnet runic doctor. Set
RUNIC_TRANSLATIONS_SERVER_ASSEMBLY (or RUNIC_TRANSLATIONS_SERVER) to a built
dotnet-runic-translations.dll to test a local server build instead. The test
follows the protocol the server offers: against a protocol 2 server (Translations
0.14) it also runs F2 on an input and the Inline Resource and Extract Group code
actions through the palette commands, and checks that the runic.* commands
apply their edits. bun run test:host:protocol2 requires protocol 2 and fails
against an older server:
RUNIC_TRANSLATIONS_SERVER=<runic-translations-sdk>/tools/dotnet-runic-translations/bin/Release/net10.0/dotnet-runic-translations.dll \
bun run test:host:protocol2
The check requires an assertion
report, not merely a zero CLI exit code. Failure logs are retained under
artifacts/host-failure. Packaging produces artifacts/runic-devkit.vsix;
no marketplace upload or user-profile installation is part of these commands.
The version in package.json is a placeholder. bun run package (package.mjs)
stamps the release version of eng/version.json, mapped to x.y.z, into a
staged copy and packs that: the plain 0.8.0 becomes 0.8.1000, 1.0.0-rc.N
becomes 1.0.(500 + N) packaged with --pre-release, and the final 1.0.0
becomes 1.0.1000. It fails if the VSIX does not carry that version, the
pre-release flag of a -preview.N/-rc.N release, and the Preview label. See
IDE extension versions for
the full mapping. Each GitHub release attaches the attested VSIX that CI built.
The language client follows Microsoft's Language Server Extension Guide.