@zhin.js/command 1.1.10 → 1.1.12

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

package/lib/command-menu.js

@@ -1,3 +1,4 @@
+import { commandMessages } from './messages.js';
 export const MENU_PAGE_SIZE = 30;
 const escape = (value) => value.replace(/[&<>"']/gu, char => ({
     '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
@@ -46,6 +47,7 @@ function icon(name, plugin = false) {
 }
 /** Presentation only: the unified outbound pipeline owns image rendering and fallback. */
 export function renderCommandMenu(title, commands, children, hint, text, options = {}) {
+    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>.
@@ -60,7 +62,7 @@ export function renderCommandMenu(title, commands, children, hint, text, options
         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}
@@ -71,11 +73,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/lib/definition.d.ts

@@ -2,8 +2,8 @@
  * Command authoring API consumed from `zhin.js/command`.
  * @module zhin.js/command
  */
-import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import { type AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
+import { type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type OperationSession, type AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
 import type { UserInteraction } from '@zhin.js/interaction';
 import { type CommandExecutionPolicy } from './execution-policy.js';
 export type { CommandExecutionPolicy, CommandExecutionLimit } from './execution-policy.js';
@@ -41,6 +41,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;
@@ -95,6 +97,7 @@ export interface CommandParameterDefinition {
     /** `[...name]` / `[[...name]]` 捕获所有段，运行时值为 `string[]`。 */
     readonly rest?: boolean;
     readonly description?: string;
+    readonly descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
 }
 /** 场景：群 / 私聊 / 频道等。 */
 export interface CommandScene {
@@ -138,6 +141,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;
@@ -206,6 +211,16 @@ export interface CommandSession {
  * ```
  */
 export interface CommandContext<TConfig = unknown, 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>>;
@@ -218,6 +233,8 @@ export interface CommandContext<TConfig = unknown, TInput extends CommandMessage
     readonly input?: TInput;
     /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
     readonly $client: AdapterClient<TAdapter>;
+    /** Bound by the actual IM operation; direct CommandIndex.execute calls may have no Session. */
+    readonly session: OperationSession<TAdapter> | undefined;
     /**
      * 对话式交互输入。IM 派发时自动注入；无消息来源时为 `undefined`。
      */
@@ -230,6 +247,7 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
     /** @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;
     /**
@@ -243,6 +261,8 @@ export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput
      * 用户路由；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)`。
@@ -282,16 +302,29 @@ type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extend
     readonly params: keyof P extends never ? Readonly<Record<string, CommandParameterValue>> : InferCommandParams<P>;
     readonly options: InferCommandOptions<O>;
 };
+/** The returned declaration retains its platform, parameter schemas and callback result. */
+type DeclaredCommandAdapter<D> = D extends {
+    readonly adapter: infer A extends string;
+} ? A : D extends {
+    readonly adapter?: infer A extends string | undefined;
+} ? A : undefined;
+export type TypedCommandDefinition<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined, P extends CommandParams, O extends CommandOptions> = Omit<CommandDefinition<TConfig, TResult, TInput, TAdapter>, 'params' | 'options' | 'execute'> & {
+    readonly params?: P;
+    readonly options?: O;
+    execute(context: TypedCommandContext<TConfig, TInput, TAdapter, P, O>): TResult | Promise<TResult>;
+};
 /**
  * `defineCommand.withConfig<Config>()` 返回的定义函数：config 类型已固定，params / options / 返回值
  * 仍从定义推断。
  * @public
  */
-export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <TResult = unknown, const P extends CommandParams = {}, const O extends CommandOptions = {}>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>) => Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
-export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage, const P extends CommandParams = {}, const O extends CommandOptions = {}>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
+export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <const TResult = unknown, const P extends CommandParams = {}, const O extends CommandOptions = {}, const D extends CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> = CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> & D) => Readonly<TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>>;
+export declare function defineCommand<TConfig = unknown, const TResult = unknown, TInput extends CommandMessage = CommandMessage, const P extends CommandParams = {}, const O extends CommandOptions = {}, const D extends CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> = CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> & D): Readonly<TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>>;
 export declare namespace defineCommand {
     var withConfig: <TConfig = unknown, TInput extends CommandMessage = CommandMessage>() => CommandDefiner<TConfig, TInput>;
 }
+/** @internal Validate display-only translations without changing their fallback text. */
+export declare function validateDescriptionI18n(value: CommandDefinition['descriptionI18n']): void;
 /** @internal Convention-loader assembly helper. */
 export declare function bindCommandParameter<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined>(definition: CommandDefinition<TConfig, TResult, TInput, TAdapter>, parameter: CommandParameterDefinition | undefined): Readonly<CommandDefinition<TConfig, TResult, TInput, TAdapter>>;
 /** @internal Runtime validation for convention-discovered modules. */
@@ -302,8 +335,27 @@ export declare function parseCommandDefinition(value: unknown): CommandDefinitio
  * @internal Command projection helper.
  */
 export declare function resolveDynamicParams(params: Readonly<Record<string, CommandDynamicValue>>, source: unknown): Readonly<Record<string, CommandParameterValue>>;
-/** @internal Command dispatcher assembly helper. */
-export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown, segments?: readonly Readonly<CommandSegment>[], interaction?: UserInteraction, adapter?: string, options?: Readonly<Record<string, CommandParameterValue>>): CommandContext;
+/** Parsed invocation values, independent of the caller's transport and lifetime. */
+export interface CommandInvocationArguments {
+    readonly args: readonly string[];
+    readonly params?: Readonly<Record<string, CommandParameterValue>>;
+    readonly options?: Readonly<Record<string, CommandParameterValue>>;
+    readonly segments?: readonly Readonly<CommandSegment>[];
+}
+/** Author and lifetime authority captured by the dispatcher for this invocation. */
+export interface CommandInvocationOperation {
+    readonly snapshot: RuntimeSnapshot;
+    readonly ownerId: PluginId;
+    readonly input?: unknown;
+    readonly interaction?: UserInteraction;
+    readonly adapter?: string;
+    readonly presentation?: Readonly<{
+        locale: Locale;
+        formatCommand?: (localPath: string, owner?: PluginId) => string | undefined;
+    }>;
+}
+/** @internal Command dispatcher assembly helper; each value has one owner. */
+export declare function createCommandContext(operation: CommandInvocationOperation, invocation: CommandInvocationArguments): CommandContext;
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
  * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。

package/lib/definition.js

@@ -1,4 +1,9 @@
-import { createCapabilityContext, readOperationClient, readOperationInputSignal, } from '@zhin.js/feature-kit';
+/**
+ * Command authoring API consumed from `zhin.js/command`.
+ * @module zhin.js/command
+ */
+import { resolveLocale } from '@zhin.js/plugin-runtime';
+import { createCapabilityContext, readOperationClient, readOperationSession, readOperationInputSignal, } from '@zhin.js/feature-kit';
 import { assertPermitSyntax } from '@zhin.js/permission';
 import { validateArgumentSchemas } from './arguments.js';
 import { normalizeExecutionPolicy } from './execution-policy.js';
@@ -37,12 +42,23 @@ export function defineCommand(definition) {
         }
     }
     validateArgumentSchemas(definition.params, definition.options);
+    validateDescriptionI18n(definition.descriptionI18n);
     validateCommandAlias(definition.alias);
+    validatePreferredAliases(definition);
     validateCommandPermit(definition.permit);
     validateCommandShortcutShape(definition.shortcut);
     const execution = normalizeExecutionPolicy(definition.execution);
     return Object.freeze({ $feature: commandBrand, ...definition, ...(execution ? { execution } : {}) });
 }
