@zhin.js/command 1.1.10 → 1.1.11

package/README.md

@@ -42,6 +42,8 @@ commands/search/[...kw]/index.ts    -> search <...kw>   （params: { kw: { type:
 - `config` / `use()` / `owner` / `generation`：owner-scoped Runtime 上下文。
 - `signal`：真实 IM 入站操作的运行代退休时同步取消。补问、确认及其他需要随代结束的等待应观察此信号；它不会强制取消已经开始的发送，也不禁止持有旧 lease 的普通命令继续排空。没有携带运行代生命周期的输入（如普通 Host 调用）不会凭空获得 IM 生命周期。
 - `input`：派发来源；IM 中为满足 `CommandMessage` 的 Runtime `Message`。
+- `locale`：本次操作已经解析的 `zh-CN` 或 `en`，群聊也按发送者偏好；无个人偏好时沿用项目默认语言。
+- `formatCommand(localPath, owner?)`：从当前索引取得静态命令调用头，默认本插件，也可显式传入已知的插件 owner，自动拼上实际 Endpoint 前缀和显式 `commandNamespace`。例如 `formatCommand('remind list')`；参数在返回的调用头后显式附加。命令不存在、被禁用或当前没有已知聊天命令环境时返回 `undefined`，不要以硬编码 `/` 或命令名掩盖该结果。
 - `adapter` / `endpoint`：适配器实例 id 与 endpoint 名。
 - `scene`：`{ id, type, name? }` 场景对象。
 - `sender`：`{ id, name?, role: string[] }` 发送者对象。
@@ -78,7 +80,9 @@ PermissionHost 或缺少身份依据均不能被展示为“已授权”或“
 
 ## 集中声明参数、选项与帮助
 
-**列出指令**：在 Bot 会话中发送 `菜单`，列出根插件的指令和直接子插件；`菜单 <插件实例键>` 查看子插件，嵌套实例用 `菜单 foo.bar`。菜单逐层浏览，不一次展开全树。账号设有命令前缀时同样要加前缀，如 `/菜单`。项目根配置的顶层 `menuKeyword` 可修改关键词，`false` 或空字符串关闭；默认关键词为 `菜单`，不是 `help`。详见[指令菜单](../../../docs/authoring/commands.md#查看已加载的指令菜单)。
+**列出指令**：中文操作使用 `菜单`，英文操作使用 `menu`，每次只接受该操作语言的默认关键词。列出根插件的指令和直接子插件；`菜单 <插件实例键>` 查看子插件，嵌套实例用 `菜单 foo.bar`（英文对应 `menu foo.bar`）。菜单逐层浏览，不一次展开全树。账号设有命令前缀时同样要加前缀，如 `/菜单`。项目根配置的顶层 `menuKeyword` 可显式修改关键词，不随语言翻译；`false` 或空字符串关闭。详见[指令菜单](../../../docs/authoring/commands.md#查看已加载的指令菜单)。
+
+命令、参数和选项保留 `description` 原文，可额外声明 `descriptionI18n: { en: 'English description' }`。菜单、`--help` 与 `CommandIndex.list(locale)` 使用对应说明，缺失时保留作者原文，不自动翻译机器名称、用户内容或参数值。参数错误带稳定的 `code` 与 `parameters`，`message` 是当前语言的展示；自定义 `validate` 返回的文本仍由作者负责。
 
 安装 `@zhin.js/html-renderer` 后，菜单发出带原始文本备用内容的 HTML 段，复用统一发送链的图片渲染和平台策略。渲染失败或平台无法消费图片时保留原文本；无渲染器时直接返回文本。Command Feature 不调用渲染器，也不新增 Core 或样式组件依赖。
 
@@ -170,3 +174,19 @@ pnpm --filter @zhin.js/command test
 
 完整用户契约见[命令创作指南](../../../docs/authoring/commands.md)，架构迁移背景见
 [Plugin Runtime 原位迁移](../../../docs/architecture/target-implementation/in-place-migration.md)。
+
+
+命令可声明 `descriptionI18n: { en: 'Create a reminder' }` 翻译描述。若静态目录名是中文，可沿用 `alias` 提供英文入口，并用 `preferredAliasI18n` 显式选择英文展示：
+
+```ts
+export default defineCommand({
+  alias: ['reminder subscribe'],
+  preferredAliasI18n: { en: 'reminder subscribe' },
+  execute({ locale, formatCommand }) {
+    // 参数仍由调用方明确附加；不存在或没有真实聊天环境时返回 undefined。
+    return formatCommand('提醒 订阅');
+  },
+});
+```
+
+`preferredAliasI18n` 必须引用该命令已声明的别名；它只选择菜单、帮助与指令引用的展示入口，不创建新路由或停用既有别名。实际插件挂载命名空间与当前消息前缀由同一个 `CommandIndex` 拼接。

package/lib/arguments.d.ts

@@ -1,8 +1,14 @@
 import type { CommandDefinition, CommandParams, CommandOptions, CommandParameterValue, CommandSegment, CommandSession } from './definition.js';
+import type { Locale } from '@zhin.js/plugin-runtime';
+export type CommandValidationIssueCode = 'expectedType' | 'expectedArray' | 'minimum' | 'maximum' | 'choices' | 'invalidFormat' | 'invalidValue' | 'unknownOption' | 'duplicateOption' | 'defaultUndefined' | 'parameterUndefined' | 'missingOption' | 'unexpectedArguments' | 'invalidParameter' | 'custom';
 export interface CommandValidationIssue {
     readonly field: string;
     readonly message: string;
+    readonly code?: CommandValidationIssueCode;
+    readonly parameters?: Readonly<Record<string, string | number>>;
 }
+/** Stable validation reason and values; never reverse-parse an English message. */
+export declare function commandValidationIssue(code: Exclude<CommandValidationIssueCode, 'custom'>, field: string, locale: Locale, parameters?: Readonly<Record<string, string | number>>): CommandValidationIssue;
 export interface ParsedCommandArguments {
     readonly params: Readonly<Record<string, CommandParameterValue>>;
     readonly options: Readonly<Record<string, CommandParameterValue>>;
@@ -14,6 +20,6 @@ export declare function validateArgumentSchemas(params?: CommandParams, options?
 /** Reserved flags use the same quoted-token and option-terminator rules as arguments. */
 export declare function requestsCommandHelp(segments: readonly Readonly<CommandSegment>[]): boolean;
 /** Parse arguments after a route match; the CommandIndex remains the only dispatcher. */
-export declare function parseCommandArguments(definition: CommandDefinition, remaining: readonly Readonly<CommandSegment>[], initial: Readonly<Record<string, CommandParameterValue>>, session: CommandSession): ParsedCommandArguments;
+export declare function parseCommandArguments(definition: CommandDefinition, remaining: readonly Readonly<CommandSegment>[], initial: Readonly<Record<string, CommandParameterValue>>, session: CommandSession, locale?: Locale): ParsedCommandArguments;
 export declare function commandUsage(name: string, definition: CommandDefinition): string;
-export declare function commandHelp(name: string, definition: CommandDefinition, prefix?: string): string;
+export declare function commandHelp(name: string, definition: CommandDefinition, prefix?: string, locale?: Locale): string;

package/lib/arguments.js

@@ -1,3 +1,9 @@
+import { commandDescription, commandMessages } from './messages.js';
+/** Stable validation reason and values; never reverse-parse an English message. */
+export function commandValidationIssue(code, field, locale, parameters = {}) {
+    const values = Object.freeze({ field, ...parameters });
+    return Object.freeze({ field, code, parameters: values, message: commandMessages(locale, code, values) });
+}
 const scalarTypes = new Set(['string', 'word', 'text', 'number', 'integer', 'float', 'boolean']);
 /** Validate the single declaration used by parsing, help and execution. */
 export function validateArgumentSchemas(params, options) {
@@ -51,6 +57,11 @@ function validateSchema(name, schema) {
     if (schema.choices !== undefined && !Array.isArray(schema.choices)) {
         throw new TypeError(`Command argument ${name}.choices must be an array`);
     }
+    if (schema.descriptionI18n !== undefined && (!schema.descriptionI18n || typeof schema.descriptionI18n !== 'object'
+        || Array.isArray(schema.descriptionI18n)
+        || Object.entries(schema.descriptionI18n).some(([locale, text]) => !['zh-CN', 'en'].includes(locale) || typeof text !== 'string'))) {
+        throw new TypeError(`Command argument ${name}.descriptionI18n must map zh-CN/en to strings`);
+    }
     if (schema.default !== undefined && !scalarTypes.has(schema.type))
         throw new TypeError(`Structured Command argument ${name} cannot declare a default`);
     if (schema.default !== undefined && typeof schema.default !== 'function') {
@@ -158,31 +169,32 @@ function valueMatches(schema, value) {
         return typeof value === 'string' || !!value && typeof value === 'object';
     return typeof value === 'string';
 }
-function validateValue(field, schema, value, session) {
+function validateValue(field, schema, value, session, locale = 'zh-CN') {
     if (schema.rest && !Array.isArray(value))
-        return { field, message: `${field}: expected an array of ${schema.type}` };
+        return commandValidationIssue('expectedArray', field, locale, { type: schema.type });
     const values = schema.rest ? (Array.isArray(value) ? value : [value]) : [value];
     for (const item of values) {
         if (!valueMatches(schema, item))
-            return { field, message: `${field}: expected ${schema.type}` };
+            return commandValidationIssue('expectedType', field, locale, { type: schema.type });
         const size = typeof item === 'number' ? item : typeof item === 'string' ? item.length : undefined;
         if (schema.min !== undefined && (size === undefined || size < schema.min))
-            return { field, message: `${field}: minimum ${schema.min}` };
+            return commandValidationIssue('minimum', field, locale, { minimum: schema.min });
         if (schema.max !== undefined && (size === undefined || size > schema.max))
-            return { field, message: `${field}: maximum ${schema.max}` };
+            return commandValidationIssue('maximum', field, locale, { maximum: schema.max });
         if (schema.choices && !schema.choices.includes(item))
-            return { field, message: `${field}: expected one of ${schema.choices.join(', ')}` };
+            return commandValidationIssue('choices', field, locale, { choices: schema.choices.join(', ') });
         if (schema.pattern) {
             const pattern = new RegExp(schema.pattern.source, schema.pattern.flags.replace(/[gy]/gu, ''));
             if (typeof item !== 'string' || !pattern.test(item))
-                return { field, message: `${field}: invalid format` };
+                return commandValidationIssue('invalidFormat', field, locale);
         }
     }
     const result = schema.validate?.(value, session);
-    return result === false || typeof result === 'string' ? { field, message: typeof result === 'string' ? result : `${field}: invalid value` } : undefined;
+    return typeof result === 'string' ? Object.freeze({ field, code: 'custom', message: result })
+        : result === false ? commandValidationIssue('invalidValue', field, locale) : undefined;
 }
 /** Parse arguments after a route match; the CommandIndex remains the only dispatcher. */
-export function parseCommandArguments(definition, remaining, initial, session) {
+export function parseCommandArguments(definition, remaining, initial, session, locale = 'zh-CN') {
     const params = { __proto__: null, ...initial };
     const options = { __proto__: null };
     const issues = [];
@@ -211,14 +223,14 @@ export function parseCommandArguments(definition, remaining, initial, session) {
         const flag = rawFlag ?? token.value;
         const name = optionNames.get(flag);
         if (!name) {
-            issues.push({ field: flag, message: `Unknown option ${flag}` });
+            issues.push(commandValidationIssue('unknownOption', flag, locale));
             continue;
         }
         const schema = schemas[name];
         if (!schema)
             continue;
         if (Object.hasOwn(options, name)) {
-            issues.push({ field: name, message: `Duplicate option --${name}` });
+            issues.push(commandValidationIssue('duplicateOption', name, locale));
             continue;
         }
         let value;
@@ -234,7 +246,7 @@ export function parseCommandArguments(definition, remaining, initial, session) {
             }
         }
         if (value === undefined)
-            issues.push({ field: name, message: `--${name}: expected ${schema.type}` });
+            issues.push(commandValidationIssue('expectedType', name, locale, { field: `--${name}`, type: schema.type }));
         else
             options[name] = value;
     }
@@ -242,14 +254,14 @@ export function parseCommandArguments(definition, remaining, initial, session) {
         if (!Object.hasOwn(options, name) && schema.default !== undefined)
             options[name] = typeof schema.default === 'function' ? schema.default(session) : schema.default;
         if (Object.hasOwn(options, name) && options[name] === undefined)
-            issues.push({ field: name, message: `--${name}: default returned undefined` });
+            issues.push(commandValidationIssue('defaultUndefined', name, locale, { field: `--${name}` }));
         else if (options[name] !== undefined) {
-            const issue = validateValue(`--${name}`, schema, options[name], session);
+            const issue = validateValue(`--${name}`, schema, options[name], session, locale);
             if (issue)
                 issues.push(issue);
         }
         else if (schema.optional === false)
-            issues.push({ field: name, message: `Missing option --${name}` });
+            issues.push(commandValidationIssue('missingOption', name, locale));
     }
     const declared = Object.entries(definition.params ?? {});
     for (const [name, declaredSchema] of declared) {
@@ -262,7 +274,7 @@ export function parseCommandArguments(definition, remaining, initial, session) {
                     ? segmentsFromTokens(raw).map((segment) => segment.type === 'text' && typeof segment.data.text === 'string' ? segment.data.text : undefined)
                     : raw.map((token) => convert(schema, token));
                 if (converted.some((item) => item === undefined))
-                    issues.push({ field: name, message: `${name}: expected ${schema.type}` });
+                    issues.push(commandValidationIssue('expectedType', name, locale, { type: schema.type }));
                 else if (converted.length > 0 || schema.optional)
                     value = converted;
             }
@@ -279,7 +291,7 @@ export function parseCommandArguments(definition, remaining, initial, session) {
                 value = convert(schema, positional.shift());
                 // Defaults apply to omitted input, never to a supplied value of the wrong type.
                 if (value === undefined) {
-                    issues.push({ field: name, message: `${name}: expected ${schema.type}` });
+                    issues.push(commandValidationIssue('expectedType', name, locale, { type: schema.type }));
                     continue;
                 }
             }
@@ -288,20 +300,20 @@ export function parseCommandArguments(definition, remaining, initial, session) {
             else if (schema.default !== undefined)
                 params[name] = typeof schema.default === 'function' ? schema.default(session) : schema.default;
             else if (!schema.optional && !(definition.$parameter?.name === name && definition.$parameter.optional)) {
-                issues.push({ field: name, message: `${name}: expected ${schema.type}` });
+                issues.push(commandValidationIssue('expectedType', name, locale, { type: schema.type }));
             }
         }
         if (Object.hasOwn(params, name) && params[name] === undefined)
-            issues.push({ field: name, message: `${name}: default or shortcut returned undefined` });
+            issues.push(commandValidationIssue('parameterUndefined', name, locale));
         else if (params[name] !== undefined) {
             const effective = definition.$parameter?.name === name && definition.$parameter.rest ? { ...schema, rest: true } : schema;
-            const issue = validateValue(name, effective, params[name], session);
+            const issue = validateValue(name, effective, params[name], session, locale);
             if (issue)
                 issues.push(issue);
         }
     }
     if (declared.length > 0 && !definition.$parameter && positional.length > 0)
-        issues.push({ field: 'arguments', message: 'Unexpected arguments' });
+        issues.push(commandValidationIssue('unexpectedArguments', 'arguments', locale));
     return Object.freeze({ params: Object.freeze(params), options: Object.freeze(options), remaining: schemas === undefined && declared.every(([name]) => Object.hasOwn(initial, name)) ? remaining : segmentsFromTokens(positional), issues: Object.freeze(issues) });
 }
 export function commandUsage(name, definition) {
@@ -310,12 +322,13 @@ export function commandUsage(name, definition) {
     const options = Object.entries(definition.options ?? {}).map(([key, schema]) => `[--${key}${schema.type === 'boolean' ? '' : ` <${schema.type}>`}]`);
     return [name, ...parameters, ...options].join(' ');
 }
-export function commandHelp(name, definition, prefix = '') {
-    return [prefix + commandUsage(name, definition), definition.description,
-        ...Object.entries(definition.params ?? {}).map(([key, schema]) => argumentHelp(key, schema)),
-        ...Object.entries(definition.options ?? {}).map(([key, schema]) => argumentHelp(`--${key}${schema.alias ? ` (-${schema.alias})` : ''}`, schema)),
+export function commandHelp(name, definition, prefix = '', locale = 'zh-CN') {
+    return [prefix + commandUsage(name, definition), commandDescription(definition, locale),
+        ...Object.entries(definition.params ?? {}).map(([key, schema]) => argumentHelp(key, schema, locale)),
+        ...Object.entries(definition.options ?? {}).map(([key, schema]) => argumentHelp(`--${key}${schema.alias ? ` (-${schema.alias})` : ''}`, schema, locale)),
     ].filter(Boolean).join('\n');
 }
-function argumentHelp(name, schema) {
-    return `  ${name}: ${schema.type}${schema.description ? ` — ${schema.description}` : ''}${schema.default !== undefined ? ` (default: ${typeof schema.default === 'function' ? 'dynamic' : JSON.stringify(schema.default)})` : ''}${schema.choices ? ` (${schema.choices.join(', ')})` : ''}${schema.min !== undefined ? ` min=${schema.min}` : ''}${schema.max !== undefined ? ` max=${schema.max}` : ''}`;
+function argumentHelp(name, schema, locale) {
+    const description = commandDescription(schema, locale);
+    return `  ${name}: ${schema.type}${description ? ` — ${description}` : ''}${schema.default !== undefined ? ` (${commandMessages(locale, 'defaultValue', { value: typeof schema.default === 'function' ? commandMessages(locale, 'dynamicValue') : JSON.stringify(schema.default) })})` : ''}${schema.choices ? ` (${schema.choices.join(', ')})` : ''}${schema.min !== undefined ? ` min=${schema.min}` : ''}${schema.max !== undefined ? ` max=${schema.max}` : ''}`;
 }

package/lib/command-index.d.ts

@@ -1,6 +1,8 @@
-import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot, type Locale } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
 import { type CommandValidationIssue } from './arguments.js';
+import { type CommandMenuEntry, type CommandMenuAppearance } from './command-menu.js';
+export type { CommandMenuEntry, CommandMenuAppearance } from './command-menu.js';
 import { type CommandExecutionLimit } from './execution-policy.js';
 export { CommandExecutionLimitedError } from './execution-policy.js';
 import { type CommandDefinition, type CommandParameterDefinition, type CommandParameterType, type CommandSegment } from './definition.js';
@@ -32,7 +34,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. */
 export interface CommandMenuNavigation {
@@ -41,19 +43,36 @@ export interface CommandMenuNavigation {
     readonly page: number;
     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;
+}
 export type CommandMatchInput = string | readonly Readonly<CommandSegment>[];
 export interface CommandMenuConfig {
-    readonly keyword: string;
+    /** Omission selects the built-in keyword for each operation's language. */
+    readonly keyword?: string;
 }
 export declare class CommandIndex {
     #private;
     private readonly snapshot;
     readonly $projection: "zhin.command-index/1";
     constructor(slots: readonly Readonly<CapabilitySlot<CommandDefinition>>[], snapshot: RuntimeSnapshot, menu?: CommandMenuConfig);
-    list(): readonly CommandDescriptor[];
+    list(locale?: Locale): readonly CommandDescriptor[];
+    /** Resolve a local static route without executing parameters, permission checks or commands. */
+    formatCommand(owner: PluginId, localPath: string, prefix: string | undefined, locale?: Locale): string | undefined;
+    /** Return the configured menu entry only when the calling environment is known. */
+    formatMenu(prefix: string | undefined, locale: Locale): string | undefined;
     has(name: string): boolean;
     execute(name: string, args?: readonly string[], operationSnapshot?: RuntimeSnapshot): Promise<unknown>;
-    dispatch(input: CommandMatchInput, source?: unknown, interactionFactory?: UserInteractionFactory, commandPrefix?: string, operationSnapshot?: RuntimeSnapshot): Promise<CommandDispatchResult>;
+    dispatch(input: CommandMatchInput, source?: unknown, interactionFactory?: UserInteractionFactory, commandPrefix?: string, operationSnapshot?: RuntimeSnapshot, localeOverride?: Locale): Promise<CommandDispatchResult>;
 }
 export declare function isCommandIndex(value: unknown): value is CommandIndex;
 /**

package/lib/command-index.js

@@ -1,9 +1,10 @@
 import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
-import { htmlRendererToken, } from '@zhin.js/plugin-runtime';
+import { htmlRendererToken, resolveLocale, } from '@zhin.js/plugin-runtime';
 import { bindOperationInput } from '@zhin.js/feature-kit';
 import { permissionHostToken, } from '@zhin.js/permission';
 import { commandAdapterMatches, toCommandPermissionSubject } from './permission-explanation.js';
-import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp } from './arguments.js';
+import { commandUsage, commandHelp, parseCommandArguments, requestsCommandHelp, commandValidationIssue } from './arguments.js';
+import { commandDescription, commandMessages } from './messages.js';
 import { MENU_PAGE_SIZE, readMenuAppearance, renderCommandMenu } from './command-menu.js';
 import { admitCommandExecution, admitDirectCommandExecution } from './execution-runtime.js';
 import { CommandExecutionLimitedError, normalizeExecutionPolicy } from './execution-policy.js';
@@ -90,6 +91,7 @@ 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,
             });
             claim([...new Set([occupancyKey(primarySegments, parameter), ...declaredRouteShapes(primarySegments, slot.definition)])], slot.source);
@@ -130,8 +132,30 @@ export class CommandIndex {
         this.#routes = Object.freeze(routes.sort(compareRoutes));
         this.#shortcuts = shortcuts;
     }
-    list() {
-        return this.#commands.map(toDescriptor);
+    list(locale = 'zh-CN') {
+        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, localPath, prefix, locale = 'zh-CN') {
+        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, locale) {
+        if (prefix === undefined || !this.#menu)
+            return undefined;
+        return prefix + (this.#menu.keyword ?? commandMessages(locale, 'menuKeyword'));
     }
     has(name) {
         try {
@@ -144,6 +168,7 @@ export class CommandIndex {
         }
     }
     async execute(name, args = [], operationSnapshot = this.snapshot) {
+        const locale = commandLocale(undefined, operationSnapshot);
         const match = this.#match(name, false);
         if (!match) {
             this.#diagnoseParameter(name);
@@ -153,28 +178,31 @@ export class CommandIndex {
             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), {});
+        const parsed = parseCommandArguments(definition, supplied, resolveDynamicParams(match.params, undefined), {}, locale);
         if (parsed.issues.length > 0)
-            throw new CommandArgumentValidationError(parsed.issues, commandHelp(match.command.name, definition));
+            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));
+            return await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options, { locale }));
         }
         finally {
             admission.release();
         }
     }
-    async dispatch(input, source = undefined, interactionFactory, commandPrefix = '', operationSnapshot = this.snapshot) {
+    async dispatch(input, source = undefined, interactionFactory, commandPrefix, operationSnapshot = this.snapshot, localeOverride) {
+        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,
                 });
@@ -192,12 +220,12 @@ export class CommandIndex {
                 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' });
@@ -205,18 +233,18 @@ export class CommandIndex {
             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));
+        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, { 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 });
     }
     #denied(record) {
@@ -334,16 +362,12 @@ export class CommandIndex {
     // ==========================================================================
     // 内置菜单命令
     // ==========================================================================
-    #dispatchMenu(input, commandPrefix, snapshot) {
+    #dispatchMenu(input, commandPrefix, snapshot, locale, keyword) {
         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);
+            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);
@@ -352,24 +376,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);
+                return this.#buildMenu(key, commandPrefix, keyword, snapshot, locale);
+            return this.#buildMenu(undefined, commandPrefix, keyword, snapshot, locale);
         }
         return undefined;
     }
-    #buildMenu(pluginKey, commandPrefix, keyword, snapshot, page = 1) {
+    #buildMenu(pluginKey, commandPrefix, keyword, snapshot, locale, page = 1) {
         const root = snapshot.root;
         const targetId = pluginKey
             ? `${root}/${pluginKey.split('.').join('/')}`
             : root;
         const node = snapshot.tree.get(targetId);
         if (!node)
-            return { value: `未找到插件: ${pluginKey}` };
+            return { value: commandMessages(locale, 'missingPlugin', { plugin: pluginKey ?? '' }) };
         const directCommands = this.#commands.filter((cmd) => cmd.slot.owner === targetId);
         const children = node.children
             .map((childId) => snapshot.tree.get(childId))
@@ -377,24 +401,25 @@ 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 <页码>」。` };
+            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 = [`=== ${displayKey} 指令菜单 ===`];
+        const lines = [commandMessages(locale, 'menuTitle', { plugin: displayKey })];
         if (pages > 1)
-            lines.push(`第 ${page}/${pages} 页 · ${directCommands.length} 条指令 · ${children.length} 个子插件`);
+            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;
@@ -403,32 +428,51 @@ export class CommandIndex {
         }
         if (directCommands.length === 0 && children.length === 0) {
             lines.push('');
-            lines.push('（暂无指令和子插件）');
+            lines.push(commandMessages(locale, 'emptyMenu'));
         }
         const hints = [];
         if (children.length > 0)
-            hints.push(`提示：使用「${commandPrefix}${keyword} <插件名>」查看子插件的指令`);
+            hints.push(commandMessages(locale, 'pluginHint', { command: `${commandPrefix}${keyword}` }));
         if (page > 1)
-            hints.push(`上一页：${invocation} --page ${page - 1}`);
+            hints.push(commandMessages(locale, 'previousPage', { command: `${invocation} --page ${page - 1}` }));
         if (page < pages)
-            hints.push(`下一页：${invocation} --page ${page + 1}`);
+            hints.push(commandMessages(locale, 'nextPage', { command: `${invocation} --page ${page + 1}` }));
         const hint = hints.length ? hints.join('\n') : undefined;
         if (hint) {
             lines.push('');
             lines.push(hint);
         }
         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);
-        return { menu, value: renderCommandMenu(displayKey, pageCommands.map(cmd => ({ name: `${commandPrefix}${cmd.name}`, description: cmd.description })), pageChildren.map(child => ({
+        const menu = 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, locale) {
+    return record.preferredSegments[locale] ?? record.segments;
+}
+function commandDisplayName(record, locale) {
+    return displayName(commandDisplaySegments(record, locale), record.parameter);
+}
+function commandLocale(source, snapshot) {
+    const locale = source && typeof source === 'object' && 'locale' in source ? source.locale : undefined;
+    return resolveLocale(locale ?? snapshot.config.get(snapshot.root)?.locale);
+}
 export function isCommandIndex(value) {
     return !!value && typeof value === 'object'
         && value.$projection === 'zhin.command-index/1';

package/lib/command-menu.d.ts

@@ -1,8 +1,9 @@
-interface MenuEntry {
+import type { Locale } from '@zhin.js/plugin-runtime';
+export interface CommandMenuEntry {
     readonly name: string;
     readonly description?: string;
 }
-interface MenuAppearance {
+export interface CommandMenuAppearance {
     readonly title?: string;
     readonly subtitle?: string;
     readonly accentColor?: string;
@@ -19,13 +20,13 @@ export interface CommandMenuSegment {
 }
 export declare const MENU_PAGE_SIZE = 30;
 /** Configuration is text/data, never an interpolated CSS or HTML fragment. */
-export declare function readMenuAppearance(value: unknown): MenuAppearance;
+export declare function readMenuAppearance(value: unknown): CommandMenuAppearance;
 /** Presentation only: the unified outbound pipeline owns image rendering and fallback. */
-export declare function renderCommandMenu(title: string, commands: readonly MenuEntry[], children: readonly MenuEntry[], hint: string | undefined, text: string, options?: {
+export declare function renderCommandMenu(title: string, commands: readonly CommandMenuEntry[], children: readonly CommandMenuEntry[], hint: string | undefined, text: string, options?: {
     readonly page?: number;
     readonly pages?: number;
+    readonly locale?: Locale;
     readonly commandTotal?: number;
     readonly pluginTotal?: number;
-    readonly appearance?: MenuAppearance;
+    readonly appearance?: CommandMenuAppearance;
 }): CommandMenuSegment;
-export {};