@steerable/agent-shell-web 0.6.52 → 0.6.55

package/src/components/settings/model-capabilities.ts

@@ -1,3 +1,4 @@
+import { t } from '@/i18n';
 import type { GatewayModelEntry } from '@/lib/local-api';
 
 /**
@@ -18,17 +19,17 @@ export interface ModelCapabilityChip {
 const MODALITY_ORDER = ['image', 'pdf', 'audio', 'video'] as const;
 
 const MODALITY_LABELS: Record<(typeof MODALITY_ORDER)[number], string> = {
-  image: '图像',
+  image: 'Image',
   pdf: 'PDF',
-  audio: '音频',
-  video: '视频',
+  audio: 'Audio',
+  video: 'Video',
 };
 
 const MODALITY_TITLES: Record<(typeof MODALITY_ORDER)[number], string> = {
-  image: '支持图像输入',
-  pdf: '支持 PDF 输入',
-  audio: '支持音频输入',
-  video: '支持视频输入',
+  image: 'Supports image input',
+  pdf: 'Supports PDF input',
+  audio: 'Supports audio input',
+  video: 'Supports video input',
 };
 
 /** 上下文窗口：1_000_000 → 1M，131_072 → 131K。 */
@@ -45,8 +46,8 @@ export function formatContextWindow(window: number | null | undefined): string |
 function unknownChip(): ModelCapabilityChip {
   return {
     key: 'unknown',
-    label: '未识别',
-    title: '网关目录未匹配到该 id，思考档位与多模态未核实。',
+    label: t('Unrecognized'),
+    title: t('The gateway catalog has no match for this id. Thinking levels and multimodal input are unverified.'),
     kind: 'unknown',
   };
 }
@@ -68,8 +69,8 @@ export function modelCapabilityChips(
     const joined = levels.join(' / ');
     chips.push({
       key: 'reasoning',
-      label: options?.detail ? `思考（${joined}）` : '思考',
-      title: `支持思考档位：${joined}`,
+      label: options?.detail ? t('Thinking ({levels})', { levels: joined }) : t('Thinking'),
+      title: t('Supported thinking levels: {levels}', { levels: joined }),
       kind: 'reasoning',
     });
   }
@@ -80,8 +81,8 @@ export function modelCapabilityChips(
     seen.add(modality);
     chips.push({
       key: modality,
-      label: MODALITY_LABELS[modality],
-      title: MODALITY_TITLES[modality],
+      label: t(MODALITY_LABELS[modality]),
+      title: t(MODALITY_TITLES[modality]),
       kind: 'modality',
     });
   }
@@ -92,7 +93,7 @@ export function modelCapabilityChips(
     chips.push({
       key: key,
       label: modality,
-      title: `输入模态：${modality}`,
+      title: t('Input modality: {modality}', { modality }),
       kind: 'modality',
     });
   }
@@ -102,7 +103,7 @@ export function modelCapabilityChips(
     chips.push({
       key: 'window',
       label: windowLabel,
-      title: `上下文窗口 ${entry.window} tokens`,
+      title: t('Context window {window} tokens', { window: entry.window ?? '' }),
       kind: 'window',
     });
   }

package/src/components/settings/preset-choice-model.ts

@@ -5,6 +5,7 @@
  * 载荷之间的转换，不硬编码任何厂商参数。
  */
 
