@zhin.js/command 1.1.10 → 1.1.11

package/src/command-index.ts

@@ -5,10 +5,12 @@ import {
 } from 'segment-matcher';
 import {
   htmlRendererToken,
+  resolveLocale,
   type CapabilityId,
   type CapabilitySlot,
   type PluginId,
   type RuntimeSnapshot,
+  type Locale,
 } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
 import { bindOperationInput } from '@zhin.js/feature-kit';
@@ -17,8 +19,10 @@ import {
   type PermissionHost,
 } from '@zhin.js/permission';
 import { commandAdapterMatches, toCommandPermissionSubject } from './permission-explanation.js';
-import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp, type CommandValidationIssue } from './arguments.js';
-import { MENU_PAGE_SIZE, readMenuAppearance, renderCommandMenu, type CommandMenuSegment } from './command-menu.js';
+import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp, commandValidationIssue, type CommandValidationIssue } from './arguments.js';
+import { commandDescription, commandMessages } from './messages.js';
+import { MENU_PAGE_SIZE, readMenuAppearance, renderCommandMenu, type CommandMenuSegment, type CommandMenuEntry, type CommandMenuAppearance } from './command-menu.js';
+export type { CommandMenuEntry, CommandMenuAppearance } from './command-menu.js';
 import { admitCommandExecution, admitDirectCommandExecution } from './execution-runtime.js';
 import { CommandExecutionLimitedError, normalizeExecutionPolicy, type CommandExecutionLimit } from './execution-policy.js';
 export { CommandExecutionLimitedError } from './execution-policy.js';
@@ -63,7 +67,7 @@ export interface CommandDispatchResult {
   readonly command?: string;
   readonly owner?: PluginId;
   readonly value?: unknown;
-  readonly menu?: CommandMenuNavigation;
+  readonly menu?: CommandMenuPage;
 }
 
 /** Semantic menu navigation; the IM composition layer supplies platform controls. */
@@ -74,14 +78,28 @@ export interface CommandMenuNavigation {
   readonly pages: number;
 }
 
+/** Immutable page data; presentation cannot change the catalog or execute commands. */
+export interface CommandMenuPage extends CommandMenuNavigation {
+  readonly locale: Locale;
+  readonly title: string;
+  readonly commands: readonly CommandMenuEntry[];
+  readonly plugins: readonly CommandMenuEntry[];
+  readonly commandTotal: number;
+  readonly pluginTotal: number;
+  readonly hint?: string;
+  readonly text: string;
+  readonly appearance: CommandMenuAppearance;
+}
+
 interface CommandMenuResult {
   readonly value: string | CommandMenuSegment;
-  readonly menu?: CommandMenuNavigation;
+  readonly menu?: CommandMenuPage;
 }
 
 interface CommandRecord extends CommandDescriptor {
   readonly slot: Readonly<CapabilitySlot<CommandDefinition>>;
   readonly segments: readonly string[];
+  readonly preferredSegments: Readonly<Partial<Record<Locale, readonly string[]>>>;
   readonly parameter?: CommandParameterDefinition;
 }
 
@@ -121,7 +139,8 @@ const segmentFields = {
 };
 
 export interface CommandMenuConfig {
-  readonly keyword: string;
+  /** Omission selects the built-in keyword for each operation's language. */
+  readonly keyword?: string;
 }
 
 export class CommandIndex {
@@ -198,6 +217,8 @@ export class CommandIndex {
         ...(shortcutKeys && shortcutKeys.length > 0 ? { shortcut: shortcutKeys } : {}),
         slot,
         segments: Object.freeze(primarySegments),
+        preferredSegments: Object.freeze(Object.fromEntries(Object.entries(slot.definition.preferredAliasI18n ?? {}).map(([locale, entry]) =>
+          [locale, Object.freeze([...namespace, ...aliasRuntimeSegments(entry, primarySegments.slice(namespace.length))])]))),
         parameter,
       });
 
@@ -251,8 +272,30 @@ export class CommandIndex {
     this.#shortcuts = shortcuts;
   }
 
