@zhin.js/command 1.1.10 → 1.1.12

package/src/arguments.ts

@@ -2,10 +2,30 @@ import type {
   CommandDefinition, CommandParams, CommandOptions, CommandParamSchema,
   CommandParameterValue, CommandSegment, CommandSession,
 } from './definition.js';
+import type { Locale } from '@zhin.js/plugin-runtime';
+import { commandDescription, commandMessages } from './messages.js';
+
+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 function commandValidationIssue(
+  code: Exclude<CommandValidationIssueCode, 'custom'>,
+  field: string,
+  locale: Locale,
+  parameters: Readonly<Record<string, string | number>> = {},
+): CommandValidationIssue {
+  const values = Object.freeze({ field, ...parameters });
+  return Object.freeze({ field, code, parameters: values, message: commandMessages(locale, code, values) });
 }
 export interface ParsedCommandArguments {
   readonly params: Readonly<Record<string, CommandParameterValue>>;
@@ -63,6 +83,11 @@ function validateSchema(name: string, schema: CommandParamSchema): void {
   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') {
     if (Array.isArray(schema.default) && !schema.rest) throw new TypeError(`Command argument ${name} requires rest: true for an array default`);
@@ -161,22 +186,23 @@ function valueMatches(schema: CommandParamSchema, value: unknown): boolean {
   if (schema.type === 'image') return typeof value === 'string' || !!value && typeof value === 'object';
   return typeof value === 'string';
 }
-function validateValue(field: string, schema: CommandParamSchema, value: CommandParameterValue, session: CommandSession): CommandValidationIssue | undefined {
-  if (schema.rest && !Array.isArray(value)) return { field, message: `${field}: expected an array of ${schema.type}` };
+function validateValue(field: string, schema: CommandParamSchema, value: CommandParameterValue, session: CommandSession, locale: Locale = 'zh-CN'): CommandValidationIssue | undefined {
+  if (schema.rest && !Array.isArray(value)) 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}` };
+    if (!valueMatches(schema, item)) 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}` };
-    if (schema.max !== undefined && (size === undefined || size > schema.max)) return { field, message: `${field}: maximum ${schema.max}` };
-    if (schema.choices && !schema.choices.includes(item)) return { field, message: `${field}: expected one of ${schema.choices.join(', ')}` };
+    if (schema.min !== undefined && (size === undefined || size < schema.min)) return commandValidationIssue('minimum', field, locale, { minimum: schema.min });
+    if (schema.max !== undefined && (size === undefined || size > schema.max)) return commandValidationIssue('maximum', field, locale, { maximum: schema.max });
+    if (schema.choices && !schema.choices.includes(item)) 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` };
+      if (typeof item !== 'string' || !pattern.test(item)) 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. */
@@ -185,6 +211,7 @@ export function parseCommandArguments(
   remaining: readonly Readonly<CommandSegment>[],
   initial: Readonly<Record<string, CommandParameterValue>>,
   session: CommandSession,
+  locale: Locale = 'zh-CN',
 ): ParsedCommandArguments {
   const params: Record<string, CommandParameterValue> = { __proto__: null, ...initial };
   const options: Record<string, CommandParameterValue> = { __proto__: null };
@@ -203,10 +230,10 @@ export function parseCommandArguments(
     const [rawFlag, inline] = token.value.split(/=(.*)/u);
     const flag = rawFlag ?? token.value;
     const name = optionNames.get(flag);
-    if (!name) { issues.push({ field: flag, message: `Unknown option ${flag}` }); continue; }
+    if (!name) { 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}` }); continue; }
+    if (Object.hasOwn(options, name)) { issues.push(commandValidationIssue('duplicateOption', name, locale)); continue; }
     let value: CommandParameterValue | undefined;
     if (inline !== undefined) value = convert(schema, { value: inline, quoted: false });
     else if (schema.type === 'boolean') value = true;
@@ -214,14 +241,14 @@ export function parseCommandArguments(
       const next = tokens[index + 1];
       if (isTextToken(next) && !(!next.quoted && /^--?[a-zA-Z]/u.test(next.value))) { index++; value = convert(schema, next); }
     }
-    if (value === undefined) issues.push({ field: name, message: `--${name}: expected ${schema.type}` });
+    if (value === undefined) issues.push(commandValidationIssue('expectedType', name, locale, { field: `--${name}`, type: schema.type }));
     else options[name] = value;
   }
   for (const [name, schema] of Object.entries(schemas ?? {})) {
     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` });
-    else if (options[name] !== undefined) { const issue = validateValue(`--${name}`, schema, options[name], session); if (issue) issues.push(issue); }
-    else if (schema.optional === false) issues.push({ field: name, message: `Missing option --${name}` });
+    if (Object.hasOwn(options, name) && options[name] === undefined) issues.push(commandValidationIssue('defaultUndefined', name, locale, { field: `--${name}` }));
+    else if (options[name] !== undefined) { const issue = validateValue(`--${name}`, schema, options[name], session, locale); if (issue) issues.push(issue); }
+    else if (schema.optional === false) issues.push(commandValidationIssue('missingOption', name, locale));
   }
   const declared = Object.entries(definition.params ?? {});
   for (const [name, declaredSchema] of declared) {
@@ -233,7 +260,7 @@ export function parseCommandArguments(
         const converted = schema.type === 'text'
           ? 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}` });