+import { t } from '@/i18n';
 import type {
   ProviderPresetDescriptor,
   ProviderPresetOverride,
@@ -28,12 +29,12 @@ export function overrideFromDescriptor(d: ProviderPresetDescriptor): ProviderPre
 /** 选择器选项标签：`host + 前缀*`，缺省键名退化为「未命名」。 */
 export function descriptorLabel(d: ProviderPresetDescriptor): string {
   const parts = [d.host, d.modelPrefix ? `${d.modelPrefix}*` : null].filter(Boolean);
-  return parts.join(' + ') || '（未命名预制）';
+  return parts.join(' + ') || t('(Unnamed preset)');
 }
 
 /** 预制参数的一行摘要，用于生效预览。 */
 export function summarizePreset(p: ProviderPresetOverride | null): string {
-  if (!p) return '不下发额外采样参数';
+  if (!p) return t('No extra sampling parameters are sent');
   const parts: string[] = [];
   if (p.temperature != null) parts.push(`temperature ${p.temperature}`);
   if (p.topP != null) parts.push(`top_p ${p.topP}`);
@@ -42,7 +43,9 @@ export function summarizePreset(p: ProviderPresetOverride | null): string {
   if (p.extraBody) {
     for (const [k, v] of Object.entries(p.extraBody)) parts.push(`${k} ${JSON.stringify(v)}`);
   }
-  return parts.length > 0 ? parts.join(' · ') : '不下发额外采样参数（该厂商最优请求即不带采样字段）';
+  return parts.length > 0
+    ? parts.join(' · ')
+    : t('No extra sampling parameters are sent (the best request for this vendor omits sampling fields)');
 }
 
 export function overridesEqual(a: ProviderPresetOverride, b: ProviderPresetOverride): boolean {

package/src/fixtures/browser-dev-data.json

@@ -6,11 +6,11 @@
     {
       "id": "local-assistant",
       "slug": "local-assistant",
-      "name": "电脑操作员",
+      "name": "Computer operator",
       "icon": "Cpu",
       "color": "#4f46e5",
-      "description": "默认本地助手，可调用 shell、文件与 MCP 工具。",
-      "rolePrompt": "你是 **电脑操作员**，本地离线助手，回答时清晰、可执行。",
+      "description": "Default local assistant. It can use the shell, files, and MCP tools.",
+      "rolePrompt": "You are **Computer operator**, a local offline assistant. Answer clearly and in steps that can be carried out.",
       "forbiddenPrompt": null,
       "skillIds": [],
       "toolPolicy": {
@@ -27,11 +27,11 @@
     {
       "id": "data-analyst",
       "slug": "data-analyst",
-      "name": "数据分析助手",
+      "name": "Data analyst",
       "icon": "Activity",
       "color": "#0ea5e9",
-      "description": "处理本地 CSV 与日志文件：清洗、统计、出图与汇总报告。",
-      "rolePrompt": "你是 **数据分析助手**，专注本地数据文件的清洗、统计与可视化。\n工作语言：中文。回答简洁、结论先行。\n\n工作纪律：\n1) 先探查文件结构再动手；\n2) 每一步都说明做了什么；\n3) 结果用表格或要点呈现。",
+      "description": "Works on local CSV and log files: cleaning, stats, charts, and a summary.",
+      "rolePrompt": "You are **Data analyst**. You clean, summarize, and chart local data files.\nBe concise and lead with the conclusion.\n\nWorking rules:\n1) Inspect the file structure before changing it;\n2) Say what each step did;\n3) Present results as a table or bullets.",
       "forbiddenPrompt": null,
       "skillIds": [],
       "toolPolicy": {
@@ -48,11 +48,11 @@
     {
       "id": "all-round-assistant",
       "slug": "all-round-assistant",
-      "name": "智能助手",
+      "name": "Assistant",
       "icon": "🔮",
       "color": "#a855f7",
-      "description": "全能智能体，自动加载全部已安装本地技能和工具，无需限定条件。",
-      "rolePrompt": "你是 **智能助手**，一个具备高权限且集成了全部本地技能（Skills）的行动体。\n你具备完整的本地命令执行（local_exec_shell）、文件读写与数据分析能力。\n你的系统提示词中已经无条件加载了所有已安装的本地技能与工具。\n请根据用户的需求，直接、高效地调用最合适的本地工具或执行脚本来解决任务。",
+      "description": "General agent. It loads every installed local skill and tool, with no extra trigger.",
+      "rolePrompt": "You are **Assistant**, with full access to every installed local skill.\nYou can run local commands (local_exec_shell), read and write files, and analyze data.\nEvery installed local skill and tool is already in your system prompt.\nCall the most direct local tool or script for the task.",
       "forbiddenPrompt": null,
       "skillIds": [],
       "toolPolicy": {
@@ -72,7 +72,7 @@
       "id": "8286e3c8-2d83-409e-930a-3e99b2004d41",
       "projectId": null,
       "userId": "local",
-      "title": "你好",
+      "title": "Hello",
       "agentId": "local-assistant",
       "createdAt": "2026-07-01T10:05:58.604Z",
       "updatedAt": "2026-07-01T10:06:06.736Z",
@@ -84,7 +84,7 @@
       "id": "8b13a92e-4b3e-4bac-885f-879ddd9e4835",
       "projectId": null,
       "userId": "local",
-      "title": "启用 csv-data-tools 技能",
+      "title": "Enable the csv-data-tools skill",
       "agentId": "all-round-assistant",
       "createdAt": "2026-06-22T04:30:54.662Z",
       "updatedAt": "2026-06-22T04:32:12.657Z",
@@ -96,7 +96,7 @@
       "id": "d536659c-6492-424d-97e8-2f701a9ce5d8",
       "projectId": null,
       "userId": "local",
-      "title": "新对话",
+      "title": "New chat",
       "agentId": "all-round-assistant",
       "createdAt": "2026-06-22T04:19:52.607Z",
       "updatedAt": "2026-06-22T04:20:00.151Z",
@@ -108,7 +108,7 @@
       "id": "4845b527-c9c9-467c-9d72-5fc5f8763aa5",
       "projectId": null,
       "userId": "local",
-      "title": "新对话",
+      "title": "New chat",
       "agentId": "all-round-assistant",
       "createdAt": "2026-06-22T04:12:17.151Z",
       "updatedAt": "2026-06-22T04:12:22.038Z",
@@ -120,7 +120,7 @@
       "id": "405f5964-f01c-4ece-9c8f-02a73d539469",
       "projectId": null,
       "userId": "local",
-      "title": "启用 csv-data-tools 技能",
+      "title": "Enable the csv-data-tools skill",
       "agentId": "all-round-assistant",
       "createdAt": "2026-06-22T04:06:21.745Z",
       "updatedAt": "2026-06-22T04:11:42.782Z",
@@ -132,7 +132,7 @@
       "id": "19a1d8e7-7e9c-425b-8509-0fe9dd292971",
       "projectId": null,
       "userId": "local",
-      "title": "启用 csv-data-tools 技能",
+      "title": "Enable the csv-data-tools skill",
       "agentId": "all-round-assistant",
       "createdAt": "2026-06-22T04:01:21.158Z",
       "updatedAt": "2026-06-22T04:05:08.801Z",
@@ -144,7 +144,7 @@
       "id": "492c1a80-85b2-486a-b365-3d668c9ad7e6",
       "projectId": null,
       "userId": "local",
-      "title": "新对话",
+      "title": "New chat",
       "agentId": "all-round-assistant",
       "createdAt": "2026-06-22T03:44:47.381Z",
       "updatedAt": "2026-06-22T03:44:54.479Z",
@@ -171,7 +171,7 @@
         "id": "ea36a5de-e2e0-428b-b882-f5e67ca326b0",
         "chatId": "8286e3c8-2d83-409e-930a-3e99b2004d41",
         "role": "assistant",
-        "content": "你好！我是**本地智能助手**，运行在你的本地机器上。\n\n我可以帮你做这些事情：\n\n**💻 本地终端操作**\n- 执行 shell 命令、读写文件\n- 搜索代码库、批量替换\n\n**📊 数据处理**\n- 清洗 CSV / 日志文件\n- 生成统计汇总\n\n直接输入需求即可开始。",
+        "content": "Hello. I am the **local assistant**, running on this computer.\n\nI can help with:\n\n**Local terminal**\n- Run shell commands and read or write files\n- Search a codebase and replace in bulk\n\n**Data**\n- Clean CSV and log files\n- Build a summary\n\nType what you want done.",
         "createdAt": "2026-07-01T10:06:06.733Z",
         "messageMetadata": "{\"traceId\":\"tr_269aa1b0f5244962b3279304d6f26323\",\"completionStatus\":\"completed\",\"trace\":{\"traceId\":\"tr_269aa1b0f5244962b3279304d6f26323\",\"sessionId\":\"8286e3c8-2d83-409e-930a-3e99b2004d41\",\"chatId\":\"8286e3c8-2d83-409e-930a-3e99b2004d41\",\"startedAtMs\":1782900364396,\"eventCount\":3,\"spanCount\":1,\"events\":[{\"name\":\"stream_start\",\"timestampMs\":1782900364396,\"data\":{\"path\":\"/api/v2/chats/8286e3c8-2d83-409e-930a-3e99b2004d41/run\",\"method\":\"POST\"}},{\"name\":\"completion_decision\",\"timestampMs\":1782900366733,\"data\":{\"status\":\"completed\",\"reason\":\"assistant produced final response with no pending tools\",\"confidence\":0.85,\"evidence\":[{\"textLength\":218,\"toolCalls\":[],\"toolErrorCount\":0}]}},{\"name\":\"stream_complete\",\"timestampMs\":1782900366733,\"data\":{\"usedTool\":false,\"completionStatus\":\"completed\",\"assistantLength\":218}}],\"spans\":[{\"name\":\"llm_call\",\"stepId\":\"step_1\",\"startMs\":1782900364396,\"endMs\":1782900366733,\"status\":\"ok\",\"data\":{\"turn\":0,\"model\":\"default\",\"tokensUsed\":{\"prompt\":8596,\"completion\":130,\"total\":8726},\"toolCalls\":0},\"durationMs\":2337}]},\"executedActions\":[]}"
       },
@@ -179,7 +179,7 @@
         "id": "ab1387a6-5c43-4d4b-986d-073d98b3f5e2",
         "chatId": "8286e3c8-2d83-409e-930a-3e99b2004d41",
         "role": "user",
-        "content": "你好",
+        "content": "Hello",
         "createdAt": "2026-07-01T10:06:04.392Z",
         "messageMetadata": null
       }
@@ -189,7 +189,7 @@
         "id": "6599eb84-515c-4f58-bec8-0f37fcfbb234",
         "chatId": "8b13a92e-4b3e-4bac-885f-879ddd9e4835",
         "role": "assistant",
-        "content": "好的，我先查看 `csv-data-tools` 技能的可用模块。\n\n**`csv-data-tools`** 技能已就绪。以下是它的能力概览：\n\n---\n\n## 📦 csv-data-tools\n\n- `csv_stats` — 列级统计（行数、缺失、分布）\n- `csv_filter` — 条件过滤与导出\n- `csv_plot` — 快速出图\n\n告诉我文件路径即可开始。",
+        "content": "I'll look at the modules in `csv-data-tools`.\n\n**`csv-data-tools`** is ready:\n\n---\n\n## csv-data-tools\n\n- `csv_stats` — column stats (rows, missing values, distribution)\n- `csv_filter` — filter and export\n- `csv_plot` — a quick chart\n\nSend a file path to start.",
         "createdAt": "2026-06-22T04:32:11.576Z",
         "messageMetadata": null
       },
@@ -227,7 +227,7 @@
         "id": "c8dc9e96-642b-4232-8c3c-c8abc32a615c",
         "chatId": "405f5964-f01c-4ece-9c8f-02a73d539469",
         "role": "assistant",
-        "content": "我来查看当前可用的 MCP 工具，找到 `csv-data-tools` 的相关信息。\n\n看起来 `csv-data-tools` 没有作为独立的 MCP 服务器注册。换个方式，先扫描本地脚本和可执行工具。\n\n结论：该技能当前未安装，可通过技能设置页导入。",
+        "content": "I'll check the MCP tools for `csv-data-tools`.\n\nIt is not registered as its own MCP server. I'll scan local scripts and executables instead.\n\nIt is not installed. Import it from the skills settings.",
         "createdAt": "2026-06-22T04:11:42.077Z",
         "messageMetadata": null
       },
@@ -245,7 +245,7 @@
         "id": "cfb0f03c-7faa-4594-b29f-f4c11fb09105",
         "chatId": "19a1d8e7-7e9c-425b-8509-0fe9dd292971",
         "role": "assistant",
-        "content": "本地模型调用失败：无法连接 OpenAI 兼容网关 (https://api.deepseek.com)，请检查 baseUrl / 网络。原始错误: fetch failed",
+        "content": "The local model call failed: could not reach the OpenAI-compatible gateway (https://api.deepseek.com). Check baseUrl and the network. Original error: fetch failed",
         "createdAt": "2026-06-22T04:05:06.751Z",
         "messageMetadata": null
       },
@@ -273,7 +273,7 @@
         "id": "c5d6136b-eaa4-4cc7-878b-450099b7d226",
         "chatId": "4e997d62-20ef-4937-a866-27778dee3a17",
         "role": "assistant",
-        "content": "我来查看当前可用的 MCP 工具，找到 `csv-data-tools` 的相关信息。\n\n看起来 `csv-data-tools` 没有作为独立的 MCP 服务器注册。换个方式，先扫描本地脚本和可执行工具。\n\n结论：该技能当前未安装，可通过技能设置页导入。",
+        "content": "I'll check the MCP tools for `csv-data-tools`.\n\nIt is not registered as its own MCP server. I'll scan local scripts and executables instead.\n\nIt is not installed. Import it from the skills settings.",
         "createdAt": "2026-06-22T03:37:37.601Z",
         "messageMetadata": null
       },
@@ -289,7 +289,7 @@
         "id": "fa89030e-5db1-4d04-9320-e796baeb89e2",
         "chatId": "4e997d62-20ef-4937-a866-27778dee3a17",
         "role": "assistant",
-        "content": "你好！我是**本地智能助手**，运行在你的本地机器上。\n\n我可以帮你做这些事情：\n\n**💻 本地终端操作**\n- 执行 shell 命令、读写文件\n- 搜索代码库、批量替换\n\n**📊 数据处理**\n- 清洗 CSV / 日志文件\n- 生成统计汇总\n\n直接输入需求即可开始。",
+        "content": "Hello. I am the **local assistant**, running on this computer.\n\nI can help with:\n\n**Local terminal**\n- Run shell commands and read or write files\n- Search a codebase and replace in bulk\n\n**Data**\n- Clean CSV and log files\n- Build a summary\n\nType what you want done.",
         "createdAt": "2026-06-22T03:34:48.778Z",
         "messageMetadata": "{\"traceId\":\"tr_f53c2142bbd347b5888f9d50c5444478\",\"completionStatus\":\"completed\",\"trace\":{\"traceId\":\"tr_f53c2142bbd347b5888f9d50c5444478\",\"sessionId\":\"4e997d62-20ef-4937-a866-27778dee3a17\",\"chatId\":\"4e997d62-20ef-4937-a866-27778dee3a17\",\"startedAtMs\":1782099286405,\"eventCount\":3,\"spanCount\":1,\"events\":[{\"name\":\"stream_start\",\"timestampMs\":1782099286405,\"data\":{\"path\":\"/api/v2/chats/4e997d62-20ef-4937-a866-27778dee3a17/run\",\"method\":\"POST\"}},{\"name\":\"completion_decision\",\"timestampMs\":1782099288778,\"data\":{\"status\":\"completed\",\"reason\":\"assistant produced final response with no pending tools\",\"confidence\":0.85,\"evidence\":[{\"textLength\":224,\"toolCalls\":[],\"toolErrorCount\":0}]}},{\"name\":\"stream_complete\",\"timestampMs\":1782099288778,\"data\":{\"usedTool\":false,\"completionStatus\":\"completed\",\"assistantLength\":224}}],\"spans\":[{\"name\":\"llm_call\",\"stepId\":\"step_1\",\"startMs\":1782099286405,\"endMs\":1782099288777,\"status\":\"ok\",\"data\":{\"turn\":0,\"model\":\"default\",\"tokensUsed\":{\"prompt\":2234,\"completion\":130,\"total\":2364},\"toolCalls\":0},\"durationMs\":2372}]},\"executedActions\":[]}"
       },
@@ -309,7 +309,7 @@
     "baseUrl": "https://api.deepseek.com",
     "apiKey": "",
     "temperature": 0.3,
-    "systemPrompt": "你是一款本地行动助手，优先给出可执行建议并在需要时调用本地工具。"
+    "systemPrompt": "You are a local assistant. Prefer advice that can be carried out, and call local tools when that helps."
   },
   "skills": []
 }

