0027: Localization keys and display text
Status
Accepted (2026-10-16, P3 spec, specs/006-editor-extension-host/, FR-027 and FR-044, research R13). Decided autonomously on the
owner's standing instruction for P3 (decide and record). Three product choices below are defaults that are still pending the
owner; they are marked and listed in the P3 notes under "Owner questions taken by default".
Context
- Display text in the editor is a literal in C# or XAML. P3 adds contribution descriptors that extensions fill, so the strings need a stable identity before the extension packages publish (owner decision 8: L1 in P3, L2 in P6).
- Moving the existing strings is L2 and is not part of this ADR. This ADR fixes how new and contributed text is keyed, where the neutral text lives, how it falls back, which culture the editor runs in, and what the analyzers check.
Decision
LocalizedText. A publicrecord struct LocalizedText(string Key, string? DefaultText)inNetPrints.Core. It resolves through resource managers in order: the UI culture, its parent, the neutral resources (the framework'sResourceManagerfallback), then the default text, then the raw key. A plain string converts to a text that is its own key and default (FromLiteral).- Convention keys.
Node.<kind>.Title,.Description,.Keywords;Node.<kind>.Pin.<in|out>.<exec|data|type>.<key>(the line format ofNodePins.Shipped.txt);Category.<id>;Command.<id>.Labeland.Tooltip;Menu.<menuId>;Panel.<panelId>.Title;Settings.<section>.<key>.Labeland.Description. A descriptor built with a literal takes the key its id implies; a descriptor built with an explicitLocalizedTextkeeps its key. The menu id (MenuPlacement.Path) is separate from the header text, which isMenu.<id>. - Neutral resources.
src/NetPrints.Core/Graph/NodeStrings.resx(node titles, pins, the built-in category) andsrc/NetPrints.Editor/Strings.resx(category, commands, menus, panels), compiled with the MSBuild strongly typed generator. The editor class is public; Core's is internal behind one public member,CoreStrings.Resources, because the public API tracker lists every generated property of a public class, one line per key. - Extension resources.
IExtensionBuilder.AddStringResources(ResourceManager)(experimental, NPXE0011) collects an extension's resources intoExtensionRegistry.StringResources, in registry order. - Language.
netprints.languagein thenetprintssection is a culture name or empty (the operating system's culture). The validator refuses a string that is not a predefined culture, and the section then falls back to its defaults like any invalid section. The editor setsCultureInfo.CurrentUICultureandDefaultThreadCurrentUICultureonce at start. Semi and Ursa follow the app culture: the editor sets theirLocale, and when the theme does not take it (it reads back a different culture) the editor setsen-US. - Analyzers. NPA040 (a key a
[NodeKind]class implies is missing from the neutral resx; a warning for authors, an error in this repository), NPA041 (a satellite has an extra key or a different{n}placeholder count) and NPA042 (aNode.<kind>.*key no declaration uses; info). They read.resxfiles fromAdditionalFiles; a project without a resx is not checked. NPH006 (a literal passed to a UI sink) lands with the repository analyzers in C2.
Defaults pending the owner
- Pin labels with no resource show the raw key (AOP follow-up question 4). A pin with no resource shows its name, as before.
- The built-in node category stays the single "NetPrints" category (question 9), key
Category.netprints. - A language change applies after a restart (question 5). There is no live switch: compiled
x:Statictext and the Semi and Ursa locale are read at start, which matches the "Restart to apply" bar of the settings pages (ADR-0040).
Consequences
- Command labels, panel titles and menu headers resolve through
Strings; node titles, pin labels, search category headers and suggestion names resolve throughLocalizedTextover the strings of the extensions and thenCoreStrings.Resources(the extensions first, so a language pack can translate a built-in key). A node shows itsNode.<kind>.Titleonly whenNode.TitleIsFixedis true (its text is the same for every instance); a title that depends on content stays as built. A pin showsNode.<kind>.Pin.<pinRef>for its name and keeps what its own text adds after the name (a data pin's type). A category header usesCategory.<name in lower case, spaces as hyphens>; a node suggestion's display name is aLocalizedText(a plain string is its own key; an explicit key keeps two suggestions with the same text apart). L2 moves the rest. - Satellite resx files are not shipped yet; the fallback chain is tested against in-memory resources, and the first translation adds a satellite and NPA041 starts to apply to it.
- Semi has locales for 16 cultures and Ursa for 7 (versions pinned in
Directory.Packages.props); any other culture shows the English strings in those controls while the editor's own text follows the app culture.