Skip to content
LoomWeaver

Translations

This is a guide, not the contract. What the platform guarantees is specified under openspec/specs/. For this page: i18n. Where this page and a specification disagree, the specification is right, and that is a defect in this page: change the behaviour there, then explain it here.

Titles/labels are translation keys resolved by the host’s Transloco. Ship your weaver’s strings as a namespace: the distribution registers provideTranslationNamespaces('notes') and serves /i18n/notes/{lang}.json; your keys then live under notes.* and can never collide with host keys. The file itself does not repeat the namespace, because the loader nests it under the name:

// /i18n/notes/en.json                      resolved keys
{
  "list": "Notes",                       // → notes.list
  "admin": "Admin tools"                 // → notes.admin
}

A literal string with no matching key renders as-is, so you can start with literals and add i18n later. The host tells a literal from a key by its shape: a key is dot-separated word segments with at least one dot and no whitespace, which every key in the workbench and in a nested bundle has. A code such as DE, a name such as Deutsch or a person’s full name is a literal, shown as it is and never reported as a missing translation in development. A dotted string no bundle knows is still reported, so a literal that looks like a key, 1.2.3 say, is the one case that warns. (See building a distribution for the wiring.)

Body text is yours. The host resolves keys only for what it draws itself: contribution metadata (view/command/item titles, settings labels, the tagline), the labels of a menu opened with ctx.ui.openMenu, and tab badges. So ctx deliberately has no translate function for the free text inside your views and dialogs. Keep that text as literals, or import @jsverse/transloco directly if you need runtime language switching inside the body. That import is the one documented exception to “a weaver imports only @loomweaver/plugin-sdk”: Transloco is a third-party library you depend on yourself, not a LoomWeaver API. The platform contract stays exactly the SDK’s exports.

Where next