@hydranium/core 1.0.0-next.31 → 1.0.0-next.32

package/src/langium/bootstrap.ts

@@ -73,7 +73,14 @@ const EXPECTED_SHARED_SLOTS: readonly ExpectedSlot[] = [
       side: 'shared',
       path: 'workspace.BuildPipelineIntegration',
       get: services => nested(services, 'workspace', 'BuildPipelineIntegration')
-   }
+   },
+   // Unbound, this fails where the cause is least visible: the render pass runs
+   // inside the `Validated` phase, so a `TypeError` there propagates out of
+   // `notifyDocumentPhase` and the document reaches `Validated` with Langium's
+   // publisher never invoked — the client receives no diagnostics for the file
+   // and the stack names the document builder.
+   { side: 'shared', path: 'MessageRenderer', get: services => nested(services, 'MessageRenderer') },
+   { side: 'shared', path: 'ServerLocale', get: services => nested(services, 'ServerLocale') }
 ];
 
 /**

package/src/langium/document-builder/document-builder.ts

@@ -21,8 +21,12 @@ import {
    interruptAndCheck,
    isOperationCancelled
 } from '@hydranium/langium';
-import { CancellationToken, type Diagnostic } from 'vscode-languageserver-protocol';
+// `Diagnostic` as a VALUE: `renderDiagnostics` needs its `getMessageString`
+// namespace helper to read the `string | MarkupContent` union without
+// restating it.
+import { CancellationToken, Diagnostic } from 'vscode-languageserver-protocol';
 import { type LogNameOptions } from '../diagnostics/logger.js';
+import type { ServerMessageRenderer } from '../../messages/renderer.js';
 import { CST_REHYDRATION_RESET_STATE, isCstShed } from '../residency/cst-residency-service.js';
 import { type ExtendedServiceRegistry } from '../service-registry.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
@@ -119,7 +123,9 @@ export interface DocumentBuilderOptions extends LogNameOptions {
  * - **In-place rebuild helpers** — {@link reparse} and
  *   {@link reparseAndRelink} — for a build-phase listener that mutated a
  *   document's AST and must reconcile it within the same build.
- * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}).
+ * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}), followed
+ *   by the **one server-side message render** every head inherits
+ *   ({@link renderDiagnostics}).
  * - **Build sessions** ({@link BuildSession}): each `update` / `build` call is
  *   one correlated unit carrying an id, a trigger label, a start time and
  *   cancellation lineage, so every line of a rebuild reads as belonging to it
@@ -152,6 +158,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly phaseDetailMs: ObservableValue<number>;
    protected readonly uriPolicy: DocumentUriPolicy;
    protected readonly clock: Clock;
+   protected readonly messageRenderer: ServerMessageRenderer;
    /** Narrower handle on the same registry as the inherited `serviceRegistry`, for {@link ExtendedServiceRegistry.registrations}. */
    protected readonly languageRegistry: ExtendedServiceRegistry;
    protected languageFileExtensions: string[] = [];
@@ -184,6 +191,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       this.languageRegistry = services.ServiceRegistry;
       this.uriPolicy = services.workspace.DocumentUriPolicy;
       this.clock = services.Clock;
+      this.messageRenderer = services.MessageRenderer;
       this.tracer = services.Tracer.for(options.logName ?? 'DocumentBuilder').trace('instantiated');
       this.logLevel = options.logLevel ?? 'debug';
       this.loggedPhases = options.loggedPhases ?? DEFAULT_LOGGED_PHASES;
@@ -893,8 +901,12 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       // build settling inside that window therefore appends after this call has
       // already deduped, and the appended duplicate is published by the listener
       // of the build that deduped. Only `serializeBuilds` closes the window.
+      //
+      // Dedupe before rendering: rendering is deterministic, so it cannot
+      // change which entries are structurally equal, and fewer survive to render.
       if (state === DocumentState.Validated) {
          this.dedupeDiagnostics(document);
+         this.renderDiagnostics(document);
       }
       if (this.logLevel === 'off') {
          return super.notifyDocumentPhase(document, state, cancelToken);
@@ -1070,6 +1082,62 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       }
    }
 
