@x18n/lsp 0.0.2 → 0.0.3

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,8 @@
+import { t as setupServer } from "./src.mjs";
+import { ProposedFeatures, createConnection } from "vscode-languageserver/node";
+//#region src/cli.ts
+const connection = createConnection(ProposedFeatures.all);
+setupServer(connection);
+connection.listen();
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,170 @@
+import { OverlayHost, Project } from "@x18n/core";
+import { NodeHost } from "@x18n/node";
+import { Connection } from "vscode-languageserver";
+//#region src/protocol.d.ts
+/**
+ * The `x18n/*` custom protocol. Shapes are versioned with the JSON contract (`contractVersion` in `@x18n/core`).
+ * Positions and ranges use LSP conventions (zero-based lines, UTF-16 characters).
+ */
+export interface Position {
+  readonly line: number;
+  readonly character: number;
+}
+export interface Range {
+  readonly start: Position;
+  readonly end: Position;
+}
+export interface Location {
+  readonly uri: string;
+  readonly range: Range;
+}
+export interface DocumentParams {
+  readonly uri: string;
+}
+export interface PositionParams extends DocumentParams {
+  readonly position: Position;
+}
+export interface ProjectInfo {
+  readonly name: string;
+  readonly root: string;
+  readonly sourceLocale: string;
+  readonly locales: readonly {
+    readonly code: string;
+    readonly displayName: string | undefined;
+    readonly flag: string | undefined;
+  }[];
+  readonly displayLocale: string;
+  readonly keys: number;
+}
+export interface KeyAtResult {
+  readonly project: string;
+  readonly key: string;
+  readonly type: "key" | "subtree";
+  readonly range: Range;
+}
+export interface TreeParams {
+  readonly project?: string | undefined;
+  /** Parent key; omitted for the roots. */
+  readonly parent?: string | undefined;
+}
+export interface TreeNode {
+  readonly key: string;
+  readonly label: string;
+  readonly leaf: boolean;
+  readonly translated: number;
+  readonly total: number;
+  /** Display-locale value for leaves. */
+  readonly value: string | undefined;
+}
+export interface LocaleProgress {
+  readonly locale: string;
+  readonly translated: number;
+  readonly total: number;
+  readonly missing: readonly string[];
+  readonly empty: readonly string[];
+}
+export interface ProgressResult {
+  readonly projects: readonly {
+    readonly name: string;
+    readonly locales: readonly LocaleProgress[];
+  }[];
+}
+export interface FileKey {
+  readonly key: string;
+  readonly range: Range;
+  readonly value: string | undefined;
+  readonly missing: boolean;
+  readonly dynamic: boolean;
+}
+export interface FileKeysResult {
+  readonly keys: readonly FileKey[];
+  readonly hardStrings: readonly {
+    readonly text: string;
+    readonly range: Range;
+  }[];
+}
+export interface UsageReportResult {
+  readonly unused: readonly {
+    readonly project: string;
+    readonly key: string;
+    readonly location: Location | undefined;
+  }[];
+  readonly missing: readonly {
+    readonly project: string;
+    readonly key: string;
+    readonly locations: readonly Location[];
+  }[];
+}
+export interface Decoration {
+  readonly range: Range;
+  readonly key: string;
+  readonly value: string | undefined;
+  readonly state: "ok" | "missing" | "dynamic";
+}
+export interface DecorationsResult {
+  readonly locale: string;
+  readonly decorations: readonly Decoration[];
+}
+export interface SetDisplayLocaleParams {
+  readonly locale: string | undefined;
+}
+export interface OpenUiParams {
+  readonly project?: string | undefined;
+}
+export interface OpenUiResult {
+  readonly url: string;
+  readonly token: string;
+}
+export interface TranslatePromptParams {
+  readonly project?: string | undefined;
+  readonly locale: string;
+  readonly keys?: readonly string[] | undefined;
+}
+export interface ChangedParams {
+  readonly project: string;
+  readonly revision: number;
+  readonly keys: readonly string[];
+}
+export interface Methods {
+  readonly projects: "x18n/projects";
+  readonly keyAt: "x18n/keyAt";
+  readonly tree: "x18n/tree";
+  readonly progress: "x18n/progress";
+  readonly fileKeys: "x18n/fileKeys";
+  readonly usageReport: "x18n/usageReport";
+  readonly decorations: "x18n/decorations";
+  readonly setDisplayLocale: "x18n/setDisplayLocale";
+  readonly openUi: "x18n/openUi";
+  readonly translatePrompt: "x18n/translatePrompt";
+  readonly changed: "x18n/changed";
+}
+export declare const methods: Methods;
+/** Commands for `workspace/executeCommand`. */
+export interface Commands {
+  readonly set: "x18n.set";
+  readonly delete: "x18n.delete";
+  readonly renamePrefix: "x18n.renamePrefix";
+  readonly extract: "x18n.extract";
+  /** `{ uri: <folder> }` -> `{ files: { path, content }[], notes, removable }`; nothing is written. */
+  readonly migrateI18nAlly: "x18n.migrateI18nAlly";
+}
+export declare const commands: Commands;
+//#endregion
+//#region src/server.d.ts
+interface ServerProject {
+  readonly name: string;
+  /** Absolute root. */
+  readonly root: string;
+  readonly project: Project;
+  readonly overlay: OverlayHost;
+}
+interface ServerOptions {
+  /** Loads the projects of a workspace folder. Default: `@x18n/node` with an overlay host. */
+  readonly loadProjects?: ((folder: string, wrapHost: (host: NodeHost) => OverlayHost) => Promise<readonly Omit<ServerProject, "overlay">[]>) | undefined;
+  /** Starts the UI server for a project (`x18n/openUi`). */
+  readonly openUi?: ((project: ServerProject) => Promise<OpenUiResult>) | undefined;
+}
+/** Registers the x18n handlers on a connection. The caller owns transport and `listen()`. */
+export declare function setupServer(connection: Connection, options?: ServerOptions): void;
+//#endregion
+export type { ServerOptions, ServerProject };

