@zhin.js/command 1.1.10 → 1.1.11

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,7 +2,7 @@
  * Command authoring API consumed from `zhin.js/command`.
  * @module zhin.js/command
  */
-import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import { 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';
@@ -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>>;
@@ -230,6 +245,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 +259,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)`。
@@ -292,6 +310,8 @@ export declare function defineCommand<TConfig = unknown, TResult = unknown, TInp
 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. */
@@ -303,7 +323,10 @@ export declare function parseCommandDefinition(value: unknown): CommandDefinitio
  */
 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;
+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>>, presentation?: Readonly<{
+    locale: Locale;
+    formatCommand?: (localPath: string, owner?: PluginId) => string | undefined;
+}>): CommandContext;
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
  * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。

package/lib/definition.js

@@ -1,3 +1,8 @@
+/**
+ * Command authoring API consumed from `zhin.js/command`.
+ * @module zhin.js/command
+ */
+import { resolveLocale } from '@zhin.js/plugin-runtime';
 import { createCapabilityContext, readOperationClient, readOperationInputSignal, } from '@zhin.js/feature-kit';
 import { assertPermitSyntax } from '@zhin.js/permission';
 import { validateArgumentSchemas } from './arguments.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;
 }
 /**
@@ -143,7 +174,7 @@ 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({})) {
+export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction, adapter, options = Object.freeze({}), presentation) {
     const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
     const session = resolveCommandSession(input);
     const parameterValues = { __proto__: null, ...params };
@@ -151,6 +182,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),

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.11",
   "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.9",
     "@zhin.js/interaction": "1.1.2",
-    "@zhin.js/permission": "1.1.8",
-    "@zhin.js/plugin-runtime": "1.1.16"
+    "@zhin.js/permission": "1.1.9",
+    "@zhin.js/plugin-runtime": "1.1.17"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

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}` : ''}`;
 }