+   /**
+    * Render every diagnostic on `document` through the bound message renderer,
+    * in ONE pass over the finished list.
+    *
+    * All three heads read `document.diagnostics` — the LSP publish,
+    * `TransferEncoder.toTransferDiagnostic` and the GLSP validation path — so
+    * one pass here is what keeps the render from happening per head. It is also
+    * the only placement that covers lexer and parser errors, which Langium
+    * pushes onto the document without routing them through `toDiagnostic`.
+    *
+    * Running here rather than from a `Validated` phase listener needs no
+    * ordering assumption: Langium publishes from `addDiagnosticsHandler`, a free
+    * function it registers as such a listener, which can only be outrun.
+    *
+    * **It inherits {@link dedupeDiagnostics}'s window, and therefore the same
+    * precondition.** A build settling inside the listener window appends
+    * diagnostics this pass never saw, and the publisher of the build that
+    * rendered sends them — unrendered. `ModelServiceOptions.serializeBuilds`
+    * closes it and defaults to `true`, so "every diagnostic is rendered" holds
+    * by default and is an opt-out rather than a guarantee. Opting out accepts
+    * unrendered diagnostics on exactly the terms it already accepts duplicates.
+    *
+    * Entries are REPLACED rather than mutated: `sendDiagnostics` passes the
+    * array by reference and serialises later, so an in-place message mutation
+    * reaches the wire even when it runs after the publisher — which would make
+    * a test for the ordering pass in either state.
+    */
+   protected renderDiagnostics(document: LangiumDocument): void {
+      const diagnostics = document.diagnostics;
+      if (!diagnostics || diagnostics.length === 0) {
+         return;
+      }
+      let changed = false;
+      // No try/catch: `renderDiagnostic` carries a no-throw contract, because an
+      // error escaping this phase strands the document at `Validated` with
+      // Langium's publisher never invoked.
+      const rendered = diagnostics.map(diagnostic => {
+         const text = this.messageRenderer.renderDiagnostic(diagnostic);
+         // Against the message's STRING FORM, not the field. `renderDiagnostic`
+         // answers a `string` by contract, while `Diagnostic.message` is
+         // `string | MarkupContent` since LSP 3.17 — so comparing the answer
+         // against the field never matches for a markup message, and a pass
+         // that replaced on mismatch flattened every un-identified markup
+         // diagnostic to its own plain text. That is silent data loss on the
+         // path whose whole job is to leave such entries alone.
+         if (text === Diagnostic.getMessageString(diagnostic)) {
+            return diagnostic;
+         }
+         changed = true;
+         return { ...diagnostic, message: text };
+      });
+      if (changed) {
+         document.diagnostics = rendered;
+      }
+   }
+
    // ============================================================
    // Internal helpers
    // ============================================================

package/src/langium/model-service/model-service.ts

@@ -11,6 +11,7 @@ import {
    type CanonicalUri,
    type CloseModelArgs,
    ConflictError,
+   defineMessage,
    Logger,
    type MaybeObservableValue,
    type MaybePromise,
@@ -34,6 +35,23 @@ import { labelPhaseListener } from '../document-builder/labeled-phase-listener.j
 import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
 import { type ServerSharedServices } from '../module.js';
 
+/**
+ * The undo-stack entry for a server-authored write pushed to the editor.
+ *
+ * **A user-facing LABEL, not a log string**, which is easy to miss because it
+ * travels as an options field rather than as a message: LSP specifies
+ * `ApplyWorkspaceEditParams.label` as "presented in the user interface for
+ * example on an undo stack to undo the workspace edit". So a user who edits
+ * through a form or drags a diagram node reads this in their editor's undo menu
+ * — which is why it is rendered like any other message the server sends rather
+ * than left as the English literal it was.
+ *
+ * Parameterless deliberately. The obvious improvement is to name the document,
+ * and it is the wrong one: an undo menu is already grouped under the file, so
+ * the URI would be noise in the one place it is redundant.
+ */
+export const MODEL_UPDATE_EDIT = defineMessage('hydranium/core/model-update-edit', 'Update Model');
+
 /** Max time {@link ModelService.settleSave} waits for the build to settle and the sync chain to drain. */
 const SAVE_SETTLE_TIMEOUT_MS = 10_000;
 
@@ -878,13 +896,26 @@ export class ModelService<
       this.syncChains.set(uri, chain);
    }
 