+/** @internal Validate display-only translations without changing their fallback text. */
+export function validateDescriptionI18n(value) {
+    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 / 返回值仍从定义推断。
  *
@@ -66,6 +82,19 @@ function validateAdapterName(adapter) {
         throw new TypeError('Command adapter must be a non-empty string');
     }
 }
+function validatePreferredAliases(definition) {
+    const preferred = definition.preferredAliasI18n;
+    if (preferred === undefined)
+        return;
+    validateDescriptionI18n(preferred);
+    const normalize = (value) => 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) {
     if (alias === undefined)
         return;
@@ -127,6 +156,8 @@ export function parseCommandDefinition(value) {
     }
     validateAdapterName(definition.adapter);
     normalizeExecutionPolicy(definition.execution);
+    validateCommandAlias(definition.alias);
+    validatePreferredAliases(definition);
     return definition;
 }
 /**
@@ -142,8 +173,10 @@ export function resolveDynamicParams(params, source) {
     }
     return Object.freeze(resolved);
 }
-/** @internal Command dispatcher assembly helper. */
-export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction, adapter, options = Object.freeze({})) {
+/** @internal Command dispatcher assembly helper; each value has one owner. */
+export function createCommandContext(operation, invocation) {
+    const { snapshot, ownerId, input, interaction, adapter, presentation } = operation;
+    const { args, params = {}, options = {}, segments = [] } = invocation;
     const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
     const session = resolveCommandSession(input);
     const parameterValues = { __proto__: null, ...params };
@@ -151,6 +184,8 @@ export function createCommandContext(snapshot, ownerId, args, params = Object.fr
     const result = {
         ...context,
         ...session,
+        locale: presentation?.locale ?? resolveLocale(snapshot.config.get(snapshot.root)?.locale),
+        formatCommand: presentation?.formatCommand ?? (() => undefined),
         args: Object.freeze([...args]),
         params: Object.freeze(parameterValues),
         options: Object.freeze(optionValues),
@@ -158,6 +193,10 @@ export function createCommandContext(snapshot, ownerId, args, params = Object.fr
         ...(input !== undefined ? { input: input } : {}),
         ...(interaction !== undefined ? { interaction } : {}),
     };
+    Object.defineProperty(result, 'session', {
+        enumerable: true,
+        get: () => readOperationSession(input, adapter),
+    });
     Object.defineProperty(result, '$client', {
         enumerable: true,
         get: () => readOperationClient(input, adapter),
@@ -170,6 +209,20 @@ export function createCommandContext(snapshot, ownerId, args, params = Object.fr
  * @internal Command dispatcher projection helper.
  */
 export function resolveCommandSession(input) {
+    const operation = readOperationSession(input);
+    if (operation) {
+        const endpoint = input && typeof input === 'object' ? input.endpointId : undefined;
+        const sender = operation.sender;
+        const roles = [...new Set([...sender?.authorizationRoles ?? [], ...sender?.platformRoles ?? []])];
+        return Object.freeze({
+            adapter: operation.scene.endpoint.adapter,
+            ...(typeof endpoint === 'string' && endpoint ? { endpoint } : {}),
+            scene: Object.freeze({ id: operation.scene.id, type: operation.scene.kind,
+                ...(operation.scene.name !== undefined ? { name: operation.scene.name } : {}) }),
+            ...(sender ? { sender: Object.freeze({ id: sender.id, ...(sender.name !== undefined ? { name: sender.name } : {}),
+                    role: Object.freeze(roles.length ? roles : ['user']) }) } : {}),
+        });
+    }
     if (!isCommandMessageLike(input))
         return Object.freeze({});
     const metadata = input.metadata && typeof input.metadata === 'object'

package/lib/index.d.ts

@@ -10,4 +10,4 @@ export * from './permission-explanation.js';
 export { CONVERSATION_MANAGER_PERMIT, canManageConversation, assertBuiltinPermits, checkBuiltinPermit, checkBuiltinPermitList, isBuiltinPermit, isPlatformPermit, parsePermitName, type ParsedPermit, type PermitKind, } from './permit.js';
 export { bindCommandSource, CommandPathSyntaxError, commandFeatureId, type BoundCommandSource, default as commandFeature, } from './provider.js';
 export { default } from './provider.js';
-export type { CommandValidationIssue } from './arguments.js';
+export type { CommandValidationIssue, CommandValidationIssueCode } from './arguments.js';

package/lib/messages.d.ts

@@ -0,0 +1,8 @@
+import { type Locale } from '@zhin.js/plugin-runtime';
+/** Translates only display metadata explicitly supplied by its author. */
+export declare function commandDescription(value: Readonly<{
+    description?: string;
+    descriptionI18n?: Readonly<Partial<Record<Locale, string>>>;
+}>, locale: Locale): string | undefined;
+/** Static dictionaries; the caller supplies the operation's language. */
+export declare const commandMessages: (locale: Locale | undefined, key: "choices" | "defaultValue" | "menuKeyword" | "invalidPage" | "missingPlugin" | "pageOutOfRange" | "menuTitle" | "menuSummary" | "childPlugins" | "emptyMenu" | "pluginHint" | "previousPage" | "nextPage" | "guideTitle" | "guideSubtitle" | "commandCount" | "pluginCount" | "commandIndex" | "pluginIndex" | "guideEmpty" | "helpHint" | "genericHelpHint" | "expectedType" | "expectedArray" | "minimum" | "maximum" | "invalidFormat" | "invalidValue" | "unknownOption" | "duplicateOption" | "defaultUndefined" | "parameterUndefined" | "missingOption" | "unexpectedArguments" | "invalidParameter" | "dynamicValue" | "noAdapter" | "missingEndpoint" | "adapterComparison" | "conditionMismatch" | "missingPermissionHost" | "missingEvidence" | "noPermit" | "uncheckedConditions" | "conditionsMatch" | "unconstrained" | "simulatedIdentity" | "unevaluatedCode" | "defaultedRole", values?: import("@zhin.js/plugin-runtime").MessageValues) => string;

package/lib/messages.js

@@ -0,0 +1,57 @@
+import { createMessages } from '@zhin.js/plugin-runtime';
+/** Translates only display metadata explicitly supplied by its author. */
+export function commandDescription(value, locale) {
+    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' },
+});

package/lib/permission-explanation.d.ts

@@ -1,5 +1,6 @@
 import { type PermissionSubject, type PermissionConditionExplanation } from '@zhin.js/permission';
 import type { CommandDescriptor } from './command-index.js';
+import { type Locale } from '@zhin.js/plugin-runtime';
 /** The exact subject projection used by the real command permit gate. No factories or checkers run. */
 export declare function toCommandPermissionSubject(source: unknown): PermissionSubject;
 /** Exact authoring adapter restriction, distinct from builtin adapter(...) matching. */
@@ -12,6 +13,7 @@ export declare function explainCommandPermissions(command: Pick<CommandDescripto
     source?: unknown;
     rolesKnown?: boolean;
     permissionHost: CommandPermissionHostStatus;
+    locale?: Locale;
 }>): Readonly<{
     permissionHost: CommandPermissionHostStatus;
     adapter: Readonly<PermissionConditionExplanation>;

package/lib/permission-explanation.js

@@ -1,6 +1,8 @@
 import { operationClientAdapter } from '@zhin.js/feature-kit';
 import { explainPermitRules, toPermissionSubject } from '@zhin.js/permission';
 import { resolveCommandSender, resolveCommandSession } from './definition.js';
+import { resolveLocale } from '@zhin.js/plugin-runtime';
+import { commandMessages } from './messages.js';
 /** The exact subject projection used by the real command permit gate. No factories or checkers run. */
 export function toCommandPermissionSubject(source) {
     const projected = toPermissionSubject(source);
@@ -13,6 +15,7 @@ export function commandAdapterMatches(command, source) {
 }
 /** Read-only hypothetical conditions. A match is not permission to execute the command. */
 export function explainCommandPermissions(command, options) {
+    const locale = resolveLocale(options.locale);
     const projected = toCommandPermissionSubject(options.source);
     const inputSender = options.source && typeof options.source === 'object'
         ? options.source.sender : undefined;
@@ -27,28 +30,28 @@ export function explainCommandPermissions(command, options) {
         && subject.sender?.role.length === 1 && subject.sender.role[0] === 'user';
     const actualAdapter = operationClientAdapter(options.source);
     const adapter = !command.adapter
-        ? { outcome: 'not_evaluated', reason: '命令未声明 adapter 约束' }
-        : !actualAdapter ? { outcome: 'unknown', reason: '未选择当前 Endpoint，无法判断命令的精确 adapter 约束' }
-            : { outcome: commandAdapterMatches(command, options.source) ? 'match' : 'mismatch', reason: '命令 adapter 与当前 Endpoint 声明的原生适配器精确比较；未探测在线状态' };
-    const rules = explainPermitRules(command.permit ?? [], subject, { rolesKnown: options.rolesKnown });
+        ? { outcome: 'not_evaluated', reason: commandMessages(locale, 'noAdapter') }
+        : !actualAdapter ? { outcome: 'unknown', reason: commandMessages(locale, 'missingEndpoint') }
+            : { outcome: commandAdapterMatches(command, options.source) ? 'match' : 'mismatch', reason: commandMessages(locale, 'adapterComparison') };
+    const rules = explainPermitRules(command.permit ?? [], subject, { rolesKnown: options.rolesKnown, locale });
     const conditions = [...(command.adapter ? [adapter] : []), ...rules];
     let summary;
     if (conditions.some(item => item.outcome === 'mismatch'))
-        summary = { outcome: 'mismatch', reason: '至少一个声明条件与假设输入不符；这不是实际准入检查' };
+        summary = { outcome: 'mismatch', reason: commandMessages(locale, 'conditionMismatch') };
     else if ((rules.length > 0 && options.permissionHost !== 'present') || conditions.some(item => item.outcome === 'unknown')) {
         summary = { outcome: 'unknown', reason: rules.length > 0 && options.permissionHost !== 'present'
-                ? 'PermissionHost 缺失或无法确认；不能推断命令可执行' : '存在缺少依据的条件，不能推断命令可执行' };
+                ? commandMessages(locale, 'missingPermissionHost') : commandMessages(locale, 'missingEvidence') };
     }
     else if (rules.length === 0)
-        summary = { outcome: 'not_evaluated', reason: '命令未声明 permit 限制；这不表示已获得执行权限' };
+        summary = { outcome: 'not_evaluated', reason: commandMessages(locale, 'noPermit') };
     else if (conditions.some(item => item.outcome === 'not_evaluated'))
-        summary = { outcome: 'not_evaluated', reason: '存在未执行的平台或自定义条件，不能推断命令可执行' };
+        summary = { outcome: 'not_evaluated', reason: commandMessages(locale, 'uncheckedConditions') };
     else
-        summary = { outcome: 'match', reason: '已解释的 builtin 条件与假设输入匹配；不代表真实授权或命令可执行' };
+        summary = { outcome: 'match', reason: commandMessages(locale, 'conditionsMatch') };
     return Object.freeze({ permissionHost: options.permissionHost, adapter: Object.freeze(adapter), rules, summary: Object.freeze(summary),
-        unconstrained: Object.freeze(['已解释的 builtin 规则不检查具体 Endpoint、parent 或 thread；保留完整目标不等于这些维度受规则限制']),
-        assumptions: Object.freeze(['身份与角色仅用于模拟，未向平台核实', '未执行命令、动态默认值、平台或自定义 checker',
+        unconstrained: Object.freeze([commandMessages(locale, 'unconstrained')]),
+        assumptions: Object.freeze([commandMessages(locale, 'simulatedIdentity'), commandMessages(locale, 'unevaluatedCode'),
             ...(defaultedRoles
-                ? ['canonical 输入未附角色时按命令运行时默认 user 解释；这不是已核验的平台角色'] : [])]),
+                ? [commandMessages(locale, 'defaultedRole')] : [])]),
     });
 }

package/lib/provider.js

@@ -223,7 +223,7 @@ const commandFeature = defineFeatureProvider({
             const rawKeyword = rootConfig?.menuKeyword;
             const menu = rawKeyword === false || rawKeyword === ''
                 ? undefined
-                : { keyword: typeof rawKeyword === 'string' ? rawKeyword : '菜单' };
+                : typeof rawKeyword === 'string' ? { keyword: rawKeyword } : {};
             return { value: new CommandIndex(slots, context.snapshot, menu) };
         },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.10",
+  "version": "1.1.12",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -21,10 +21,10 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.1.8",
+    "@zhin.js/feature-kit": "1.1.10",
     "@zhin.js/interaction": "1.1.2",
-    "@zhin.js/permission": "1.1.8",
-    "@zhin.js/plugin-runtime": "1.1.16"
+    "@zhin.js/permission": "1.1.10",
+    "@zhin.js/plugin-runtime": "1.1.18"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",