package/src/hooks/useProjects.ts

@@ -51,7 +51,7 @@ export async function refreshProjects(): Promise<void> {
   } catch (err) {
     if (seq !== requestSeq) return;
     const message = err instanceof Error ? err.message : String(err);
-    console.error('获取项目列表失败:', err);
+    console.error('Failed to load projects:', err);
     snapshot = { projects: snapshot.projects, error: message };
     emit();
   }

package/src/i18n/agent-label.ts

@@ -0,0 +1,15 @@
+import { t } from './runtime';
+
+/**
+ * 内置智能体的界面名按 id 翻译。库里的 name 仍是种子原文，切换语言不改历史行。
+ * 用户自建智能体用库里的名字。
+ */
+const BUILTIN_AGENT_LABELS: Record<string, string> = {
+  'local-assistant': 'Computer operator',
+  'all-round-assistant': 'Assistant',
+};
+
+export function agentLabel(agent: { id: string; name: string }): string {
+  const source = BUILTIN_AGENT_LABELS[agent.id];
+  return source ? t(source) : agent.name;
+}

package/src/i18n/index.tsx

@@ -0,0 +1,68 @@
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+import {
+  configureI18n,
+  getLocale,
+  registerLocale,
+  setLocale,
+  subscribeI18n,
+  supportedLocales,
+  t,
+} from './runtime';
+
+export { configureI18n, getLocale, registerLocale, setLocale, supportedLocales, t };
+export { LOCALE_STORAGE_KEY, SOURCE_LOCALE, normalizeLocale, resolveLocale } from './translate';
+
+interface I18nContextValue {
+  locale: string;
+  locales: readonly string[];
+  t: typeof t;
+  setLocale: (locale: string) => void;
+}
+
+const I18nContext = createContext<I18nContextValue | null>(null);
+
+/**
+ * 包住应用树。语言变化时用 key 重挂子树，这样直接调用 `t()` 的组件也会换文案。
+ */
+export function I18nProvider({ children }: { children: ReactNode }) {
+  const [locale, setSnapshot] = useState(getLocale);
+  useEffect(() => subscribeI18n(() => setSnapshot(getLocale())), []);
+  const value = useMemo<I18nContextValue>(
+    () => ({
+      locale,
+      locales: supportedLocales(),
+      t,
+      setLocale: (next) => {
+        if (!setLocale(next)) return;
+        window.electron?.setLocale?.(next);
+      },
+    }),
+    [locale],
+  );
+  return (
+    <I18nContext.Provider value={value}>
+      <div key={locale} className="contents">
+        {children}
+      </div>
+    </I18nContext.Provider>
+  );
+}
+
+export function useI18n(): I18nContextValue {
+  const value = useContext(I18nContext);
+  if (value) return value;
+  return {
+    locale: getLocale(),
+    locales: supportedLocales(),
+    t,
+    setLocale,
+  };
+}
+
+/** 语言名用该语言自己的写法，不跟着界面语言翻。 */
+export function localeEndonym(locale: string): string {
+  if (locale === 'zh') return '中文'; // i18n:allow 语言名用该语言自己的写法
+  if (locale === 'en') return 'English';
+  return locale;
+}