package/dist/index.mjs

@@ -0,0 +1 @@
+export { n as commands, r as methods, t as setupServer } from "./src.mjs";

package/dist/src.mjs

@@ -0,0 +1,870 @@
+import { relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { extractItems, findCandidates } from "@x18n/builtins/extractors";
+import { createLineIndex, createOverlayHost, isX18nError, renderPrompt } from "@x18n/core";
+import { loadWorkspace, migrateI18nAlly } from "@x18n/node";
+import { CodeActionKind, CompletionItemKind, DiagnosticSeverity, DidChangeWatchedFilesNotification, FileChangeType, ResponseError, SymbolKind, TextDocumentSyncKind, TextDocuments } from "vscode-languageserver";
+import { TextDocument } from "vscode-languageserver-textdocument";
+//#region src/protocol.ts
+const methods = {
+	projects: "x18n/projects",
+	keyAt: "x18n/keyAt",
+	tree: "x18n/tree",
+	progress: "x18n/progress",
+	fileKeys: "x18n/fileKeys",
+	usageReport: "x18n/usageReport",
+	decorations: "x18n/decorations",
+	setDisplayLocale: "x18n/setDisplayLocale",
+	openUi: "x18n/openUi",
+	translatePrompt: "x18n/translatePrompt",
+	changed: "x18n/changed"
+};
+const commands = {
+	set: "x18n.set",
+	delete: "x18n.delete",
+	renamePrefix: "x18n.renamePrefix",
+	extract: "x18n.extract",
+	migrateI18nAlly: "x18n.migrateI18nAlly"
+};
+//#endregion
+//#region package.json
+var version = "0.0.3";
+//#endregion
+//#region src/server.ts
+const severities = {
+	error: DiagnosticSeverity.Error,
+	warning: DiagnosticSeverity.Warning,
+	info: DiagnosticSeverity.Information,
+	hint: DiagnosticSeverity.Hint
+};
+function truncate(text, max) {
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function display(value) {
+	return value === void 0 ? void 0 : typeof value === "string" ? value : JSON.stringify(value);
+}
+const posix = (path) => sep === "\\" ? path.replace(/\\/g, "/") : path;
+var Server = class {
+	connection;
+	options;
+	documents = new TextDocuments(TextDocument);
+	projects = [];
+	published = /* @__PURE__ */ new Map();
+	timers = /* @__PURE__ */ new Map();
+	settings = {
+		annotationMaxLength: 40,
+		displayLocale: void 0,
+		codeLens: false
+	};
+	ready = Promise.resolve();
+	folders = [];
+	watchRegistration = false;
+	constructor(connection, options) {
+		this.connection = connection;
+		this.options = options;
+	}
+	/** ---- Paths and positions ---- */
+	locate(uri) {
+		if (!uri.startsWith("file:")) return void 0;
+		const file = fileURLToPath(uri);
+		let best;
+		for (const entry of this.projects) {
+			const rel = relative(entry.root, file);
+			if (!rel.startsWith("..") && !resolve(entry.root, rel).startsWith("..") && (!best || entry.root.length > best.root.length)) best = entry;
+		}
+		return best ? {
+			entry: best,
+			path: posix(relative(best.root, file))
+		} : void 0;
+	}
+	uriOf(entry, path) {
+		return pathToFileURL(resolve(entry.root, path)).href;
+	}
+	text(entry, path) {
+		return this.documents.get(this.uriOf(entry, path))?.getText() ?? entry.project.text(path) ?? "";
+	}
+	range(entry, path, range) {
+		const index = createLineIndex(this.text(entry, path));
+		return {
+			start: index.position(range.start),
+			end: index.position(range.end)
+		};
+	}
+	offset(uri, position, entry, path) {
+		const document = this.documents.get(uri);
+		return document ? document.offsetAt(position) : createLineIndex(this.text(entry, path)).offset(position);
+	}
+	location(entry, path, range) {
+		return {
+			uri: this.uriOf(entry, path),
+			range: this.range(entry, path, range)
+		};
+	}
+	at(params) {
+		const found = this.locate(params.textDocument.uri);
+		if (!found) return void 0;
+		return {
+			...found,
+			offset: this.offset(params.textDocument.uri, params.position, found.entry, found.path)
+		};
+	}
+	displayLocale(entry) {
+		const wanted = this.settings.displayLocale;
+		return wanted && entry.project.locales.includes(wanted) ? wanted : entry.project.sourceLocale;
+	}
+	resourcePath(entry, id) {
+		return entry.project.resources.find((r) => r.id === id)?.path ?? id;
+	}
+	/** ---- Lifecycle ---- */
+	async load() {
+		for (const folder of this.folders) {
+			const overlays = [];
+			const wrap = (host) => {
+				const overlay = createOverlayHost(host);
+				overlays.push(overlay);
+				return overlay;
+			};
+			(this.options.loadProjects ? await this.options.loadProjects(folder, wrap) : (await loadWorkspace({
+				cwd: folder,
+				wrapHost: wrap
+			}).catch((error) => {
+				this.connection.window.showWarningMessage(`x18n: ${error instanceof Error ? error.message : String(error)}`);
+				return { projects: [] };
+			})).projects).forEach((item, i) => {
+				const overlay = overlays[i];
+				if (overlay && !this.projects.some((p) => p.root === item.root)) this.projects.push({
+					name: item.name,
+					root: item.root,
+					project: item.project,
+					overlay
+				});
+			});
+		}
+		for (const entry of this.projects) entry.project.onChange((change) => {
+			this.connection.sendNotification(methods.changed, {
+				project: entry.name,
+				revision: change.revision,
+				keys: change.keys
+			});
+			this.publishDiagnostics();
+		});
+	}
+	async initialize(params) {
+		const folders = params.workspaceFolders?.map((folder) => fileURLToPath(folder.uri)) ?? (params.rootUri ? [fileURLToPath(params.rootUri)] : []);
+		this.folders = folders;
+		this.watchRegistration = params.capabilities.workspace?.didChangeWatchedFiles?.dynamicRegistration === true;
+		const settings = params.initializationOptions;
+		if (typeof settings?.displayLocale === "string") this.settings.displayLocale = settings.displayLocale;
+		if (typeof settings?.annotationMaxLength === "number") this.settings.annotationMaxLength = settings.annotationMaxLength;
+		if (typeof settings?.codeLens === "boolean") this.settings.codeLens = settings.codeLens;
+		return {
+			serverInfo: {
+				name: "x18n",
+				version
+			},
+			capabilities: {
+				textDocumentSync: TextDocumentSyncKind.Incremental,
+				definitionProvider: true,
+				implementationProvider: true,
+				referencesProvider: true,
+				renameProvider: { prepareProvider: true },
+				hoverProvider: true,
+				inlayHintProvider: true,
+				completionProvider: { triggerCharacters: [
+					".",
+					"'",
+					"\"",
+					"`",
+					":"
+				] },
+				codeActionProvider: { codeActionKinds: [CodeActionKind.QuickFix, CodeActionKind.RefactorExtract] },
+				documentSymbolProvider: true,
+				workspaceSymbolProvider: true,
+				codeLensProvider: { resolveProvider: false },
+				executeCommandProvider: { commands: Object.values(commands) }
+			}
+		};
+	}
+	async initialized() {
+		const progress = await this.connection.window.createWorkDoneProgress().catch(() => void 0);
+		progress?.begin("x18n", 0, "Indexing keys and usages", false);
+		this.ready = this.load().finally(() => progress?.done());
+		await this.ready;
+		this.publishDiagnostics();
+		if (this.watchRegistration) this.connection.client.register(DidChangeWatchedFilesNotification.type, { watchers: [{ globPattern: "**/*" }] }).catch(() => void 0);
+	}
+	/** ---- Document sync ---- */
+	schedule(uri, run) {
+		clearTimeout(this.timers.get(uri));
+		this.timers.set(uri, setTimeout(() => {
+			this.timers.delete(uri);
+			run();
+		}, 100));
+	}
+	async changed(uri, text) {
+		await this.ready;
+		const found = this.locate(uri);
+		if (!found) return;
+		if (text === void 0) found.entry.overlay.clearOverlay(found.path);
+		else found.entry.overlay.setOverlay(found.path, text);
+		await found.entry.project.update([{
+			type: "change",
+			path: found.path
+		}]);
+	}
+	async watched(changes) {
+		await this.ready;
+		const byProject = /* @__PURE__ */ new Map();
+		for (const change of changes) {
+			const found = this.locate(change.uri);
+			if (!found || found.path.startsWith("node_modules/") || found.path.includes("/node_modules/") || this.documents.get(change.uri)) continue;
+			const list = byProject.get(found.entry) ?? [];
+			byProject.set(found.entry, list);
+			list.push({
+				type: change.type === FileChangeType.Created ? "create" : change.type === FileChangeType.Deleted ? "delete" : "change",
+				path: found.path
+			});
+		}
+		for (const [entry, events] of byProject) await entry.project.update(events);
+	}
+	publishDiagnostics() {
+		for (const entry of this.projects) {
+			const byFile = /* @__PURE__ */ new Map();
+			for (const d of entry.project.analyze().diagnostics) {
+				if (!d.location) continue;
+				const uri = this.uriOf(entry, d.location.path);
+				const list = byFile.get(uri) ?? [];
+				byFile.set(uri, list);
+				list.push({
+					range: this.range(entry, d.location.path, d.location.range),
+					severity: severities[d.severity],
+					code: d.code,
+					source: "x18n",
+					message: d.message,
+					data: {
+						key: d.key,
+						locale: d.locale
+					}
+				});
+			}
+			const previous = this.published.get(entry.root) ?? /* @__PURE__ */ new Set();
+			for (const uri of previous) if (!byFile.has(uri)) this.connection.sendDiagnostics({
+				uri,
+				diagnostics: []
+			});
+			for (const [uri, diagnostics] of byFile) this.connection.sendDiagnostics({
+				uri,
+				diagnostics
+			});
+			this.published.set(entry.root, new Set(byFile.keys()));
+		}
+	}
+	/** ---- Symbols ---- */
+	entryLocation(entry, node) {
+		return this.location(entry, node.path, node.range.key);
+	}
+	async definition(params) {
+		await this.ready;
+		const at = this.at(params);
+		const target = at && at.entry.project.keyAt(at.path, at.offset);
+		if (!at || !target) return null;
+		const nodes = at.entry.project.locations(target.key);
+		const source = nodes.find((node) => node.locale === at.entry.project.sourceLocale) ?? nodes[0];
+		return source ? [this.entryLocation(at.entry, source)] : null;
+	}
+	async implementation(params) {
+		await this.ready;
+		const at = this.at(params);
+		const target = at && at.entry.project.keyAt(at.path, at.offset);
+		if (!at || !target) return null;
+		return at.entry.project.locations(target.key).map((node) => this.entryLocation(at.entry, node));
+	}
+	async references(params) {
+		await this.ready;
+		const at = this.at(params);
+		const target = at && at.entry.project.keyAt(at.path, at.offset);
+		if (!at || !target) return null;
+		const { project } = at.entry;
+		const usages = (target.type === "subtree" ? project.usages({ prefix: target.key }) : project.usages({ key: target.key })).map((m) => this.location(at.entry, m.usage.path, m.usage.range));
+		const entries = params.context.includeDeclaration || target.source === "usage" ? project.locations(target.key).map((node) => this.entryLocation(at.entry, node)) : [];
+		return [...usages, ...entries];
+	}
+	async prepareRename(params) {
+		await this.ready;
+		const at = this.at(params);
+		const target = at && at.entry.project.keyAt(at.path, at.offset);
+		if (!at || !target) return null;
+		return {
+			range: this.range(at.entry, at.path, target.range),
+			placeholder: target.key
+		};
+	}
+	async rename(params) {
+		await this.ready;
+		const at = this.at(params);
+		const target = at && at.entry.project.keyAt(at.path, at.offset);
+		if (!at || !target) return null;
+		const { project } = at.entry;
+		const to = project.parseKey(params.newName.trim());
+		const op = target.type === "subtree" ? {
+			type: "rename-prefix",
+			from: target.key,
+			to
+		} : {
+			type: "rename",
+			from: target.key,
+			to
+		};
+		const plan = this.plan(project, [op]);
+		if (plan.warnings.length) this.connection.window.showWarningMessage(`x18n: ${plan.warnings.join(" ")}`);
+		return this.workspaceEdit(at.entry, plan);
+	}
+	plan(project, ops) {
+		try {
+			return project.plan(ops);
+		} catch (error) {
+			throw new ResponseError(1, isX18nError(error) ? `${error.message}. ${error.hint}` : String(error));
+		}
+	}
+	workspaceEdit(entry, plan) {
+		const documentChanges = [];
+		const toEdit = (change) => {
+			const uri = this.uriOf(entry, change.path);
+			if (change.type === "create") {
+				documentChanges.push({
+					kind: "create",
+					uri,
+					options: { ignoreIfExists: true }
+				});
+				documentChanges.push({
+					textDocument: {
+						uri,
+						version: null
+					},
+					edits: [{
+						range: {
+							start: {
+								line: 0,
+								character: 0
+							},
+							end: {
+								line: 0,
+								character: 0
+							}
+						},
+						newText: change.content
+					}]
+				});
+			} else if (change.type === "delete") documentChanges.push({
+				kind: "delete",
+				uri
+			});
+			else documentChanges.push({
+				textDocument: {
+					uri,
+					version: this.documents.get(uri)?.version ?? null
+				},
+				edits: change.edits.map((edit) => ({
+					range: this.range(entry, change.path, edit.range),
+					newText: edit.text
+				}))
+			});
+		};
+		plan.changes.forEach(toEdit);
+		return { documentChanges };
+	}
+	/** ---- Editor features ---- */
+	async hover(params) {
+		await this.ready;
+		const at = this.at(params);
+		const target = at && at.entry.project.keyAt(at.path, at.offset);
+		if (!at || !target) return null;
+		const { project } = at.entry;
+		const lines = [`**x18n** \`${target.key}\``, ""];
+		if (target.type === "key") {
+			lines.push("| | |", "| --- | --- |");
+			for (const locale of project.locales) {
+				const value = display(project.lookup(target.key, locale)?.value);
+				lines.push(`| ${project.localeInfo(locale).flag ?? ""} ${locale} | ${value === void 0 ? "_missing_" : value === "" ? "_empty_" : value.replace(/\|/g, "\\|").replace(/\n/g, " ")} |`);
+			}
+		}
+		const usages = target.type === "subtree" ? project.usages({ prefix: target.key }) : project.usages({ key: target.key });
+		const args = encodeURIComponent(JSON.stringify([{
+			project: at.entry.name,
+			key: target.key
+		}]));
+		lines.push("", `${usages.length} usage${usages.length === 1 ? "" : "s"} · [Open in UI](command:x18n.openKey?${args}) · [Copy translate prompt](command:x18n.copyTranslatePrompt?${args})`);
+		return {
+			contents: {
+				kind: "markdown",
+				value: lines.join("\n")
+			},
+			range: this.range(at.entry, at.path, target.range)
+		};
+	}
+	async inlayHints(params) {
+		await this.ready;
+		const found = this.locate(params.textDocument.uri);
+		if (!found) return [];
+		const { entry, path } = found;
+		const locale = this.displayLocale(entry);
+		const index = createLineIndex(this.text(entry, path));
+		const start = index.offset(params.range.start);
+		const end = index.offset(params.range.end);
+		const hints = [];
+		for (const { usage } of entry.project.usages({ path })) {
+			if (usage.key === void 0 || usage.dynamic !== false || usage.range.start < start || usage.range.end > end) continue;
+			const value = display(entry.project.lookup(usage.key, locale)?.value);
+			hints.push({
+				position: index.position(usage.range.end + 1),
+				label: value === void 0 ? " ⚠ missing" : ` ${truncate(value, this.settings.annotationMaxLength)}`,
+				paddingLeft: true
+			});
+		}
+		return hints;
+	}
+	async completion(params) {
+		await this.ready;
+		const at = this.at(params);
+		if (!at) return [];
+		const { project } = at.entry;
+		const slot = project.keySlots(at.path).find((range) => at.offset >= range.start && at.offset <= range.end);
+		if (!slot) return [];
+		const usage = project.usages({ path: at.path }).map((m) => m.usage).find((u) => u.range.start === slot.start);
+		const scopeNs = usage?.scopeNamespace ?? project.config.namespace.default;
+		const prefix = usage?.scopePrefix ? `${usage.scopePrefix}.` : "";
+		const range = this.range(at.entry, at.path, slot);
+		return project.keys().flatMap((key) => {
+			let insert = key;
+			if (project.namespaced && key.startsWith(`${scopeNs}:`)) insert = key.slice(scopeNs.length + 1);
+			if (prefix) {
+				if (!insert.startsWith(prefix)) return [];
+				insert = insert.slice(prefix.length);
+			}
+			const source = display(project.lookup(key, project.sourceLocale)?.value);
+			return [{
+				label: insert,
+				kind: CompletionItemKind.Text,
+				...source === void 0 ? {} : { detail: source },
+				textEdit: {
+					range,
+					newText: insert
+				},
+				filterText: insert
+			}];
+		});
+	}
+	async codeActions(params) {
+		await this.ready;
+		const found = this.locate(params.textDocument.uri);
+		if (!found) return [];
+		const { entry, path } = found;
+		const index = createLineIndex(this.text(entry, path));
+		const start = index.offset(params.range.start);
+		const end = index.offset(params.range.end);
+		const actions = [];
+		for (const d of entry.project.analyze().diagnostics) {
+			if (!d.location || d.location.path !== path || d.location.range.end < start || d.location.range.start > end) continue;
+			for (const fix of d.fixes) try {
+				actions.push({
+					title: fix.title,
+					kind: CodeActionKind.QuickFix,
+					edit: this.workspaceEdit(entry, entry.project.plan(fix.ops))
+				});
+			} catch {}
+		}
+		return [...actions, ...this.extractActions(entry, path, start, end)];
+	}
+	extractActions(entry, path, start, end) {
+		const { project } = entry;
+		if (project.nodes(path).length > 0) return [];
+		const candidates = findCandidates(project, { files: [path] });
+		const inRange = candidates.filter((c) => c.range.start <= end && c.range.end >= start);
+		const actions = [];
+		const edit = (list) => {
+			try {
+				return this.workspaceEdit(entry, project.plan([{
+					type: "extract",
+					items: extractItems(project, list)
+				}]));
+			} catch {
+				return;
+			}
+		};
+		const text = this.text(entry, path);
+		const index = createLineIndex(text);
+		for (const candidate of inRange) {
+			const extracted = edit([candidate]);
+			if (extracted) actions.push({
+				title: `Extract "${truncate(candidate.text, 30)}" to ${candidate.key}`,
+				kind: CodeActionKind.RefactorExtract,
+				edit: extracted
+			});
+			const line = index.position(candidate.range.start).line;
+			const indent = /^\s*/.exec(index.line(line))?.[0] ?? "";
+			const comment = /-(?:text|attribute)$/.test(candidate.kind) && !candidate.kind.startsWith("js") ? "<!-- x18n-ignore -->" : "// x18n-ignore";
+			actions.push({
+				title: `Ignore "${truncate(candidate.text, 30)}"`,
+				kind: CodeActionKind.QuickFix,
+				edit: { changes: { [this.uriOf(entry, path)]: [{
+					range: {
+						start: {
+							line,
+							character: 0
+						},
+						end: {
+							line,
+							character: 0
+						}
+					},
+					newText: `${indent}${comment}\n`
+				}] } }
+			});
+		}
+		if (inRange.length > 0 && candidates.length > 1) {
+			const all = edit(candidates);
+			if (all) actions.push({
+				title: `Extract all ${candidates.length} hard strings in this file`,
+				kind: CodeActionKind.RefactorExtract,
+				edit: all
+			});
+		}
+		return actions;
+	}
+	async documentSymbols(params) {
+		await this.ready;
+		const found = this.locate(params.textDocument.uri);
+		if (!found) return [];
+		const { entry, path } = found;
+		const roots = [];
+		const stack = [];
+		for (const node of entry.project.nodes(path)) {
+			while (stack.length && !node.key.startsWith(`${stack.at(-1).key}.`)) stack.pop();
+			const parentKey = stack.at(-1)?.key;
+			const symbol = {
+				name: parentKey ? node.key.slice(parentKey.length + 1) : node.key,
+				detail: node.leaf ? display(entry.project.message(node.key, node.locale)?.value) ?? "" : "",
+				kind: node.leaf ? SymbolKind.String : SymbolKind.Namespace,
+				range: this.range(entry, path, {
+					start: node.range.key.start,
+					end: Math.max(node.range.value.end, node.range.key.end)
+				}),
+				selectionRange: this.range(entry, path, node.range.key),
+				children: []
+			};
+			if (stack.length) stack.at(-1).symbol.children.push(symbol);
+			else roots.push(symbol);
+			if (!node.leaf) stack.push({
+				key: node.key,
+				symbol
+			});
+		}
+		return roots;
+	}
+	async workspaceSymbols(params) {
+		await this.ready;
+		const query = params.query.toLowerCase();
+		const out = [];
+		for (const entry of this.projects) for (const key of entry.project.keys()) {
+			const value = display(entry.project.message(key, entry.project.sourceLocale)?.value) ?? "";
+			if (query && !key.toLowerCase().includes(query) && !value.toLowerCase().includes(query)) continue;
+			const node = entry.project.locations(key)[0];
+			if (node) out.push({
+				name: key,
+				kind: SymbolKind.String,
+				containerName: value,
+				location: this.entryLocation(entry, node)
+			});
+			if (out.length >= 500) return out;
+		}
+		return out;
+	}
+	async codeLenses(params) {
+		await this.ready;
+		const found = this.locate(params.textDocument.uri);
+		if (!this.settings.codeLens || !found) return [];
+		const { entry, path } = found;
+		return entry.project.nodes(path).filter((node) => node.leaf).map((node) => {
+			const info = entry.project.get(node.key);
+			const used = info?.usages.length ?? 0;
+			const missing = info?.missing ?? [];
+			const title = `used ${used} time${used === 1 ? "" : "s"}${missing.length ? ` · missing in ${missing.join(", ")}` : ""}`;
+			return {
+				range: this.range(entry, path, node.range.key),
+				command: {
+					title,
+					command: ""
+				}
+			};
+		});
+	}
+	async executeCommand(params) {
+		await this.ready;
+		const arg = params.arguments?.[0];
+		if (typeof arg !== "object" || arg === null) return null;
+		const input = arg;
+		if (params.command === commands.extract && typeof input.uri === "string") return this.extractFile(input.uri);
+		if (params.command === commands.migrateI18nAlly && typeof input.uri === "string") return migrateI18nAlly(fileURLToPath(input.uri));
+		const entry = this.projects.find((p) => p.name === input.project) ?? this.projects[0];
+		if (!entry || typeof input.key !== "string") return null;
+		const key = entry.project.parseKey(input.key);
+		let op;
+		if (params.command === commands.set && typeof input.value === "string") op = {
+			type: "set",
+			key,
+			locale: input.locale ?? entry.project.sourceLocale,
+			value: input.value
+		};
+		else if (params.command === commands.delete) op = {
+			type: "delete",
+			key,
+			locales: input.locale ? [input.locale] : "all"
+		};
+		else if (params.command === commands.renamePrefix && typeof input.to === "string") op = {
+			type: "rename-prefix",
+			from: key,
+			to: entry.project.parseKey(input.to)
+		};
+		if (!op) return null;
+		const edit = this.workspaceEdit(entry, this.plan(entry.project, [op]));
+		await this.connection.workspace.applyEdit(edit);
+		return edit;
+	}
+	async extractFile(uri) {
+		const found = this.locate(uri);
+		if (!found) return null;
+		const { entry, path } = found;
+		const candidates = findCandidates(entry.project, { files: [path] });
+		if (candidates.length === 0) return null;
+		const edit = this.workspaceEdit(entry, this.plan(entry.project, [{
+			type: "extract",
+			items: extractItems(entry.project, candidates)
+		}]));
+		await this.connection.workspace.applyEdit(edit);
+		return edit;
+	}
+	/** ---- Custom protocol ---- */
+	entryByName(name) {
+		return name === void 0 ? this.projects[0] : this.projects.find((p) => p.name === name);
+	}
+	projectInfos() {
+		return this.projects.map((entry) => ({
+			name: entry.name,
+			root: entry.root,
+			sourceLocale: entry.project.sourceLocale,
+			locales: entry.project.locales.map((code) => ({
+				code,
+				displayName: entry.project.localeInfo(code).displayName,
+				flag: entry.project.localeInfo(code).flag
+			})),
+			displayLocale: this.displayLocale(entry),
+			keys: entry.project.keys().length
+		}));
+	}
+	async keyAt(params) {
+		await this.ready;
+		const at = this.at({
+			textDocument: { uri: params.uri },
+			position: params.position
+		});
+		const target = at && at.entry.project.keyAt(at.path, at.offset);
+		if (!at || !target) return null;
+		return {
+			project: at.entry.name,
+			key: target.key,
+			type: target.type,
+			range: this.range(at.entry, at.path, target.range)
+		};
+	}
+	tree(params) {
+		const entry = this.entryByName(params.project);
+		if (!entry) return [];
+		const { project } = entry;
+		const locale = this.displayLocale(entry);
+		const parent = params.parent;
+		const children = /* @__PURE__ */ new Map();
+		for (const key of project.keys()) {
+			if (parent !== void 0 && !key.startsWith(project.namespaced && parent.endsWith(":") ? parent : `${parent}.`)) continue;
+			const rest = parent === void 0 ? key : key.slice(parent.length + (parent.endsWith(":") ? 0 : 1));
+			const segment = (parent === void 0 && project.namespaced ? rest.slice(0, rest.indexOf(":") + 1) : "") || rest.split(".")[0];
+			const child = parent === void 0 ? segment : `${parent}${parent.endsWith(":") ? "" : "."}${segment}`;
+			const list = children.get(child) ?? [];
+			children.set(child, list);
+			list.push(key);
+		}
+		const others = project.locales.filter((l) => l !== project.sourceLocale);
+		return [...children].map(([key, keys]) => {
+			const leaf = keys.length === 1 && keys[0] === key;
+			const filled = (k, l) => !["", void 0].includes(display(project.message(k, l)?.value));
+			const translated = keys.reduce((sum, k) => sum + others.filter((l) => filled(k, l)).length, 0);
+			return {
+				key,
+				label: key.slice((parent?.length ?? -1) + 1).replace(/:$/, "") || key,
+				leaf,
+				translated,
+				total: keys.length * others.length,
+				value: leaf ? display(project.message(key, locale)?.value) : void 0
+			};
+		});
+	}
+	progress() {
+		return { projects: this.projects.map((entry) => ({
+			name: entry.name,
+			locales: entry.project.analyze().coverage.map((c) => ({
+				locale: c.locale,
+				translated: c.translated,
+				total: c.total,
+				missing: c.missing,
+				empty: c.empty
+			}))
+		})) };
+	}
+	async fileKeys(params) {
+		await this.ready;
+		const found = this.locate(params.uri);
+		if (!found) return {
+			keys: [],
+			hardStrings: []
+		};
+		const { entry, path } = found;
+		const locale = this.displayLocale(entry);
+		return {
+			keys: entry.project.nodes(path).length > 0 ? entry.project.nodes(path).filter((n) => n.leaf).map((n) => ({
+				key: n.key,
+				range: this.range(entry, path, n.range.key),
+				value: display(entry.project.message(n.key, locale)?.value),
+				missing: entry.project.get(n.key).missing.length > 0,
+				dynamic: false
+			})) : entry.project.usages({ path }).flatMap(({ usage }) => usage.key === void 0 ? [] : [{
+				key: usage.key,
+				range: this.range(entry, path, usage.range),
+				value: display(entry.project.lookup(usage.key, locale)?.value),
+				missing: usage.dynamic === false && entry.project.lookup(usage.key, entry.project.sourceLocale) === void 0,
+				dynamic: usage.dynamic !== false
+			}]),
+			hardStrings: entry.project.hardStrings(path).map((h) => ({
+				text: h.text,
+				range: this.range(entry, path, h.range)
+			}))
+		};
+	}
+	usageReport() {
+		const unused = [];
+		const missing = [];
+		for (const entry of this.projects) {
+			const analysis = entry.project.analyze();
+			for (const key of analysis.unused) {
+				const node = entry.project.locations(key)[0];
+				unused.push({
+					project: entry.name,
+					key,
+					location: node ? this.entryLocation(entry, node) : void 0
+				});
+			}
+			const byKey = /* @__PURE__ */ new Map();
+			for (const usage of analysis.undefinedUsages) {
+				const list = byKey.get(usage.key) ?? [];
+				byKey.set(usage.key, list);
+				list.push(this.location(entry, usage.path, usage.range));
+			}
+			for (const [key, locations] of byKey) missing.push({
+				project: entry.name,
+				key,
+				locations
+			});
+		}
+		return {
+			unused,
+			missing
+		};
+	}
+	async decorations(params) {
+		await this.ready;
+		const found = this.locate(params.uri);
+		if (!found || found.entry.project.nodes(found.path).length > 0) return {
+			locale: this.settings.displayLocale ?? "",
+			decorations: []
+		};
+		const { entry, path } = found;
+		const locale = this.displayLocale(entry);
+		return {
+			locale,
+			decorations: entry.project.usages({ path }).flatMap(({ usage }) => {
+				if (usage.key === void 0) return [];
+				const value = display(entry.project.lookup(usage.key, locale)?.value);
+				const state = usage.dynamic !== false ? "dynamic" : value === void 0 ? "missing" : "ok";
+				return [{
+					range: this.range(entry, path, usage.range),
+					key: usage.key,
+					value,
+					state
+				}];
+			})
+		};
+	}
+};
+/** Registers the x18n handlers on a connection. The caller owns transport and `listen()`. */
+function setupServer(connection, options = {}) {
+	let ui;
+	const openUi = options.openUi ?? (async (entry) => (await (ui ??= import("./ui.mjs").then((m) => m.createUiServers(connection)))).open(entry));
+	connection.onShutdown(async () => {
+		await (await ui)?.close();
+	});
+	const server = new Server(connection, options);
+	server.documents.listen(connection);
+	connection.onInitialize((params) => server.initialize(params));
+	connection.onInitialized(() => void server.initialized());
+	server.documents.onDidChangeContent(({ document }) => server.schedule(document.uri, () => server.changed(document.uri, document.getText())));
+	server.documents.onDidClose(({ document }) => server.schedule(document.uri, () => server.changed(document.uri, void 0)));
+	connection.onDidChangeWatchedFiles((params) => void server.watched(params.changes));
+	connection.onDefinition((params) => server.definition(params));
+	connection.onImplementation((params) => server.implementation(params));
+	connection.onReferences((params) => server.references(params));
+	connection.onPrepareRename((params) => server.prepareRename(params));
+	connection.onRenameRequest((params) => server.rename(params));
+	connection.onHover((params) => server.hover(params));
+	connection.languages.inlayHint.on((params) => server.inlayHints(params));
+	connection.onCompletion((params) => server.completion(params));
+	connection.onCodeAction((params) => server.codeActions(params));
+	connection.onDocumentSymbol((params) => server.documentSymbols(params));
+	connection.onWorkspaceSymbol((params) => server.workspaceSymbols(params));
+	connection.onCodeLens((params) => server.codeLenses(params));
+	connection.onExecuteCommand((params) => server.executeCommand(params));
+	connection.onRequest(methods.projects, async () => {
+		await server.ready;
+		return server.projectInfos();
+	});
+	connection.onRequest(methods.keyAt, (params) => server.keyAt(params));
+	connection.onRequest(methods.tree, async (params) => {
+		await server.ready;
+		return server.tree(params ?? {});
+	});
+	connection.onRequest(methods.progress, async () => {
+		await server.ready;
+		return server.progress();
+	});
+	connection.onRequest(methods.fileKeys, (params) => server.fileKeys(params));
+	connection.onRequest(methods.usageReport, async () => {
+		await server.ready;
+		return server.usageReport();
+	});
+	connection.onRequest(methods.decorations, (params) => server.decorations(params));
+	connection.onNotification(methods.setDisplayLocale, (params) => {
+		server.settings.displayLocale = params.locale;
+		connection.languages.inlayHint.refresh().catch(() => void 0);
+	});
+	connection.onRequest(methods.openUi, async (params) => {
+		await server.ready;
+		const entry = server.entryByName(params?.project);
+		if (!entry) throw new ResponseError(1, `No project "${params?.project ?? ""}" in this server.`);
+		return openUi(entry);
+	});
+	connection.onRequest(methods.translatePrompt, async (params) => {
+		await server.ready;
+		const entry = server.entryByName(params.project);
+		if (!entry) throw new ResponseError(1, `Unknown project "${params.project}".`);
+		return renderPrompt(entry.project.prompt("translate", params.locale, { keys: params.keys }));
+	});
+}
+//#endregion
+export { commands as n, methods as r, setupServer as t };

package/dist/ui.mjs

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createX18nDevframe } from "@x18n/ui";
+import { createDevServer } from "devframe/adapters/dev";
+import { getTempAuthCodeInfo } from "devframe/node/auth";
+//#region src/ui.ts
+/**
+* One devframe dev server per project, on loopback, sharing the server's `Project`.
+* The token is devframe's one-time code: the webview passes it as the magic link
+* fragment (`#devframe_otp=<token>`), which the UI exchanges for a session.
+*/
+function createUiServers(connection) {
+	const servers = /* @__PURE__ */ new Map();
+	return {
+		async open(entry) {
+			let server = servers.get(entry);
+			if (!server) {
+				server = createDevServer(createX18nDevframe([entry], { openInEditor: async ({ path, line, column }) => {
+					const position = {
+						line: line - 1,
+						character: column - 1
+					};
+					await connection.window.showDocument({
+						uri: pathToFileURL(join(entry.root, path)).href,
+						takeFocus: true,
+						selection: {
+							start: position,
+							end: position
+						}
+					});
+				} }), {
+					host: "127.0.0.1",
+					port: 0,
+					auth: true,
+					openBrowser: false
+				});
+				servers.set(entry, server);
+			}
+			return {
+				url: `${(await server).origin}/`,
+				token: getTempAuthCodeInfo().code
+			};
+		},
+		async close() {
+			await Promise.all([...servers.values()].map(async (server) => (await server).close()));
+			servers.clear();
+		}
+	};
+}
+//#endregion
+export { createUiServers };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/lsp",
   "type": "module",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "x18n language server for any LSP editor",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -29,10 +29,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@x18n/builtins": "0.0.2",
-    "@x18n/core": "0.0.2",
-    "@x18n/node": "0.0.2",
-    "@x18n/ui": "0.0.2",
+    "@x18n/builtins": "0.0.3",
+    "@x18n/core": "0.0.3",
+    "@x18n/node": "0.0.3",
+    "@x18n/ui": "0.0.3",
     "devframe": "^1.2.5",
     "vscode-languageserver": "^10.1.2",
     "vscode-languageserver-textdocument": "^1.0.15"