+   /**
+    * The undo-stack label for a server-authored write, in the locale the server
+    * was handed at init.
+    *
+    * One method rather than the literal at each `applyEdit`, because the two
+    * call sites are the same edit — a push and its full-replace retry — and an
+    * undo menu showing two different words for one operation would read as two
+    * operations.
+    */
+   protected editLabel(): string {
+      return this.services.MessageRenderer.renderMessage(MODEL_UPDATE_EDIT);
+   }
+
    protected async drainSyncQueue(uri: string): Promise<void> {
       const uriLogger = this.tracer.withUri(uri);
       while (this.pendingSync.has(uri)) {
          const text = this.pendingSync.get(uri)!;
          this.pendingSync.delete(uri);
          try {
-            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
             if (result?.applied === false && !this.pendingSync.has(uri)) {
                // The push is addressed at the client's LAST DECLARED VERSION, so a
                // rejection normally means the client's buffer moved while the
@@ -905,7 +936,7 @@ export class ModelService<
                // queued — best-effort, since a settle arriving later simply pushes
                // after this and still wins.
                uriLogger.warn(`Language client rejected applyEdit at its declared version — re-pushing a full replace`);
-               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
                if (result?.applied === false) {
                   uriLogger.warn(`Language client rejected the full-replace retry too — client content is stale`);
                }

package/src/langium/module.ts

@@ -8,6 +8,8 @@
  ********************************************************************************/
 
 import { type Clock, type Logger, type Project, type Tracer, type TransferDiagnostic, NoopLogger, SystemClock } from '@hydranium/protocol';
+import { ServerLocale } from '../locale/server-locale.js';
+import { ServerMessageRenderer } from '../messages/renderer.js';
 import { ServerTracer } from './diagnostics/server-tracer.js';
 import { HydraniumLangiumProfiler } from './diagnostics/hydranium-langium-profiler.js';
 import { type AstNode, type Module } from '@hydranium/langium';
@@ -92,6 +94,24 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
     * plain `DefaultTracer` with their own `MemoryReader`.
     */
    Tracer: Tracer;
+   /**
+    * Renders each user-facing message once, before the server sends it — so
+    * every message is rendered by the side that knows the reading user's
+    * language. All three heads inherit one diagnostics pass, which is what
+    * makes this the single slot an adopter with i18n rebinds; the same binding
+    * serves framework codes and their own `defineMessage` codes alike.
+    *
+    * The framework ships English only and selects no locale, so the default
+    * returns every sentence unchanged. Adopters subclass and override
+    * `translationsFor`.
+    */
+   MessageRenderer: ServerMessageRenderer;
+   /**
+    * The locale an init handed the server, for whoever renders in it. Held
+    * apart from the renderer so replacing the renderer cannot drop locale
+    * handling.
+    */
+   ServerLocale: ServerLocale;
    /**
     * LSP-bound slots layered on top of Langium's `LangiumSharedLSPServices`.
     * The framework contributes a single string slot here —
@@ -334,6 +354,8 @@ export function createServerSharedModule(
       ServiceRegistry: services => new ExtendedServiceRegistry<ServerLanguageServices>(services),
       Logger: () => new NoopLogger(),
       Tracer: services => new ServerTracer(services.Logger, services.Clock),
+      ServerLocale: services => new ServerLocale(services),
+      MessageRenderer: services => new ServerMessageRenderer(services),
       // Bind Langium's per-grammar-rule / per-`$type` parse/link/validate
       // profiler (the data the framework's own `Tracer`/`ProfileSession` passes
       // cannot produce), routed through our `Logger` and debug-gated. At the

package/src/langium/naming/name-provider.ts

@@ -59,6 +59,16 @@ export interface NameProviderOptions {
     * an `id` field) override explicitly; the explicit override at
     * the adopter side documents the grammar's convention rather than
     * burying it in a framework default.
+    *
+    * **The override is not optional where `name` is a display LABEL rather
+    * than an identifier**, and getting it wrong is quiet at first and then
+    * loud. A `name=STRING` holding `"Order.Line"` is legitimate content, but
+    * the default reads it as the identifier: `getName` composes a qualified
+    * name whose segments cannot be told apart from the label's own dots, and
+    * `nameSeparatorCheck` reports `hydranium/core/separator-in-name` on every
+    * such node. That diagnostic then names the wrong remedy — it asks for a
+    * different character, when the fix is to point this option at the property
+    * that really is the identifier.
     */
    readonly nameProperties?: readonly string[];
 }

package/src/langium/naming/name-separator-validation.ts

@@ -10,14 +10,36 @@
 import { type AstNode, type ValidationAcceptor, type ValidationChecks } from '@hydranium/langium';
 import { defineMessage } from '@hydranium/protocol';
 import { acceptMessage } from '../../messages/carriers.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { type ValidationCheckContribution, type ValidationCheckRegistry } from '../validation/validation-contribution.js';
+import type { NameProvider } from './name-provider.js';
 
+/**
+ * A name value that collides with the qualified-name separator.
+ *
+ * **The sentence addresses a MODELLER, and the remedy it names is theirs**:
+ * where `name` really is the identifier, a different character is the fix and
+ * the only one available to whoever is typing.
+ *
+ * **The adopter-facing failure is a different one, and this message cannot
+ * carry it.** With `nameProperties` left at its default `['name']` over a
+ * grammar where `name` is a display LABEL — a `STRING` legitimately holding
+ * `"Order.Line"` — this fires on every dotted label at once, and "use a
+ * different character" is then advice nobody can act on: the content is
+ * correct and the configuration is not. A burst of this diagnostic across
+ * unrelated nodes is that misconfiguration, not a naming problem, and the fix
+ * is `nameProperties`. Widening the sentence to say both was rejected: a
+ * modeller cannot act on a DI option, and naming one in an editor squiggle
+ * teaches the wrong audience.
+ *
+ * Unreachable from a grammar whose identifier charset excludes the separator,
+ * which is every example here and the reference adopter — so it reads as dead
+ * and is not: it guards the configuration, not the content.
+ */
 export const SEPARATOR_IN_NAME = defineMessage(
    'hydranium/core/separator-in-name',
    "Name '{name}' contains the configured name separator '{separator}', which is reserved for qualified-name composition — use a different character."
 );
-import { type ServerLanguageServices } from '../language-module.js';
-import { type ValidationCheckContribution, type ValidationCheckRegistry } from '../validation/validation-contribution.js';
-import type { NameProvider } from './name-provider.js';
 
 /**
  * Per-node validation check: flag name-bearing AST nodes whose name

package/src/langium/shared-services.ts

@@ -9,6 +9,8 @@
 
 import type { Clock, Logger, Project, Tracer } from '@hydranium/protocol';
 import type { LangiumSharedCoreServices } from '@hydranium/langium';
+import type { ServerLocale } from '../locale/server-locale.js';
+import type { ServerMessageRenderer } from '../messages/renderer.js';
 import type { SelfSaveRegistry } from '../documents/self-save-registry.js';
 import type { WritableFileSystemProvider } from '../documents/ast-document-manager.js';
 import type { HydraniumDocumentRegistry } from './workspace/langium-documents.js';
@@ -28,8 +30,9 @@ import type { AdditionalDocumentContribution } from './workspace/additional-docu
  * framework additions that other framework services consume: the dedicated
  * {@link Clock}, {@link Logger} and {@link Tracer} top-level slots (injectable
  * time source, emission-only logger, and the measure-and-emit tracer composed
- * from the other two), the {@link AdditionalDocumentContribution} group, an
- * {@link ExtendedServiceRegistry}, and on `workspace` a writable file-system
+ * from the other two), the {@link AdditionalDocumentContribution} group, the
+ * {@link ServerMessageRenderer} and the {@link ServerLocale} it renders in,
+ * an {@link ExtendedServiceRegistry}, and on `workspace` a writable file-system
  * provider plus {@link HydraniumWorkspaceManager}, {@link ProjectManager},
  * {@link SelfSaveRegistry}, {@link BuildPipelineIntegration},
  * {@link BuildPhasePassService}, {@link CstResidencyService} and
@@ -58,6 +61,14 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
     * adopters deep-merge contributions that seed built-in / stdlib documents.
     */
    additionalDocuments: Record<string, AdditionalDocumentContribution>;
+   /**
+    * Renders each user-facing message once, before the server sends it. On the
+    * shared tier with no workspace dependency, because all three heads'
+    * messages pass through it.
+    */
+   MessageRenderer: ServerMessageRenderer;
+   /** The locale an init handed the server, for whoever renders in it. */
+   ServerLocale: ServerLocale;
    /**
     * Narrows Langium's base `ServiceRegistry` slot to the framework impl the
     * framework always binds, so the abstaining lookups — `getServicesFor`

package/src/langium/validation/document-validator.ts

@@ -7,10 +7,20 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer, TransferDiagnostic } from '@hydranium/protocol';
+import {
+   defineMessage,
+   describeError,
+   messageData,
+   type LogThreshold,
+   type MaybeObservableValue,
+   ObservableValue,
+   type Tracer,
+   TransferDiagnostic
+} from '@hydranium/protocol';
 import {
    type AstNode,
    type AstNodeLocator,
+   type AstReflection,
    DefaultDocumentValidator,
    type DiagnosticInfo,
    type LangiumDocument,
@@ -48,6 +58,26 @@ export interface TransferLspDiagnostic extends Diagnostic {
    property?: string;
 }
 
+/**
+ * A reference resolved to nothing.
+ *
+ * **The English is byte-identical to Langium's `DefaultLinker.createLinkingError`
+ * sentence, and must stay so.** The identity is attached to a diagnostic Langium
+ * already worded, so a divergence here would silently change the text every
+ * adopter without a catalogue sees. {@link HydraniumDocumentValidator.processLinkingErrors}
+ * attaches it only when the two match exactly, which is also what keeps an
+ * adopter's own reworded linking error from being mislabelled as this one.
+ *
+ * It exists because this is the most-seen validation error in any language built
+ * on the framework, and Langium puts its own code in `data.code` rather than on
+ * `Diagnostic.code` — so without a framework identity every adopter wanting to
+ * render it has to special-case Langium's shape.
+ */
+export const UNRESOLVED_REFERENCE = defineMessage(
+   'hydranium/core/unresolved-reference',
+   "Could not resolve reference to {referenceType} named '{refText}'."
+);
+
 export interface DocumentValidatorOptions extends LogNameOptions {
    /**
     * Level at which the `validateDocument` timing line is emitted, or `'off'`
@@ -94,6 +124,7 @@ export interface DocumentValidatorOptions extends LogNameOptions {
 export class HydraniumDocumentValidator extends DefaultDocumentValidator {
    protected readonly tracer: Tracer;
    protected readonly astNodeLocator: AstNodeLocator;
+   protected readonly reflection: AstReflection;
    protected readonly logLevel: ObservableValue<LogThreshold>;
    protected readonly logAfterMs: ObservableValue<number>;
    protected readonly validateVirtualDocuments: ObservableValue<boolean>;
@@ -103,6 +134,7 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       super(services);
       this.tracer = services.shared.Tracer.for(options.logName ?? 'DocumentValidator').trace('instantiated');
       this.astNodeLocator = services.workspace.AstNodeLocator;
+      this.reflection = services.shared.AstReflection;
       this.logLevel = ObservableValue.from(options.logLevel ?? 'debug');
       this.logAfterMs = ObservableValue.from(options.logAfterMs ?? 20);
       this.validateVirtualDocuments = ObservableValue.from(options.validateVirtualDocuments ?? false);
@@ -157,6 +189,90 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       return !this.validateSyntheticNodes.value && isSyntheticNode(node);
    }
 
+   /**
+    * Langium's linking-error pass, plus the framework identity on each
+    * diagnostic it produced.
+    *
+    * Langium puts its own `linking-error` marker in `data.code` and leaves
+    * `Diagnostic.code` unset, so nothing identifies the message on a surface
+    * that drops `data` — which is every editor surface. This adds the framework
+    * identity to both `code` and `data.hydranium` while LEAVING `data.code` in
+    * place: `stopAfterLinkingErrors` and Langium's code-action dispatch both
+    * read it.
+    *
+    * **The identity is attached only when the message is the one
+    * {@link UNRESOLVED_REFERENCE} renders.** Two other sentences reach this
+    * list: the linker's exception form, raised when resolution itself throws,
+    * and whatever an adopter overriding `createLinkingError` chose. Labelling
+    * either would make a catalogue render the wrong sentence — and for the
+    * exception form it would discard the underlying cause. Comparing against
+    * the locally rendered English is what discriminates; there is no structural
+    * field that does.
+    */
+   protected override processLinkingErrors(document: LangiumDocument, diagnostics: Diagnostic[], options: ValidationOptions): void {
+      const from = diagnostics.length;
+      super.processLinkingErrors(document, diagnostics, options);
+      for (let index = from; index < diagnostics.length; index++) {
+         diagnostics[index] = this.identifyLinkingError(diagnostics[index]);
+      }
+   }
+
+   /**
+    * Add the {@link UNRESOLVED_REFERENCE} identity to one linking diagnostic,
+    * or return it untouched when its message is not the sentence that identity
+    * renders.
+    *
+    * `refText` comes from the `data` Langium populated; `referenceType` is not
+    * in it, so it is recovered the same way `createLinkingError` produced it —
+    * through the reflection, from the container type and property.
+    */
+   protected identifyLinkingError(diagnostic: Diagnostic): Diagnostic {
+      const data = diagnostic.data as { code?: unknown; refText?: unknown; containerType?: unknown; property?: unknown } | undefined;
+      if (typeof data?.refText !== 'string' || typeof data.containerType !== 'string' || typeof data.property !== 'string') {
+         return diagnostic;
+      }
+      const referenceType = this.referenceTypeOf(data.containerType, data.property, data.refText);
+      if (referenceType === undefined) {
+         return diagnostic;
+      }
+      const params = { referenceType, refText: data.refText };
+      if (diagnostic.message !== UNRESOLVED_REFERENCE.format(params)) {
+         return diagnostic;
+      }
+      // Merged OVER Langium's data rather than replacing it, so `data.code`
+      // survives for the readers that switch on it.
+      return { ...diagnostic, code: UNRESOLVED_REFERENCE.code, data: { ...data, ...messageData(UNRESOLVED_REFERENCE, params) } };
+   }
+
+   /**
+    * The declared target type of the reference this diagnostic came from, or
+    * `undefined` when the reflection cannot name one.
+    *
+    * **The lookup can throw, and that is the reason this is a method rather
+    * than an inline call.** `AbstractAstReflection.getReferenceType` raises on
+    * an unknown container `$type` and on a property that is not a reference —
+    * and the linking error whose type it cannot name is the one most likely to
+    * reach here, because `DefaultLinker` catches its OWN failed lookup and
+    * turns it into the exception-form message. Rethrowing would take
+    * `validateDocument` with it, since Langium wraps `processLinkingErrors` in
+    * no try: a diagnostic Langium degraded gracefully would become a failed
+    * build. Declining is also the right answer on the merits — a reference
+    * whose type cannot be named is not the message
+    * {@link UNRESOLVED_REFERENCE} claims.
+    */
+   protected referenceTypeOf(containerType: string, property: string, refText: string): string | undefined {
+      try {
+         return this.reflection.getReferenceType({
+            container: { $type: containerType } as AstNode,
+            property,
+            reference: { $refText: refText }
+         } as Parameters<AstReflection['getReferenceType']>[0]);
+      } catch (err: unknown) {
+         this.tracer.debug(`cannot name the reference type for ${containerType}.${property}: ${describeError(err)}`);
+         return undefined;
+      }
+   }
+
    protected override toDiagnostic<N extends AstNode>(
       severity: ValidationSeverity,
       message: string,

package/src/langium/workspace/hydranium-workspace-manager.ts

@@ -9,9 +9,10 @@
 
 import { Deferred, type Logger, type Tracer } from '@hydranium/protocol';
 import { DefaultWorkspaceManager, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
-import { type CancellationToken } from 'vscode-languageserver';
+import { type CancellationToken, type InitializeParams } from 'vscode-languageserver';
 import type { WorkspaceFolder } from 'vscode-languageserver-types';
 import { type LogNameOptions, resolveLogFilePlaceholder, toLogFileWorkspaceToken } from '../diagnostics/logger.js';
+import type { ServerLocale } from '../../locale/server-locale.js';
 import type { ProjectChangeEvent } from '../project/project-change-event.js';
 import type { ProjectManager } from '../project/project-manager.js';
 import type { ServerSharedServicesMinimal } from '../shared-services.js';
@@ -156,6 +157,8 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
    readonly workspaceInitialized: Promise<unknown> = this.workspaceInitializedDeferred.promise;
 
    protected readonly uriPolicy: DocumentUriPolicy;
+   /** Handed the client's locale at init; read by whoever renders in it. */
+   protected readonly serverLocale: ServerLocale;
    protected readonly writableFileSystemProvider: WritableFileSystemProvider;
    protected readonly additionalDocuments: Record<string, AdditionalDocumentContribution>;
    /** Registry consulted by {@link warnIfUnroutable} to check a seeded document routes. */
@@ -166,6 +169,7 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       this.projectManager = services.workspace.ProjectManager;
       this.projectManager.onProjectsChanged(event => this.onProjectsChanged(event));
       this.uriPolicy = services.workspace.DocumentUriPolicy;
+      this.serverLocale = services.ServerLocale;
       this.writableFileSystemProvider = services.workspace.FileSystemProvider;
       this.additionalDocuments = services.additionalDocuments;
       this.languageRegistry = services.ServiceRegistry;
@@ -360,6 +364,19 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       }
    }
 
+   /**
+    * Forward the locale the client declared, then Langium's own read of the
+    * params. `DefaultWorkspaceManager.initialize` reads `workspaceFolders`
+    * alone, so `params.locale` would otherwise be discarded — and this is the
+    * only place it arrives, which the headless init seams route through too.
+    */
+   override initialize(params: InitializeParams): void {
+      if (params.locale) {
+         this.serverLocale.accept(params.locale);
+      }
+      super.initialize(params);
+   }
+
    /**
     * Override of Langium's workspace setup to resolve / reject
     * {@link workspaceInitializedDeferred} once setup completes. Adopters with

package/src/langium/workspace/initialize-workspace.ts

@@ -18,6 +18,25 @@ import type { ServerSharedServicesMinimal } from '../shared-services.js';
 /** A workspace folder root accepted by the headless init seams: a filesystem path or a {@link URI}. */
 export type WorkspaceFolderInput = string | URI;
 
+/**
+ * Options for the headless init seams.
+ *
+ * **Optional, and the parameter is optional too**, so that no existing caller
+ * has to change to gain a field it does not set.
+ */
+export interface ProgrammaticInitOptions {
+   /**
+    * The locale to render user-facing server messages in — the headless
+    * equivalent of LSP `initialize`'s `locale`, for a head with no LSP
+    * connection (`startStdioServer`, the CLI subcommands, a test harness).
+    *
+    * Omitted means no locale, which the default renderer resolves as the
+    * framework's English. That is the correct answer for a headless tool: it
+    * has no reading user to have a language.
+    */
+   readonly locale?: string;
+}
+
 /**
  * Normalize the seam's flexible folder argument to LSP {@link WorkspaceFolder}s.
  * A `string` is resolved to an absolute filesystem path and wrapped as a
@@ -58,17 +77,25 @@ function toWorkspaceFolders(folders: WorkspaceFolderInput | ReadonlyArray<Worksp
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function initializeWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
    const workspaceFolders = toWorkspaceFolders(folders);
    const manager = services.workspace.WorkspaceManager;
-   // `initialize` records the folders (DefaultWorkspaceManager reads only this
+   // `locale` goes through the synthesized params rather than a direct
+   // `acceptLocale` call, so this seam and a real LSP `initialize` reach the
+   // slot by the SAME path — an adopter overriding the capture in
+   // `HydraniumWorkspaceManager.initialize` is honoured headlessly too, which a
+   // second write site here would silently bypass.
+   //
+   // `initialize` records the folders (DefaultWorkspaceManager reads only that
    // field); `initialized` runs `mutex.write(initializeWorkspace)` and resolves
    // once discovery + the init build settle, so awaiting it is the ready gate.
-   manager.initialize({ workspaceFolders } as InitializeParams);
+   manager.initialize({ workspaceFolders, locale: options.locale } as InitializeParams);
    await manager.initialized({} as InitializedParams);
 }
 
@@ -91,12 +118,14 @@ export async function initializeWorkspaceProgrammatically(
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function buildWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
-   await initializeWorkspaceProgrammatically(services, folders);
+   await initializeWorkspaceProgrammatically(services, folders, options);
    const documents = services.workspace.LangiumDocuments.all.toArray();
    await services.workspace.DocumentBuilder.build(documents, { validation: true });
 }

package/src/locale/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+export * from './server-locale.js';