package/src/i18n/runtime.ts

@@ -0,0 +1,117 @@
+/**
+ * 渲染进程的当前语言。产品入口在 bootstrap 前 registerLocale，
+ * bootstrap 再 configureI18n。未配置时只有英语。
+ */
+
+import {
+  LOCALE_STORAGE_KEY,
+  SOURCE_LOCALE,
+  resolveLocale,
+  translate,
+} from './translate';
+
+export interface I18nStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+interface I18nState {
+  locales: string[];
+  defaultLocale: string;
+  locale: string;
+  catalogs: Record<string, Record<string, string>>;
+}
+
+const state: I18nState = {
+  locales: [SOURCE_LOCALE],
+  defaultLocale: SOURCE_LOCALE,
+  locale: SOURCE_LOCALE,
+  catalogs: {},
+};
+
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+export function subscribeI18n(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function registerLocale(locale: string, messages: Record<string, string>): void {
+  const normalized = locale.trim();
+  if (!normalized || normalized === SOURCE_LOCALE) return;
+  state.catalogs[normalized] = { ...state.catalogs[normalized], ...messages };
+  emit();
+}
+
+function readStorage(): I18nStorage | null {
+  if (typeof localStorage === 'undefined') return null;
+  return localStorage;
+}
+
+function systemLocale(): string | null {
+  if (typeof navigator === 'undefined') return null;
+  return navigator.language || null;
+}
+
+export function configureI18n(options: {
+  locales: readonly string[];
+  defaultLocale: string;
+  systemLocale?: string | null;
+  storage?: I18nStorage | null;
+}): void {
+  const locales = [...new Set(options.locales.filter((locale) => locale.length > 0))];
+  state.locales = locales.length > 0 ? locales : [SOURCE_LOCALE];
+  state.defaultLocale = options.defaultLocale || SOURCE_LOCALE;
+  const storage = options.storage === undefined ? readStorage() : options.storage;
+  state.locale = resolveLocale({
+    supported: state.locales,
+    defaultLocale: state.defaultLocale,
+    saved: storage?.getItem(LOCALE_STORAGE_KEY) ?? null,
+    system: options.systemLocale === undefined ? systemLocale() : options.systemLocale,
+  });
+  applyDocumentLang(state.locale);
+  emit();
+}
+
+export function getLocale(): string {
+  return state.locale;
+}
+
+export function supportedLocales(): readonly string[] {
+  return state.locales;
+}
+
+export function setLocale(locale: string): boolean {
+  if (!state.locales.includes(locale)) return false;
+  if (state.locale === locale) return true;
+  state.locale = locale;
+  const storage = readStorage();
+  storage?.setItem(LOCALE_STORAGE_KEY, locale);
+  applyDocumentLang(locale);
+  emit();
+  return true;
+}
+
+export function t(message: string, params?: Record<string, string | number>): string {
+  return translate(message, state.locale, state.catalogs, params);
+}
+
+function applyDocumentLang(locale: string): void {
+  if (typeof document === 'undefined') return;
+  document.documentElement.lang = locale === 'zh' ? 'zh-CN' : locale;
+}
+
+/** 测试隔离。生产代码不调用。 */
+export function resetI18nForTests(): void {
+  state.locales = [SOURCE_LOCALE];
+  state.defaultLocale = SOURCE_LOCALE;
+  state.locale = SOURCE_LOCALE;
+  state.catalogs = {};
+  listeners.clear();
+}

package/src/i18n/translate.ts

@@ -0,0 +1,65 @@
+/**
+ * 界面文案查找。源语言是英语：调用处写英文句子，应用层语言包把英文映射到译文。
+ * 缺译文时原样返回英文，漏翻在界面上看得见。
+ */
+
+export const SOURCE_LOCALE = 'en';
+export const LOCALE_STORAGE_KEY = 'agent-shell.locale';
+
+/** `zh-CN` / `en-US` 收成语言包用的主标签。不认识的标签保留主段。 */
+export function normalizeLocale(raw: string | null | undefined): string | null {
+  if (!raw) return null;
+  const lower = raw.trim().toLowerCase().replace(/_/g, '-');
+  if (!lower) return null;
+  if (lower.startsWith('zh')) return 'zh';
+  if (lower.startsWith('en')) return 'en';
+  const primary = lower.split('-')[0];
+  return primary || null;
+}
+
+export function resolveLocale(options: {
+  supported: readonly string[];
+  defaultLocale: string;
+  saved: string | null;
+  system: string | null;
+}): string {
+  const supported = options.supported.filter((locale) => locale.length > 0);
+  const list = supported.length > 0 ? supported : [SOURCE_LOCALE];
+  const pick = (value: string | null): string | null => {
+    if (!value) return null;
+    if (list.includes(value)) return value;
+    const normalized = normalizeLocale(value);
+    if (normalized && list.includes(normalized)) return normalized;
+    return null;
+  };
+  return (
+    pick(options.saved) ??
+    pick(options.system) ??
+    pick(options.defaultLocale) ??
+    list[0] ??
+    SOURCE_LOCALE
+  );
+}
+
+export function formatMessage(
+  template: string,
+  params?: Record<string, string | number>,
+): string {
+  if (!params) return template;
+  return template.replace(/\{(\w+)\}/g, (whole, name: string) => {
+    const value = params[name];
+    return value === undefined ? whole : String(value);
+  });
+}
+
+/** 语言包的键是英文源句。源语言不查表。 */
+export function translate(
+  message: string,
+  locale: string,
+  catalogs: Readonly<Record<string, Readonly<Record<string, string>>>>,
+  params?: Record<string, string | number>,
+): string {
+  const table = locale === SOURCE_LOCALE ? undefined : catalogs[locale];
+  const template = table?.[message] ?? message;
+  return formatMessage(template, params);
+}

package/src/layouts/AgentLayout.tsx

@@ -17,6 +17,7 @@ import {
   type UseChatsAndAgentsResult,
 } from '@/hooks/useChatsAndAgents';
 import { hostToolChrome, sanitizeRightPanelKind, settingsChrome } from '@/lib/host-tools';
+import { t } from '@/i18n';
 
 /**
  * AgentLayout wraps `/agent`, `/agent/:chatId`, and `/` (default) with a
@@ -560,8 +561,8 @@ function AgentLayoutContent() {
               type="button"
               onClick={toggleSidebarCollapsed}
               className="flex h-7 w-7 items-center justify-center rounded-full text-agent-muted-foreground transition-colors duration-200 hover:bg-agent-foreground/5 hover:text-agent-foreground"
-              title="展开侧边栏"
-              aria-label="展开侧边栏"
+              title={t('Expand sidebar')}
+              aria-label={t('Expand sidebar')}
             >
               <LuPanelLeftOpen className="h-3.5 w-3.5" />
             </button>
@@ -581,11 +582,11 @@ function AgentLayoutContent() {
           <div
             role="separator"
             aria-orientation="vertical"
-            aria-label="调整侧边栏宽度"
+            aria-label={t('Resize sidebar')}
             onMouseDown={() => setIsResizing(true)}
             onDoubleClick={resetWidth}
             className="w-1 flex-shrink-0 cursor-col-resize bg-transparent transition-colors hover:bg-agent-border/60"
-            title="拖拽调整侧边栏宽度（双击恢复默认）"
+            title={t('Drag to resize the sidebar (double-click to reset)')}
           />
         </>
       )}
@@ -612,11 +613,11 @@ function AgentLayoutContent() {
               <div
                 role="separator"
                 aria-orientation="vertical"
-                aria-label="调整右侧面板宽度"
+                aria-label={t('Resize right panel')}
                 onMouseDown={() => setIsTerminalResizing(true)}
                 onDoubleClick={resetTerminalWidth}
                 className="w-1 flex-shrink-0 cursor-col-resize bg-transparent transition-colors hover:bg-agent-border/60"
-                title="拖拽调整右侧面板宽度（双击恢复默认）"
+                title={t('Drag to resize the right panel (double-click to reset)')}
               />
               <div
                 className={`h-full flex-shrink-0 overflow-hidden rounded-agent-lg shadow-sm ${