@hydranium/core 1.0.0-next.7 → 1.0.0-next.70

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

@@ -7,12 +7,23 @@
  * 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,
+   DocumentValidator,
    type LangiumDocument,
    type LangiumCoreServices,
    type ValidateSingleNodeOptions,
@@ -20,21 +31,102 @@ import {
    type ValidationSeverity
 } from '@hydranium/langium';
 import type { CancellationToken } from 'vscode-languageserver-protocol';
-import type { Diagnostic } from 'vscode-languageserver-types';
+// A VALUE import, for `Diagnostic.getMessageString`: `message` is
+// `string | MarkupContent` in LSP 3.17+, so upstream's own reader is what
+// narrows it rather than a hand-rolled union check here.
+import { Diagnostic } from 'vscode-languageserver-types';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { isSyntheticNode } from '../workspace/synthetic.js';
 import { isVirtualUri } from '../workspace/virtual-document.js';
 
 /**
- * Diagnostic shape produced by {@link HydraniumDocumentValidator}: an LSP
- * {@link Diagnostic} extended with the protocol-level `element` path and
- * optional `property` name from {@link TransferDiagnostic}.
+ * Diagnostic read off a `LangiumDocument`: an LSP {@link Diagnostic} that MAY
+ * carry the protocol-level `element` path and `property` name from
+ * {@link TransferDiagnostic}.
+ *
+ * `element` is optional because a document's diagnostics do not all come from
+ * this validator. {@link HydraniumDocumentValidator.toDiagnostic} always sets
+ * one, but Langium pushes lexer and parser errors straight onto the document
+ * without routing them through it, so a document that fails to parse carries
+ * diagnostics with no path at all. Treat it as absent, not empty.
+ *
+ * Narrowing `LangiumDocument.diagnostics` to this type instead is unavailable:
+ * declaration merging may add a member but not retype one, and augmenting the
+ * LSP `Diagnostic` reaches only one of the two declaration files its package
+ * ships, since the `exports` map splits `import` from `default` with no `types`
+ * condition. Consumers therefore cast at the read, and the cast is sound only
+ * because this field is optional.
  */
 export interface TransferLspDiagnostic extends Diagnostic {
-   element: string;
+   element?: string;
    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}'."