-  list(): readonly CommandDescriptor[] {
-    return this.#commands.map(toDescriptor);
+  list(locale: Locale = 'zh-CN'): readonly CommandDescriptor[] {
+    return this.#commands.map(record => ({ ...toDescriptor(record),
+      name: commandDisplayName(record, locale), usage: commandUsage(commandDisplayName(record, locale), record.slot.definition),
+      description: commandDescription(record.slot.definition, locale),
+      parameters: record.parameters.map(parameter => ({ ...parameter, description: commandDescription(parameter, locale) })),
+      options: Object.freeze(Object.fromEntries(Object.entries(record.options).map(([key, schema]) =>
+        [key, { ...schema, description: commandDescription(schema, locale) }]))),
+    }));
+  }
+
+  /** Resolve a local static route without executing parameters, permission checks or commands. */
+  formatCommand(owner: PluginId, localPath: string, prefix: string | undefined, locale: Locale = 'zh-CN'): string | undefined {
+    if (prefix === undefined || typeof localPath !== 'string') return undefined;
+    const path = localPath.trim().split(/\s+/u).filter(Boolean).join(' ');
+    if (!path) return undefined;
+    const command = this.#commands.find(record => record.owner === owner
+      && record.slot.localName.split('/').filter(segment => !segment.startsWith('$')).join(' ') === path);
+    return command ? prefix + commandDisplaySegments(command, locale).filter(segment => !segment.startsWith('$')).join(' ') : undefined;
+  }
+
+  /** Return the configured menu entry only when the calling environment is known. */
+  formatMenu(prefix: string | undefined, locale: Locale): string | undefined {
+    if (prefix === undefined || !this.#menu) return undefined;
+    return prefix + (this.#menu.keyword ?? commandMessages(locale, 'menuKeyword'));
   }
 
   has(name: string): boolean {
@@ -265,6 +308,7 @@ export class CommandIndex {
   }
 
   async execute(name: string, args: readonly string[] = [], operationSnapshot: RuntimeSnapshot = this.snapshot): Promise<unknown> {
+    const locale = commandLocale(undefined, operationSnapshot);
     const match = this.#match(name, false);
     if (!match) {
       this.#diagnoseParameter(name);
@@ -273,14 +317,14 @@ export class CommandIndex {
     if (!(await this.#permitAllows(match.command, undefined, operationSnapshot))) throw new Error(`Permission denied for Command: ${match.command.name}`);
     const definition = match.command.slot.definition;
     const supplied = [...match.remaining, ...(args.length > 0 ? [{ type: 'text', data: { text: args.join(' ') } }] : [])];
-    const parsed = parseCommandArguments(definition, supplied, resolveDynamicParams(match.params, undefined), {});
-    if (parsed.issues.length > 0) throw new CommandArgumentValidationError(parsed.issues, commandHelp(match.command.name, definition));
+    const parsed = parseCommandArguments(definition, supplied, resolveDynamicParams(match.params, undefined), {}, locale);
+    if (parsed.issues.length > 0) throw new CommandArgumentValidationError(parsed.issues, commandHelp(commandDisplayName(match.command, locale), definition, '', locale));
     // No inbound source: execution policy applies per command, never as a blanket refusal.
     const admission = admitDirectCommandExecution(match.command.slot.id, match.command.execution, operationSnapshot);
     if (admission.limit) throw new CommandExecutionLimitedError(admission.limit);
     try {
       return await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner,
-        textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options));
+        textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options, { locale }));
     } finally {
       admission.release();
     }
@@ -290,16 +334,20 @@ export class CommandIndex {
     input: CommandMatchInput,
     source: unknown = undefined,
     interactionFactory?: UserInteractionFactory,
-    commandPrefix = '',
+    commandPrefix?: string,
     operationSnapshot: RuntimeSnapshot = this.snapshot,
+    localeOverride?: Locale,
   ): Promise<CommandDispatchResult> {
+    const locale = localeOverride ?? commandLocale(source, operationSnapshot);
+    const prefix = commandPrefix ?? '';
     if (this.#menu) {
-      const menuResult = this.#dispatchMenu(input, commandPrefix, operationSnapshot);
+      const keyword = this.#menu.keyword ?? commandMessages(locale, 'menuKeyword');
+      const menuResult = this.#dispatchMenu(input, prefix, operationSnapshot, locale, keyword);
       if (menuResult !== undefined) {
         return Object.freeze({
           matched: true,
           status: 'executed',
-          command: this.#menu.keyword,
+          command: keyword,
           owner: operationSnapshot.root,
           ...menuResult,
         });
@@ -314,27 +362,29 @@ export class CommandIndex {
       if (!candidate) return Object.freeze({ matched: false, status: 'unmatched' });
       if (!commandAdapterMatches(candidate, source)) return Object.freeze({ matched: false, status: 'unmatched' });
       if (!(await this.#permitAllows(candidate, source, operationSnapshot))) return this.#denied(candidate);
-      const help = commandHelp(candidate.name, candidate.slot.definition, commandPrefix);
+      const help = commandHelp(commandDisplayName(candidate, locale), candidate.slot.definition, prefix, locale);
       const segments = normalizeSegments(typeof input === 'string' ? [{ type: 'text', data: { text: input } }] : input);
       if (requestsCommandHelp(segments)) return Object.freeze({ matched: true, status: 'executed', command: candidate.name, owner: candidate.slot.owner, value: help });
       return Object.freeze({ matched: true, status: 'invalid', command: candidate.name, owner: candidate.slot.owner,
-        issues: Object.freeze([{ field: candidate.parameter?.name ?? 'arguments', message: 'Missing or invalid command parameter' }]), help });
+        issues: Object.freeze([commandValidationIssue('invalidParameter', candidate.parameter?.name ?? 'arguments', locale)]), help });
     }
     if (!commandAdapterMatches(match.command, source)) return Object.freeze({ matched: false, status: 'unmatched' });
     if (!(await this.#permitAllows(match.command, source, operationSnapshot))) return this.#denied(match.command);
     const definition = match.command.slot.definition;
     const authorSource = bindOperationInput(source, match.command.slot.owner, operationSnapshot);
-    const help = commandHelp(match.command.name, definition, commandPrefix);
+    const help = commandHelp(commandDisplayName(match.command, locale), definition, prefix, locale);
     if (match.helpRequested) {
       return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value: help });
     }
-    const parsed = parseCommandArguments(definition, match.remaining, resolveDynamicParams(match.params, authorSource), resolveCommandSession(authorSource));
+    const parsed = parseCommandArguments(definition, match.remaining, resolveDynamicParams(match.params, authorSource), resolveCommandSession(authorSource), locale);
     if (parsed.issues.length > 0) return Object.freeze({ matched: true, status: 'invalid', command: match.command.name,
       owner: match.command.slot.owner, issues: parsed.issues, help });
     const limit = admitCommandExecution(authorSource, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
     if (limit) return Object.freeze({ matched: true, status: 'limited', command: match.command.name, owner: match.command.slot.owner, limit });
     const value = await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner,
-      textArgs(parsed.remaining), parsed.params, authorSource, parsed.remaining, interactionFactory?.(authorSource), definition.adapter, parsed.options));
+      textArgs(parsed.remaining), parsed.params, authorSource, parsed.remaining, interactionFactory?.(authorSource), definition.adapter, parsed.options,
+      { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath,
+        source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) }));
     return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
   }
 
@@ -446,13 +496,10 @@ export class CommandIndex {
   // 内置菜单命令
   // ==========================================================================
 
-  #dispatchMenu(input: CommandMatchInput, commandPrefix: string, snapshot: RuntimeSnapshot): CommandMenuResult | undefined {
+  #dispatchMenu(input: CommandMatchInput, commandPrefix: string, snapshot: RuntimeSnapshot, locale: Locale, keyword: string): CommandMenuResult | undefined {
     const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
     if (text === undefined) return undefined;
-    const menu = this.#menu;
-    if (!menu) return undefined;
-    const keyword = menu.keyword;
-    if (text === keyword) return this.#buildMenu(undefined, commandPrefix, keyword, snapshot);
+    if (text === keyword) return this.#buildMenu(undefined, commandPrefix, keyword, snapshot, locale);
     if (text.startsWith(keyword + ' ')) {
       const key = text.slice(keyword.length + 1).trim();
       const args = key.split(/\s+/u);
@@ -461,24 +508,24 @@ export class CommandIndex {
         const pageText = args[flag + 1] ?? '';
         if (flag > 1 || args.length !== flag + 2 || !/^[1-9]\d*$/u.test(pageText)
           || !Number.isSafeInteger(Number(pageText))) {
-          return { value: `页码必须是正整数。用法：${commandPrefix}${keyword} [插件名] --page <页码>` };
+          return { value: commandMessages(locale, 'invalidPage', { command: `${commandPrefix}${keyword}` }) };
         }
-        return this.#buildMenu(flag === 1 ? args[0] : undefined, commandPrefix, keyword, snapshot, Number(pageText));
+        return this.#buildMenu(flag === 1 ? args[0] : undefined, commandPrefix, keyword, snapshot, locale, Number(pageText));
       }
-      if (key) return this.#buildMenu(key, commandPrefix, keyword, snapshot);
-      return this.#buildMenu(undefined, commandPrefix, keyword, snapshot);
+      if (key) return this.#buildMenu(key, commandPrefix, keyword, snapshot, locale);
+      return this.#buildMenu(undefined, commandPrefix, keyword, snapshot, locale);
     }
     return undefined;
   }
 
-  #buildMenu(pluginKey: string | undefined, commandPrefix: string, keyword: string, snapshot: RuntimeSnapshot, page = 1): CommandMenuResult {
+  #buildMenu(pluginKey: string | undefined, commandPrefix: string, keyword: string, snapshot: RuntimeSnapshot, locale: Locale, page = 1): CommandMenuResult {
     const root = snapshot.root;
     const targetId = pluginKey
       ? `${root}/${pluginKey.split('.').join('/')}` as PluginId
       : root;
 
     const node = snapshot.tree.get(targetId);
-    if (!node) return { value: `未找到插件: ${pluginKey}` };
+    if (!node) return { value: commandMessages(locale, 'missingPlugin', { plugin: pluginKey ?? '' }) };
 
     const directCommands = this.#commands.filter((cmd) => cmd.slot.owner === targetId);
     const children = node.children
@@ -487,26 +534,27 @@ export class CommandIndex {
 
     const pages = Math.max(1, Math.ceil((directCommands.length + children.length) / MENU_PAGE_SIZE));
     const invocation = `${commandPrefix}${keyword}${pluginKey ? ` ${pluginKey}` : ''}`;
-    if (page > pages) return { value: `页码超出范围：共 ${pages} 页。请使用「${invocation} --page <页码>」。` };
+    if (page > pages) return { value: commandMessages(locale, 'pageOutOfRange', { pages, command: invocation }) };
     const offset = (page - 1) * MENU_PAGE_SIZE;
     const pageCommands = directCommands.slice(offset, offset + MENU_PAGE_SIZE);
     const pageChildren = children.slice(Math.max(0, offset - directCommands.length), Math.max(0, offset + MENU_PAGE_SIZE - directCommands.length));
 
     const displayKey = pluginKey ?? node.instanceKey;
-    const lines: string[] = [`=== ${displayKey} 指令菜单 ===`];
-    if (pages > 1) lines.push(`第 ${page}/${pages} 页 · ${directCommands.length} 条指令 · ${children.length} 个子插件`);
+    const lines: string[] = [commandMessages(locale, 'menuTitle', { plugin: displayKey })];
+    if (pages > 1) lines.push(commandMessages(locale, 'menuSummary', { page, pages, commands: directCommands.length, plugins: children.length }));
 
     if (pageCommands.length > 0) {
       lines.push('');
       for (const cmd of pageCommands) {
-        const desc = cmd.description ? `  - ${cmd.description}` : '';
-        lines.push(`  ${commandPrefix}${cmd.name}${desc}`);
+        const description = commandDescription(cmd.slot.definition, locale);
+        const desc = description ? `  - ${description}` : '';
+        lines.push(`  ${commandPrefix}${commandDisplayName(cmd, locale)}${desc}`);
       }
     }
 
     if (pageChildren.length > 0) {
       lines.push('');
-      lines.push('子插件：');
+      lines.push(commandMessages(locale, 'childPlugins'));
       for (const child of pageChildren) {
         const childKey = pluginKey ? `${pluginKey}.${child.instanceKey}` : child.instanceKey;
         const label = child.metadata?.displayName ?? child.instanceKey;
@@ -516,13 +564,13 @@ export class CommandIndex {
 
     if (directCommands.length === 0 && children.length === 0) {
       lines.push('');
-      lines.push('（暂无指令和子插件）');
+      lines.push(commandMessages(locale, 'emptyMenu'));
     }
 
     const hints: string[] = [];
-    if (children.length > 0) hints.push(`提示：使用「${commandPrefix}${keyword} <插件名>」查看子插件的指令`);
-    if (page > 1) hints.push(`上一页：${invocation} --page ${page - 1}`);
-    if (page < pages) hints.push(`下一页：${invocation} --page ${page + 1}`);
+    if (children.length > 0) hints.push(commandMessages(locale, 'pluginHint', { command: `${commandPrefix}${keyword}` }));
+    if (page > 1) hints.push(commandMessages(locale, 'previousPage', { command: `${invocation} --page ${page - 1}` }));
+    if (page < pages) hints.push(commandMessages(locale, 'nextPage', { command: `${invocation} --page ${page + 1}` }));
     const hint = hints.length ? hints.join('\n') : undefined;
     if (hint) {
       lines.push('');
@@ -530,19 +578,39 @@ export class CommandIndex {
     }
 
     const text = lines.join('\n');
-    const menu = Object.freeze({ keyword, ...(pluginKey ? { pluginKey } : {}), page, pages });
-    if (!snapshot.resources.get(root)?.has(htmlRendererToken.id)) return { value: text, menu };
     const config = snapshot.config.get(root) as Record<string, unknown> | undefined;
-    return { menu, value: renderCommandMenu(displayKey,
-      pageCommands.map(cmd => ({ name: `${commandPrefix}${cmd.name}`, description: cmd.description })),
-      pageChildren.map(child => ({
+    const menu: CommandMenuPage = Object.freeze({
+      keyword, ...(pluginKey ? { pluginKey } : {}), page, pages, locale, title: displayKey,
+      commands: Object.freeze(pageCommands.map(cmd => Object.freeze({
+        name: `${commandPrefix}${commandDisplayName(cmd, locale)}`, description: commandDescription(cmd.slot.definition, locale),
+      }))),
+      plugins: Object.freeze(pageChildren.map(child => Object.freeze({
         name: pluginKey ? `${pluginKey}.${child.instanceKey}` : child.instanceKey,
         description: child.metadata?.displayName ?? child.instanceKey,
-      })), hint, text, { page, pages, commandTotal: directCommands.length, pluginTotal: children.length,
-        appearance: readMenuAppearance(config?.menuStyle) }) };
+      }))),
+      commandTotal: directCommands.length, pluginTotal: children.length, hint, text,
+      appearance: Object.freeze(readMenuAppearance(config?.menuStyle)),
+    });
+    if (!snapshot.resources.get(root)?.has(htmlRendererToken.id)) return { value: text, menu };
+    return { menu, value: renderCommandMenu(displayKey, menu.commands, menu.plugins, hint, text, {
+      page, pages, locale, commandTotal: menu.commandTotal, pluginTotal: menu.pluginTotal, appearance: menu.appearance,
+    }) };
   }
 }
 
+function commandDisplaySegments(record: CommandRecord, locale: Locale): readonly string[] {
+  return record.preferredSegments[locale] ?? record.segments;
+}
+
+function commandDisplayName(record: CommandRecord, locale: Locale): string {
+  return displayName(commandDisplaySegments(record, locale), record.parameter);
+}
+
+function commandLocale(source: unknown, snapshot: RuntimeSnapshot): Locale {
+  const locale = source && typeof source === 'object' && 'locale' in source ? source.locale : undefined;
+  return resolveLocale(locale ?? (snapshot.config.get(snapshot.root) as { locale?: unknown } | undefined)?.locale);
+}
+
 export function isCommandIndex(value: unknown): value is CommandIndex {
   return !!value && typeof value === 'object'
     && (value as { readonly $projection?: unknown }).$projection === 'zhin.command-index/1';

package/src/command-menu.ts

@@ -1,9 +1,12 @@
-interface MenuEntry {
+import type { Locale } from '@zhin.js/plugin-runtime';
+import { commandMessages } from './messages.js';
+
+export interface CommandMenuEntry {
   readonly name: string;
   readonly description?: string;
 }
 
-interface MenuAppearance {
+export interface CommandMenuAppearance {
   readonly title?: string;
   readonly subtitle?: string;
   readonly accentColor?: string;
@@ -27,7 +30,7 @@ const escape = (value: string) => value.replace(/[&<>"']/gu, char => ({
 })[char] ?? char);
 
 /** Configuration is text/data, never an interpolated CSS or HTML fragment. */
-export function readMenuAppearance(value: unknown): MenuAppearance {
+export function readMenuAppearance(value: unknown): CommandMenuAppearance {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
   const input = value as Record<string, unknown>;
   const result: { title?: string; subtitle?: string; accentColor?: string; backgroundImage?: string } = {};
@@ -69,20 +72,21 @@ function icon(name: string, plugin = false): string {
 /** Presentation only: the unified outbound pipeline owns image rendering and fallback. */
 export function renderCommandMenu(
   title: string,
-  commands: readonly MenuEntry[],
-  children: readonly MenuEntry[],
+  commands: readonly CommandMenuEntry[],
+  children: readonly CommandMenuEntry[],
   hint: string | undefined,
   text: string,
-  options: { readonly page?: number; readonly pages?: number; readonly commandTotal?: number; readonly pluginTotal?: number; readonly appearance?: MenuAppearance } = {},
+  options: { readonly page?: number; readonly pages?: number; readonly locale?: Locale; readonly commandTotal?: number; readonly pluginTotal?: number; readonly appearance?: CommandMenuAppearance } = {},
 ): CommandMenuSegment {
+  const locale = options.locale ?? 'zh-CN';
   const appearance = options.appearance ?? {};
   const background = appearance.backgroundImage ?? `data:image/svg+xml,${encodeURIComponent(landscape)}`;
   // CSS string escaping additionally prevents an artwork URL from closing <style>.
   const cssUrl = JSON.stringify(background).replace(/</gu, '\\3c ').replace(/>/gu, '\\3e ');
-  const entries = (items: readonly MenuEntry[], plugin: boolean) => items.map(item =>
+  const entries = (items: readonly CommandMenuEntry[], plugin: boolean) => items.map(item =>
     `<div class="entry"><div class="icon">${icon(item.name, plugin)}</div><div class="copy"><div class="name">${escape(item.name)}</div>${item.description
       ? `<div class="description">${escape(item.description)}</div>` : ''}</div></div>`).join('');
-  const section = (label: string, items: readonly MenuEntry[], total: number, plugin = false) => items.length === 0 ? ''
+  const section = (label: string, items: readonly CommandMenuEntry[], total: number, plugin = false) => items.length === 0 ? ''
     : `<section><div class="section-head"><h2>${label}</h2><span>${items.length} / ${total}</span></div><div class="grid">${entries(items, plugin)}</div></section>`;
   const page = options.page ?? 1;
   const pages = options.pages ?? 1;
@@ -91,7 +95,7 @@ export function renderCommandMenu(
     type: 'html',
     data: {
       width: 1080, fileName: 'command-menu.png', text,
-      html: `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><style>
+      html: `<!doctype html><html lang="${locale}"><head><meta charset="utf-8"><style>
 *{box-sizing:border-box}body{margin:0;background:#253b46;color:#f4f0e6;font-family:"PingFang SC","Microsoft YaHei",sans-serif;font-size:18px;line-height:1.5;--accent:${appearance.accentColor ?? '#e7c993'}}
 main{padding:42px 28px 24px;background-image:linear-gradient(180deg,#0c202a0a,#0c202a55),url(${cssUrl});background-size:cover;background-position:center top}
 header{min-height:210px;padding:10px 22px 30px;position:relative}.eyebrow{font-size:12px;letter-spacing:5px;color:#f4e4c4;margin:0 0 17px}
@@ -102,11 +106,11 @@ h2{margin:0;font-size:20px;font-weight:700;letter-spacing:1px;color:var(--accent
 .grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));background:#20363fdb;border-radius:0 0 13px 13px;overflow:hidden}
 .entry{display:flex;align-items:center;gap:12px;padding:19px 17px;min-width:0;min-height:106px;border-top:1px solid #e7e6d614;border-right:1px solid #e7e6d614;background:linear-gradient(120deg,#ffffff08,#ffffff00)}.entry:nth-child(3n){border-right:0}
 .icon{width:35px;height:35px;flex:0 0 35px;color:var(--accent);filter:drop-shadow(0 1px 6px #d9ba7c22)}.icon svg{display:block;width:100%;height:100%}.copy{min-width:0}.name{font-size:18px;font-weight:700;color:var(--accent)}.description{margin:4px 0 0;color:#e1e8e5;font-size:15px;line-height:1.45}
-.name,.description,h1{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;overflow-wrap:anywhere;white-space:pre-wrap}
+.name{overflow-wrap:anywhere;white-space:pre-wrap}.description,h1{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;overflow-wrap:anywhere;white-space:pre-wrap}
 footer{margin:6px 5px 0;padding:15px 18px;display:flex;align-items:center;justify-content:space-between;gap:22px;background:#142a34da;border:1px solid #f0e2c71c;border-radius:13px}.hint{font-size:14px;color:#cfdbd7;white-space:pre-wrap;overflow-wrap:anywhere}.page{font-size:20px;color:var(--accent);white-space:nowrap;font-family:Georgia,serif}.signature{margin:16px 0 0;text-align:center;font-size:10px;letter-spacing:4px;color:#c4d0c899}.empty{margin:0 0 20px;padding:28px;background:#142a34da;border-radius:16px;color:#dbe4de}
-</style></head><body><main><header><div class="eyebrow">ZHIN / COMMAND ATLAS</div><h1>${escape(appearance.title || `${title} · 指令指南`)}</h1><div class="subtitle">${escape(appearance.subtitle ?? '每一个灵感，都有回应。')}</div><div class="summary"><i></i>${options.commandTotal ?? commands.length} 条指令<span>·</span>${options.pluginTotal ?? children.length} 个子插件<span>·</span>${escape(title)}</div></header>
-${section('指令索引', commands, options.commandTotal ?? commands.length)}${section('插件导航', children, options.pluginTotal ?? children.length, true)}${commands.length || children.length ? '' : '<p class="empty">暂无指令和子插件</p>'}
-<footer><div class="hint">${escape(hint ?? '查看参数与用法：指令名 --help')}</div><div class="page">${String(page).padStart(2, '0')} / ${String(pages).padStart(2, '0')}</div></footer><div class="signature">ZHIN · MAKE EVERY MESSAGE MATTER</div></main></body></html>`,
+</style></head><body><main><header><div class="eyebrow">ZHIN / COMMAND ATLAS</div><h1>${escape(appearance.title || commandMessages(locale, 'guideTitle', { title }))}</h1><div class="subtitle">${escape(appearance.subtitle ?? commandMessages(locale, 'guideSubtitle'))}</div><div class="summary"><i></i>${escape(commandMessages(locale, 'commandCount', { count: options.commandTotal ?? commands.length }))}<span>·</span>${escape(commandMessages(locale, 'pluginCount', { count: options.pluginTotal ?? children.length }))}<span>·</span>${escape(title)}</div></header>
+${section(commandMessages(locale, 'commandIndex'), commands, options.commandTotal ?? commands.length)}${section(commandMessages(locale, 'pluginIndex'), children, options.pluginTotal ?? children.length, true)}${commands.length || children.length ? '' : `<p class="empty">${commandMessages(locale, 'guideEmpty')}</p>`}
+<footer><div class="hint">${escape(hint ?? commandMessages(locale, 'genericHelpHint'))}</div><div class="page">${String(page).padStart(2, '0')} / ${String(pages).padStart(2, '0')}</div></footer><div class="signature">ZHIN · MAKE EVERY MESSAGE MATTER</div></main></body></html>`,
     },
   };
 }

package/src/definition.ts

@@ -2,7 +2,7 @@
  * Command authoring API consumed from `zhin.js/command`.
  * @module zhin.js/command
  */
-import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { resolveLocale, type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import {
   createCapabilityContext,
   readOperationClient,
@@ -92,6 +92,8 @@ export interface CommandParamSchema {
   readonly type: CommandParameterType;
   readonly default?: CommandDynamicValue;
   readonly description?: string;
+  /** Optional translated display text; machine keys and values remain unchanged. */
+  readonly descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
   readonly optional?: boolean;
   readonly rest?: boolean;
   readonly min?: number;
@@ -145,6 +147,7 @@ export interface CommandParameterDefinition {
   /** `[...name]` / `[[...name]]` 捕获所有段，运行时值为 `string[]`。 */
   readonly rest?: boolean;
   readonly description?: string;
+  readonly descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
 }
 
 /** 场景：群 / 私聊 / 频道等。 */
@@ -192,6 +195,8 @@ export interface CommandConversation {
 export interface CommandMessage {
   readonly conversation: CommandConversation;
   readonly content: string;
+  /** Display preference resolved by the IM runtime, when this is an IM operation. */
+  readonly locale?: Locale;
   /** 发送者（结构化视图见 CommandContext.sender）。 */
   readonly sender?: { readonly id: string; readonly name?: string; readonly roles?: readonly string[] };
   readonly id?: string;
@@ -264,6 +269,16 @@ export interface CommandContext<
   TInput extends CommandMessage = CommandMessage,
   TAdapter extends string | undefined = undefined,
 > extends CapabilityContext<TConfig>, CommandSession {
+  /** Language resolved once for the current operation. */
+  readonly locale: Locale;
+  /**
+   * Resolve a static local command path to its current chat invocation. Defaults to this
+   * plugin; an explicit owner may reference another indexed plugin.
+   * Includes the actual Endpoint prefix and configured commandNamespace. Arguments
+   * are appended explicitly by the caller. Returns undefined for unknown/disabled
+   * paths or calls without a known chat command environment.
+   */
+  formatCommand(localPath: string, owner?: PluginId): string | undefined;
   readonly args: readonly string[];
   readonly params: Readonly<Record<string, CommandParameterValue>>;
   readonly options: Readonly<Record<string, CommandParameterValue>>;
@@ -294,6 +309,7 @@ export interface CommandDefinition<
   /** @internal Convention-derived parameter metadata. */
   readonly $parameter?: CommandParameterDefinition;
   readonly description?: string;
+  readonly descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
   /** Restrict this command to one adapter and infer `context.$client`. */
   readonly adapter?: TAdapter;
   /**
@@ -307,6 +323,8 @@ export interface CommandDefinition<
    * 用户路由；alias 只替换文件路径提供的静态段。
    */
   readonly alias?: readonly string[];
+  /** Display an explicitly declared alias for this locale; every value must also occur in alias. */
+  readonly preferredAliasI18n?: Readonly<Partial<Record<Locale, string>>>;
   /**
    * 内置 permit DSL（AND）。单项内逗号为 OR。
    * 例：`adapter(icqq)`、`role(master)`、`group(123,456)`。
@@ -398,7 +416,9 @@ export function defineCommand<
     }
   }
   validateArgumentSchemas(definition.params, definition.options);
+  validateDescriptionI18n(definition.descriptionI18n);
   validateCommandAlias(definition.alias);
+  validatePreferredAliases(definition);
   validateCommandPermit(definition.permit);
   validateCommandShortcutShape(definition.shortcut);
   const execution = normalizeExecutionPolicy(definition.execution);
@@ -407,6 +427,15 @@ export function defineCommand<
   >;
 }
 
+/** @internal Validate display-only translations without changing their fallback text. */
+export function validateDescriptionI18n(value: CommandDefinition['descriptionI18n']): void {
+  if (value === undefined) return;
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.entries(value).some(([locale, text]) => !['zh-CN', 'en'].includes(locale) || typeof text !== 'string')) {
+    throw new TypeError('Command descriptionI18n must map zh-CN/en to strings');
+  }
+}
+
 /**
  * 先固定插件 config 类型，再定义命令；params / options / 返回值仍从定义推断。
  *
@@ -435,6 +464,19 @@ function validateAdapterName(adapter: string | undefined): void {
   }
 }
 
+function validatePreferredAliases(definition: Pick<CommandDefinition, 'alias' | 'preferredAliasI18n'>): void {
+  const preferred = definition.preferredAliasI18n;
+  if (preferred === undefined) return;
+  validateDescriptionI18n(preferred);
+  const normalize = (value: string) => value.trim().split(/\s+/u).filter(Boolean).join(' ');
+  const aliases = new Set(definition.alias?.map(normalize));
+  for (const [locale, alias] of Object.entries(preferred)) {
+    if (!aliases.has(normalize(alias))) {
+      throw new TypeError(`Command preferredAliasI18n.${locale} must reference a declared alias`);
+    }
+  }
+}
+
 function validateCommandAlias(alias: readonly string[] | undefined): void {
   if (alias === undefined) return;
   if (!Array.isArray(alias)) {
@@ -506,6 +548,8 @@ export function parseCommandDefinition(value: unknown): CommandDefinition {
   }
   validateAdapterName(definition.adapter);
   normalizeExecutionPolicy(definition.execution);
+  validateCommandAlias(definition.alias);
+  validatePreferredAliases(definition);
   return definition as CommandDefinition;
 }
 
@@ -537,6 +581,7 @@ export function createCommandContext(
   interaction?: UserInteraction,
   adapter?: string,
   options: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
+  presentation?: Readonly<{ locale: Locale; formatCommand?: (localPath: string, owner?: PluginId) => string | undefined }>,
 ): CommandContext {
   const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
   const session = resolveCommandSession(input);
@@ -545,6 +590,8 @@ export function createCommandContext(
   const result = {
     ...context,
     ...session,
+    locale: presentation?.locale ?? resolveLocale((snapshot.config.get(snapshot.root) as { locale?: unknown } | undefined)?.locale),
+    formatCommand: presentation?.formatCommand ?? (() => undefined),
     args: Object.freeze([...args]),
     params: Object.freeze(parameterValues),
     options: Object.freeze(optionValues),

package/src/index.ts

@@ -28,4 +28,4 @@ export {
 } from './provider.js';
 export { default } from './provider.js';
 
-export type { CommandValidationIssue } from './arguments.js';
+export type { CommandValidationIssue, CommandValidationIssueCode } from './arguments.js';

package/src/messages.ts

@@ -0,0 +1,62 @@
+import { createMessages, type Locale } from '@zhin.js/plugin-runtime';
+
+/** Translates only display metadata explicitly supplied by its author. */
+export function commandDescription(
+  value: Readonly<{ description?: string; descriptionI18n?: Readonly<Partial<Record<Locale, string>>> }>,
+  locale: Locale,
+): string | undefined {
+  return value.descriptionI18n?.[locale] ?? value.description;
+}
+
+/** Static dictionaries; the caller supplies the operation's language. */
+export const commandMessages = createMessages({
+  menuKeyword: { 'zh-CN': '菜单', en: 'menu' },
+  invalidPage: { 'zh-CN': '页码必须是正整数。用法：{command} [插件名] --page <页码>', en: 'The page must be a positive integer. Usage: {command} [plugin] --page <page>' },
+  missingPlugin: { 'zh-CN': '未找到插件: {plugin}', en: 'Plugin not found: {plugin}' },
+  pageOutOfRange: { 'zh-CN': '页码超出范围：共 {pages} 页。请使用「{command} --page <页码>」。', en: 'Page out of range: {pages} pages available. Use {command} --page <page>.' },
+  menuTitle: { 'zh-CN': '=== {plugin} 指令菜单 ===', en: '=== {plugin} command menu ===' },
+  menuSummary: { 'zh-CN': '第 {page}/{pages} 页 · {commands} 条指令 · {plugins} 个子插件', en: 'Page {page}/{pages} · Commands: {commands} · Plugins: {plugins}' },
+  childPlugins: { 'zh-CN': '子插件：', en: 'Plugins:' },
+  emptyMenu: { 'zh-CN': '（暂无指令和子插件）', en: '(No commands or plugins)' },
+  pluginHint: { 'zh-CN': '提示：使用「{command} <插件名>」查看子插件的指令', en: 'Use {command} <plugin> to view a plugin’s commands.' },
+  previousPage: { 'zh-CN': '上一页：{command}', en: 'Previous page: {command}' },
+  nextPage: { 'zh-CN': '下一页：{command}', en: 'Next page: {command}' },
+  guideTitle: { 'zh-CN': '{title} · 指令指南', en: '{title} · Command guide' },
+  guideSubtitle: { 'zh-CN': '每一个灵感，都有回应。', en: 'An answer to every idea.' },
+  commandCount: { 'zh-CN': '{count} 条指令', en: 'Commands: {count}' },
+  pluginCount: { 'zh-CN': '{count} 个子插件', en: 'Plugins: {count}' },
+  commandIndex: { 'zh-CN': '指令索引', en: 'Commands' },
+  pluginIndex: { 'zh-CN': '插件导航', en: 'Plugins' },
+  guideEmpty: { 'zh-CN': '暂无指令和子插件', en: 'No commands or plugins' },
+  helpHint: { 'zh-CN': '查看参数与用法：{command} --help', en: 'View arguments and usage: {command} --help' },
+  genericHelpHint: { 'zh-CN': '在当前环境的指令后追加 --help 查看用法', en: 'Append --help to a command in this environment to view its usage' },
+  expectedType: { 'zh-CN': '{field}：应为 {type}', en: '{field}: expected {type}' },
+  expectedArray: { 'zh-CN': '{field}：应为 {type} 数组', en: '{field}: expected an array of {type}' },
+  minimum: { 'zh-CN': '{field}：最小值为 {minimum}', en: '{field}: minimum {minimum}' },
+  maximum: { 'zh-CN': '{field}：最大值为 {maximum}', en: '{field}: maximum {maximum}' },
+  choices: { 'zh-CN': '{field}：可选值为 {choices}', en: '{field}: expected one of {choices}' },
+  invalidFormat: { 'zh-CN': '{field}：格式不正确', en: '{field}: invalid format' },
+  invalidValue: { 'zh-CN': '{field}：值不正确', en: '{field}: invalid value' },
+  unknownOption: { 'zh-CN': '未知选项 {field}', en: 'Unknown option {field}' },
+  duplicateOption: { 'zh-CN': '重复选项 --{field}', en: 'Duplicate option --{field}' },
+  defaultUndefined: { 'zh-CN': '{field}：默认值返回了 undefined', en: '{field}: default returned undefined' },
+  parameterUndefined: { 'zh-CN': '{field}：默认值或快捷指令返回了 undefined', en: '{field}: default or shortcut returned undefined' },
+  missingOption: { 'zh-CN': '缺少选项 --{field}', en: 'Missing option --{field}' },
+  unexpectedArguments: { 'zh-CN': '存在多余参数', en: 'Unexpected arguments' },
+  invalidParameter: { 'zh-CN': '缺少指令参数或参数不正确', en: 'Missing or invalid command parameter' },
+  defaultValue: { 'zh-CN': '默认值：{value}', en: 'default: {value}' },
+  dynamicValue: { 'zh-CN': '动态计算', en: 'dynamic' },
+  noAdapter: { 'zh-CN': '命令未声明 adapter 约束', en: 'The command does not declare an adapter restriction' },
+  missingEndpoint: { 'zh-CN': '未选择当前 Endpoint，无法判断命令的精确 adapter 约束', en: 'Select an Endpoint to evaluate the command’s exact adapter restriction' },
+  adapterComparison: { 'zh-CN': '命令 adapter 与当前 Endpoint 声明的原生适配器精确比较；未探测在线状态', en: 'Exact comparison with the Endpoint’s declared native adapter; online status was not checked' },
+  conditionMismatch: { 'zh-CN': '至少一个声明条件与假设输入不符；这不是实际准入检查', en: 'At least one declared condition does not match the hypothetical input; this is not a live admission check' },
+  missingPermissionHost: { 'zh-CN': 'PermissionHost 缺失或无法确认；不能推断命令可执行', en: 'PermissionHost is missing or unverified; command execution cannot be inferred' },
+  missingEvidence: { 'zh-CN': '存在缺少依据的条件，不能推断命令可执行', en: 'Some conditions lack evidence; command execution cannot be inferred' },
+  noPermit: { 'zh-CN': '命令未声明 permit 限制；这不表示已获得执行权限', en: 'The command does not declare permit restrictions; this does not establish authorization' },
+  uncheckedConditions: { 'zh-CN': '存在未执行的平台或自定义条件，不能推断命令可执行', en: 'Platform or custom conditions have not been evaluated; command execution cannot be inferred' },
+  conditionsMatch: { 'zh-CN': '已解释的 builtin 条件与假设输入匹配；不代表真实授权或命令可执行', en: 'The explained builtin conditions match the hypothetical input; this does not establish authorization or executability' },
+  unconstrained: { 'zh-CN': '已解释的 builtin 规则不检查具体 Endpoint、parent 或 thread；保留完整目标不等于这些维度受规则限制', en: 'The explained builtin rules do not constrain a specific Endpoint, parent or thread; retaining the full target does not add such restrictions' },
+  simulatedIdentity: { 'zh-CN': '身份与角色仅用于模拟，未向平台核实', en: 'Identity and roles are hypothetical and have not been verified with the platform' },
+  unevaluatedCode: { 'zh-CN': '未执行命令、动态默认值、平台或自定义 checker', en: 'Commands, dynamic defaults, platform checks and custom checkers have not been executed' },
+  defaultedRole: { 'zh-CN': 'canonical 输入未附角色时按命令运行时默认 user 解释；这不是已核验的平台角色', en: 'Canonical input without roles uses the command runtime’s default user role; this is not a verified platform role' },
+});