+        if (converted.some((item) => item === undefined)) issues.push(commandValidationIssue('expectedType', name, locale, { type: schema.type }));
         else if (converted.length > 0 || schema.optional) value = converted as readonly (string | number | boolean | Readonly<Record<string, unknown>>)[];
       } else if (schema.type === 'text') {
         const raw: string[] = [];
@@ -246,20 +273,20 @@ export function parseCommandArguments(
         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;
         }
       }
       if (value !== undefined) params[name] = value;
       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` });
-    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); if (issue) issues.push(issue); }
+    if (Object.hasOwn(params, name) && params[name] === 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, locale); if (issue) issues.push(issue); }
   }
-  if (declared.length > 0 && !definition.$parameter && positional.length > 0) issues.push({ field: 'arguments', message: 'Unexpected arguments' });
+  if (declared.length > 0 && !definition.$parameter && positional.length > 0) 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) });
 }
 
@@ -269,12 +296,13 @@ export function commandUsage(name: string, definition: CommandDefinition): strin
   const options = Object.entries(definition.options ?? {}).map(([key, schema]) => `[--${key}${schema.type === 'boolean' ? '' : ` <${schema.type}>`}]`);
   return [name, ...parameters, ...options].join(' ');
 }
-export function commandHelp(name: string, definition: CommandDefinition, prefix = ''): string {
-  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: string, definition: CommandDefinition, prefix = '', locale: Locale = 'zh-CN'): string {
+  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: string, schema: CommandParamSchema): string {
-  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: string, schema: CommandParamSchema, locale: Locale): string {
+  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/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';
@@ -54,6 +58,24 @@ export interface CommandDescriptor {
   readonly shortcut?: readonly string[];
 }
 
+/** One dispatch reads the caller's exact operation generation and presentation. */
+export interface CommandDispatchRequest {
+  readonly input: CommandMatchInput;
+  readonly source?: unknown;
+  readonly interactionFactory?: UserInteractionFactory;
+  readonly commandPrefix?: string;
+  readonly snapshot?: RuntimeSnapshot;
+  readonly locale?: Locale;
+}
+/** Presentation and generation shared across one menu lookup/render operation. */
+interface CommandMenuContext {
+  readonly commandPrefix: string;
+  readonly keyword: string;
+  readonly snapshot: RuntimeSnapshot;
+  readonly locale: Locale;
+}
+interface CommandMenuSelection { readonly pluginKey?: string; readonly page?: number }
+
 export interface CommandDispatchResult {
   readonly matched: boolean;
   readonly status: 'unmatched' | 'invalid' | 'denied' | 'limited' | 'executed';
@@ -63,7 +85,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 +96,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 +157,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 +235,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 +290,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 +326,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,33 +335,33 @@ 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));
+      return await definition.execute(createCommandContext({ snapshot: operationSnapshot, ownerId: match.command.slot.owner,
+        adapter: definition.adapter, presentation: { locale } }, {
+        args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options,
+      }));
     } finally {
       admission.release();
     }
   }
 
-  async dispatch(
-    input: CommandMatchInput,
-    source: unknown = undefined,
-    interactionFactory?: UserInteractionFactory,
-    commandPrefix = '',
-    operationSnapshot: RuntimeSnapshot = this.snapshot,
-  ): Promise<CommandDispatchResult> {
+  async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot,
+    locale: localeOverride }: CommandDispatchRequest): 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, { commandPrefix: prefix, snapshot: 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 +376,31 @@ 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));
+    const value = await definition.execute(createCommandContext({
+      snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
+      interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
+      presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath,
+        source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
+    }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
     return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
   }
 
@@ -446,13 +512,11 @@ export class CommandIndex {
   // 内置菜单命令
   // ==========================================================================
 
-  #dispatchMenu(input: CommandMatchInput, commandPrefix: string, snapshot: RuntimeSnapshot): CommandMenuResult | undefined {
+  #dispatchMenu(input: CommandMatchInput, context: CommandMenuContext): CommandMenuResult | undefined {
+    const { commandPrefix, keyword, locale } = context;
     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({}, context);
     if (text.startsWith(keyword + ' ')) {
       const key = text.slice(keyword.length + 1).trim();
       const args = key.split(/\s+/u);
@@ -461,24 +525,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({ pluginKey: flag === 1 ? args[0] : undefined, page: Number(pageText) }, context);
       }
-      if (key) return this.#buildMenu(key, commandPrefix, keyword, snapshot);
-      return this.#buildMenu(undefined, commandPrefix, keyword, snapshot);
+      if (key) return this.#buildMenu({ pluginKey: key }, context);
+      return this.#buildMenu({}, context);
     }
     return undefined;
   }
 
-  #buildMenu(pluginKey: string | undefined, commandPrefix: string, keyword: string, snapshot: RuntimeSnapshot, page = 1): CommandMenuResult {
+  #buildMenu({ pluginKey, page = 1 }: CommandMenuSelection, { commandPrefix, keyword, snapshot, locale }: CommandMenuContext): 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 +551,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 +581,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 +595,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';