+);
+
+/**
+ * A character no token of the grammar can start with.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultLexerErrorProvider.buildUnexpectedCharactersMessage`, and must stay
+ * so** — one layer further out than {@link UNRESOLVED_REFERENCE}, whose sentence
+ * is Langium's. Langium words neither: `processLexingErrors` copies
+ * `lexerDiagnostic.message` through untouched, so the text an adopter sees today
+ * is produced two dependencies down and is the only thing this identity may
+ * claim to be. {@link HydraniumDocumentValidator.identifyLexingError} attaches
+ * it only when the two match exactly, which is also what keeps a custom lexer's
+ * own diagnostics — Langium admits any of them through `lexerReport` — from
+ * being mislabelled as this one.
+ *
+ * It exists because a lexing error is the FIRST message a user of a new language
+ * sees and the one an adopter cannot reach: every other diagnostic worth
+ * translating either carries an identity already or is raised by adopter code,
+ * while this one arrives with a Langium `data.code` naming a KIND and no
+ * parameters at all — so a catalogue had nothing to key on and nothing to
+ * interpolate.
+ *
+ * `skipped` rather than `length`, matching what the sentence says the number
+ * means: chevrotain reports how many characters the lexer discarded to recover,
+ * which for a single stray character is one and for a run of them is the run.
+ */
+export const LEXING_ERROR = defineMessage(
+   'hydranium/core/lexing-error',
+   'unexpected character: ->{character}<- at offset: {offset}, skipped {skipped} characters.'
+);
+
+/**
+ * Langium's own `data.code` values for a diagnostic that came out of the lexer.
+ *
+ * All four severities, not just the error one: `lexerReport` admits warnings and
+ * below, and a token builder that downgrades a stray character still produces
+ * the same sentence. Gating on the error code alone would leave the identity off
+ * a message that is word-for-word the one it names.
+ */
+const LEXING_CODES: ReadonlySet<unknown> = new Set([
+   DocumentValidator.LexingError,
+   DocumentValidator.LexingWarning,
+   DocumentValidator.LexingInfo,
+   DocumentValidator.LexingHint
+]);
+
 export interface DocumentValidatorOptions extends LogNameOptions {
    /**
     * Level at which the `validateDocument` timing line is emitted, or `'off'`
@@ -81,6 +173,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>;
@@ -90,6 +183,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);
@@ -111,16 +205,85 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       }
       const level = this.logLevel.value;
       if (level === 'off') {
-         return super.validateDocument(document, options, cancelToken);
+         return this.validateAndIdentify(document, options, cancelToken);
       }
       // `level` is narrowed to `LogLevel` past the early-return.
       return this.tracer
          .withUri(document.uri.toString())
-         .time('validateDocument', () => super.validateDocument(document, options, cancelToken), level, {
+         .time('validateDocument', () => this.validateAndIdentify(document, options, cancelToken), level, {
             logAfterMs: this.logAfterMs.value
          });
    }
 
+   /**
+    * Langium's validation pass, plus the framework identity on the lexing
+    * diagnostics it produced.
+    *
+    * **Here rather than in an override of `processLexingErrors`, and the reason
+    * is that the seam cannot see what the identity needs.** Langium hands that
+    * method a `ParseResult`, which carries the AST and the error lists but not
+    * the source text — and the offending CHARACTER is the parameter a
+    * translation exists to interpolate. The document does carry it, and this is
+    * the innermost point that still holds one. Reconstructing the character by
+    * matching it out of the finished sentence was the alternative, and it
+    * inverts the direction the rest of this file works in: every other identity
+    * here is derived from structured fields and CHECKED against the prose.
+    *
+    * Inside the timing span rather than around it, so the line accounts for the
+    * whole pass.
+    */
+   protected async validateAndIdentify(
+      document: LangiumDocument,
+      options?: ValidationOptions,
+      cancelToken?: CancellationToken
+   ): Promise<Diagnostic[]> {
+      const diagnostics = await super.validateDocument(document, options, cancelToken);
+      // Mapped in place over the array Langium built, rather than filtered and
+      // re-concatenated: the publish order is the diagnostic order and a
+      // reordering would move a squiggle's entry in the problems list.
+      for (let index = 0; index < diagnostics.length; index++) {
+         diagnostics[index] = this.identifyLexingError(document, diagnostics[index]);
+      }
+      return diagnostics;
+   }
+
+   /**
+    * Add the {@link LEXING_ERROR} identity to one diagnostic, or return it
+    * untouched when it is not the sentence that identity renders.
+    *
+    * The parameters come from the diagnostic's own RANGE, not from
+    * `parseResult.lexerErrors`. Both hold the same numbers, and the range is the
+    * one that needs no assumption about upstream: correlating the two lists
+    * would depend on Langium appending one diagnostic per lexer error in order,
+    * which is true today and is an internal of the method being wrapped.
+    *
+    * **The format-and-compare is the whole discriminator, and it validates the
+    * reconstruction as well as the identity.** A range that did not round-trip
+    * to the offset chevrotain reported would produce a different sentence and be
+    * declined, so a wrong parameter set can never be attached to a right-looking
+    * message.
+    */
+   protected identifyLexingError(document: LangiumDocument, diagnostic: Diagnostic): Diagnostic {
+      const data = diagnostic.data as { code?: unknown } | undefined;
+      if (!LEXING_CODES.has(data?.code)) {
+         return diagnostic;
+      }
+      const text = document.textDocument;
+      const offset = text.offsetAt(diagnostic.range.start);
+      const params = {
+         character: text.getText().charAt(offset),
+         offset,
+         skipped: text.offsetAt(diagnostic.range.end) - offset
+      };
+      if (Diagnostic.getMessageString(diagnostic) !== LEXING_ERROR.format(params)) {
+         return diagnostic;
+      }
+      // Merged OVER Langium's data, so `data.code` survives for the readers that
+      // switch on it — `stopAfterLexingErrors` is one, and the GLSP head's
+      // read-only decision is another.
+      return { ...diagnostic, code: LEXING_ERROR.code, data: { ...data, ...messageData(LEXING_ERROR, params) } };
+   }
+
    /**
     * Skip validation for a node **and its children** when
     * {@link shouldSkipValidation} returns true.
@@ -144,6 +307,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/document-uri-policy.ts

@@ -105,10 +105,9 @@ export class DefaultDocumentUriPolicy implements DocumentUriPolicy {
    /**
     * No filesystem access, so existence cannot be checked — every URI is
     * treated as loadable and returned unchanged. A later load that misses
-    * therefore reaches the filesystem and throws, which
-    * `AbstractHydraniumLangiumDocuments.getOrCreateDocument` absorbs into its
-    * empty-document fallback: under this policy that fallback, not this method,
-    * is what makes a missing file a placeholder rather than an error.
+    * therefore reaches the filesystem and throws, which reports the miss with
+    * the reason the read failed. Under a policy that CAN check, the miss is
+    * caught earlier and reported without one.
     */
    loadUri(uri: URI | string): URI | undefined {
       return UriUtils.toUri(uri);

package/src/langium/workspace/hydranium-langium-document-factory.ts

@@ -15,6 +15,7 @@ import {
    type ParseResult,
    type URI
 } from '@hydranium/langium';
+import { type ExtendedServiceRegistry } from '../service-registry.js';
 import { type Serializer } from '../serialization/serializer.js';
 
 /** Structural view of the per-language serializer slot on the resolved services. */
@@ -49,6 +50,39 @@ interface WithSerializer {
  * node identity is preserved.
  */
 export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFactory {
+   /**
+    * Narrows the inherited Langium `ServiceRegistry` field to the framework's
+    * {@link ExtendedServiceRegistry}, so the by-id lookup below needs no
+    * per-callsite cast. The framework's shared module binds that class.
+    */
+   declare protected readonly serviceRegistry: ExtendedServiceRegistry;
+
+   /**
+    * Parse `text` for `uri` under the grammar `languageId` names, instead of
+    * the one `uri` routes to.
+    *
+    * For a URI that routes to no grammar at all: a directory, or any other URI
+    * that names no file and so carries no extension. Langium's ladder ends at
+    * the extension, so it reports `no services for the extension ''` from
+    * inside the parse — naming neither the URI nor the caller that could have
+    * said which grammar it meant.
+    *
+    * The caller supplies the language because nothing else can. A URI with no
+    * extension carries no routing signal, and choosing on its behalf would be a
+    * guess the moment a second grammar is registered — which is why this takes
+    * the id rather than falling back to a sole registered language.
+    *
+    * @throws when `languageId` names no registered grammar.
+    */
+   fromStringInLanguage<T extends AstNode = AstNode>(text: string, uri: URI, languageId: string): LangiumDocument<T> {
+      const services = this.serviceRegistry.getServicesById(languageId);
+      if (!services) {
+         throw new Error(`No grammar is registered for the language id '${languageId}' (parsing ${uri.toString()}).`);
+      }
+      const parseResult: ParseResult<T> = services.parser.LangiumParser.parse<T>(text);
+      return this.createLangiumDocument<T>(parseResult, uri, undefined, text);
+   }
+
    override fromModel<T extends AstNode = AstNode>(model: T, uri: URI): LangiumDocument<T> {
       // Make the code-built AST as structurally complete as a parsed one — the
       // parser links containers, `fromModel` does not. In place (identity kept).

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,31 @@ 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.
+    *
+    * **The ABSENT case is reported from here rather than from `ServerLocale`,
+    * because this is the only end that can see it.** `accept` is not called
+    * when no locale was declared — nor should it be, since `''` is a claim
+    * about a language rather than the absence of one — so a log written there
+    * covers one of the two outcomes and leaves the other looking like a server
+    * that never reached init. Both lines are at `info` for the reason `accept`
+    * gives: the framework ships no catalogue, so an undeclared locale and an
+    * untranslated code produce the same English and the log is what separates
+    * them.
+    */
+   override initialize(params: InitializeParams): void {
+      if (params.locale) {
+         this.serverLocale.accept(params.locale);
+      } else {
+         this.tracer.info("no locale declared at init — rendering messages in the framework's English");
+      }
+      super.initialize(params);
+   }
+
    /**
     * Override of Langium's workspace setup to resolve / reject
     * {@link workspaceInitializedDeferred} once setup completes. Adopters with

package/src/langium/workspace/in-memory-file-system-provider.ts

@@ -8,12 +8,22 @@
  ********************************************************************************/
 
 import { type FileSystemNode, URI } from '@hydranium/langium';
-import { type Tracer } from '@hydranium/protocol';
+import { defineMessage, type Tracer } from '@hydranium/protocol';
 import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
 import { serveVirtualDocument } from './virtual-document.js';
 
+/**
+ * The browser host's spelling of "the document is not there". Its Node
+ * counterpart is `NO_LOADABLE_CONTENT`: this provider has no `realpath`, so the
+ * URI policy cannot answer the existence question ahead of the read and the miss
+ * surfaces here instead.
+ */
+export const NO_SUCH_FILE = defineMessage('hydranium/core/no-such-file', 'No such file: {uri}');
+
+export const NO_SUCH_PATH = defineMessage('hydranium/core/no-such-path', 'No such file or directory: {uri}');
+
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
  *
@@ -127,7 +137,7 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       }
       const content = this.files.get(normalize(uri));
       if (content === undefined) {
-         throw new Error(`No such file: ${uri.toString()}`);
+         throw new Error(NO_SUCH_FILE.format({ uri: uri.toString() }));
       }
       return content;
    }
@@ -152,7 +162,7 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       if (this.hasChildren(path)) {
          return { isFile: false, isDirectory: true, uri };
       }
-      throw new Error(`No such file or directory: ${uri.toString()}`);
+      throw new Error(NO_SUCH_PATH.format({ uri: uri.toString() }));
    }
 
    exists(uri: URI): Promise<boolean> {

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 });
 }