@qthinker/opencode-deepseek-search 0.2.0 → 0.3.0

package/src/deepseek.ts

@@ -1,8 +1,12 @@
 // DeepSeek Search / Fetch HTTP core.
 //
 // Responsibilities: request shaping, retry policy, response mapping and
-// user-facing (Chinese) error messages. No plugin context and no storage here,
-// so every mapper below is unit-testable without network access.
+// user-facing error messages (rendered through the i18n tables). No plugin
+// context and no storage here, so every mapper below is unit-testable without
+// network access.
+
+import { t } from "./i18n/index.ts"
+import type { Language } from "./rpc.ts"
 
 export const API_BASE = "https://api.deepseek.com"
 export const SEARCH_PATH = "/v1/tools/search"
@@ -32,12 +36,8 @@ export interface FetchResult {
   truncated: boolean
 }
 
-export function missingKeyMessage(): string {
-  return (
-    "未配置 DeepSeek API Key：请设置环境变量 DEEPSEEK_API_KEY" +
-    '（PowerShell: [Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY","sk-...","User")），' +
-    '或在插件 options 中写 "apiKey": "{env:DEEPSEEK_API_KEY}"，然后重启 opencode。'
-  )
+export function missingKeyMessage(language: Language): string {
+  return t(language, "error.missingKey")
 }
 
 // ---------- abort plumbing: combine the caller signal with a timeout ----------
@@ -80,42 +80,43 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
 
 // ---------- error mapping ----------
 
-function upstreamMessage(body: string): string {
+function upstreamMessage(body: string, language: Language): string {
   try {
     const parsed = JSON.parse(body) as { error?: { message?: unknown } }
     const message = parsed?.error?.message
-    return typeof message === "string" && message.trim() ? `：${message.trim()}` : ""
+    if (typeof message !== "string" || !message.trim()) return ""
+    // The provider text is kept verbatim; only the separator is localized.
+    const separator = language === "en" ? ": " : "："
+    return `${separator}${message.trim()}`
   } catch {
     return ""
   }
 }
 
-export function httpError(status: number, body: string, isFetch: boolean): Error {
-  const upstream = upstreamMessage(body)
-  const fetchHint = isFetch ? " 可改用内置 webfetch 工具抓取该页面。" : ""
+export function httpError(status: number, body: string, isFetch: boolean, language: Language): Error {
+  const upstream = upstreamMessage(body, language)
+  const hint = isFetch ? t(language, "error.http.fetchHint") : ""
+  const params = { upstream, hint, status }
   switch (status) {
     case 400:
-      return new Error(`DeepSeek 请求参数无效（400）${upstream}。搜索词需 1~128 字符；Fetch 的 URL 需为合法的 http(s) 绝对地址。`)
+      return new Error(t(language, "error.http.400", params))
     case 401:
-      return new Error(`DeepSeek API Key 无效（401）${upstream}。请检查 DEEPSEEK_API_KEY 环境变量或 options.apiKey。`)
+      return new Error(t(language, "error.http.401", params))
     case 402:
-      return new Error("DeepSeek 账户余额不足（402），失败请求不计费。请充值后重试。")
+      return new Error(t(language, "error.http.402", params))
     case 403:
-      return new Error(`DeepSeek Fetch 被目标站点安全策略拒绝（403）${upstream}。${fetchHint}`)
+      return new Error(t(language, "error.http.403", params))
     case 404:
-      return new Error(`DeepSeek 无法提取该链接的正文（404）${upstream}。请确认链接可访问。${fetchHint}`)
+      return new Error(t(language, "error.http.404", params))
     case 408:
-      return new Error("DeepSeek 请求超时（408），已退避重试一次仍失败。请稍后重试。")
+      return new Error(t(language, "error.http.408", params))
     case 413:
-      return new Error("DeepSeek 请求体过大（413）。请缩短输入。")
+      return new Error(t(language, "error.http.413", params))
     case 429:
-      return new Error("DeepSeek 触发限速（429，账号级 Search 100 QPS / Fetch 25 QPS），已退避重试一次仍失败。请稍后再试。")
+      return new Error(t(language, "error.http.429", params))
     default:
-      if (status >= 500)
-        return new Error(
-          `DeepSeek 服务端错误（${status}），已退避重试一次仍失败。可把插件 options.mode 改为 "native" 暂用原生搜索。`,
-        )
-      return new Error(`DeepSeek 请求失败（HTTP ${status}）${upstream}`)
+      if (status >= 500) return new Error(t(language, "error.http.5xx", params))
+      return new Error(t(language, "error.http.other", params))
   }
 }
 
@@ -132,9 +133,10 @@ export async function postJson(
   body: unknown,
   apiKey: string,
   timeoutMs: number,
+  language: Language,
   signal?: AbortSignal,
 ): Promise<unknown> {
-  if (!apiKey) throw new Error(missingKeyMessage())
+  if (!apiKey) throw new Error(missingKeyMessage(language))
   for (let attempt = 1; ; attempt++) {
     const merged = mergeAbort(signal, timeoutMs)
     try {
@@ -149,7 +151,7 @@ export async function postJson(
         try {
           return JSON.parse(text) as unknown
         } catch {
-          throw new Error(`DeepSeek 返回了无法解析的响应（HTTP ${res.status}）。请稍后重试。`)
+          throw new Error(t(language, "error.parse", { status: res.status }))
         }
       }
       const text = await res.text().catch(() => "")
@@ -157,18 +159,18 @@ export async function postJson(
         await sleep(retryAfterMs(res.headers), signal)
         continue
       }
-      throw httpError(res.status, text, path === FETCH_PATH)
+      throw httpError(res.status, text, path === FETCH_PATH, language)
     } catch (e) {
       if (e instanceof Error && e.name === "AbortError") {
         throw new Error(
           signal?.aborted
-            ? "DeepSeek 请求已取消。"
-            : `DeepSeek 请求超时（${Math.round(timeoutMs / 1000)} 秒），请重试。`,
+            ? t(language, "error.aborted")
+            : t(language, "error.timeout", { seconds: Math.round(timeoutMs / 1000) }),
         )
       }
       // fetch() rejects with TypeError on DNS/TLS/proxy failures.
       if (e instanceof TypeError) {
-        throw new Error(`无法连接 ${API_BASE}（网络错误：${e.message}）。请检查网络或代理设置。`)
+        throw new Error(t(language, "error.network", { base: API_BASE, message: e.message }))
       }
       throw e
     } finally {
@@ -222,39 +224,53 @@ export async function deepseekSearch(
   query: string,
   apiKey: string,
   count: number,
+  language: Language,
   signal?: AbortSignal,
 ): Promise<SearchResult[]> {
-  const data = await postJson(SEARCH_PATH, buildSearchBody(query, count), apiKey, SEARCH_TIMEOUT_MS, signal)
+  const data = await postJson(
+    SEARCH_PATH,
+    buildSearchBody(query, count),
+    apiKey,
+    SEARCH_TIMEOUT_MS,
+    language,
+    signal,
+  )
   return mapSearchResults(data)
 }
 
 // ---------- DeepSeek Fetch -> Markdown with truncation ----------
 
-export function mapFetchResponse(data: unknown, url: string, maxChars: number): FetchResult {
+export function mapFetchResponse(
+  data: unknown,
+  url: string,
+  maxChars: number,
+  language: Language,
+): FetchResult {
   const title = typeof (data as { title?: unknown })?.title === "string" ? (data as { title: string }).title : ""
   const raw = typeof (data as { content?: unknown })?.content === "string" ? (data as { content: string }).content : ""
   const truncated = raw.length > maxChars
   let body = truncated ? raw.slice(0, maxChars) : raw
   if (truncated) {
-    body += `\n\n[DeepSeek Fetch 截断提示] 原文共 ${raw.length} 字符，超出上限 ${maxChars}，此处仅保留前 ${maxChars} 字符。`
+    body += `\n\n${t(language, "error.fetch.truncated", { raw: raw.length, max: maxChars })}`
   }
   return {
-    markdown: `# ${title || url}\n来源: ${url}\n\n${body}`,
+    markdown: `# ${title || url}\n${t(language, "fetch.source", { url })}\n\n${body}`,
     chars: raw.length,
     empty: raw.length === 0,
     truncated,
   }
 }
 
-export function validateUrl(url: string): string | undefined {
-  if (!/^https?:\/\//i.test(url)) return `无效 URL：「${url}」。DeepSeek Fetch 仅支持 http/https 绝对地址。`
-  if (url.length > MAX_URL_CHARS) return `URL 过长（${url.length} > ${MAX_URL_CHARS} 字符）。`
+export function validateUrl(url: string, language: Language): string | undefined {
+  if (!/^https?:\/\//i.test(url)) return t(language, "error.validate.urlScheme", { url })
+  if (url.length > MAX_URL_CHARS)
+    return t(language, "error.validate.urlLong", { length: url.length, max: MAX_URL_CHARS })
   try {
     const parsed = new URL(url)
-    if (!parsed.host) return `URL 缺少主机名：「${url}」。`
-    if (parsed.username || parsed.password) return "URL 不能包含用户名/密码（userinfo）。"
+    if (!parsed.host) return t(language, "error.validate.urlHost", { url })
+    if (parsed.username || parsed.password) return t(language, "error.validate.urlUserinfo")
   } catch {
-    return `无法解析 URL：「${url}」。`
+    return t(language, "error.validate.urlParse", { url })
   }
   return undefined
 }
@@ -263,15 +279,17 @@ export async function deepseekFetch(
   url: string,
   apiKey: string,
   maxChars: number,
+  language: Language,
   signal?: AbortSignal,
 ): Promise<FetchResult> {
-  const data = await postJson(FETCH_PATH, { url }, apiKey, FETCH_TIMEOUT_MS, signal)
-  return mapFetchResponse(data, url, maxChars)
+  const data = await postJson(FETCH_PATH, { url }, apiKey, FETCH_TIMEOUT_MS, language, signal)
+  return mapFetchResponse(data, url, maxChars, language)
 }
 
-export function validateQuery(query: string): string | undefined {
-  if (query.length === 0) return "搜索词为空：DeepSeek Search 需要非空 query（1~128 字符）。"
-  if (query.length > MAX_QUERY_CHARS) return `搜索词过长（${query.length} 字符，上限 ${MAX_QUERY_CHARS}），请精简后重试。`
+export function validateQuery(query: string, language: Language): string | undefined {
+  if (query.length === 0) return t(language, "error.validate.queryEmpty")
+  if (query.length > MAX_QUERY_CHARS)
+    return t(language, "error.validate.queryLong", { length: query.length, max: MAX_QUERY_CHARS })
   return undefined
 }
 

package/src/gui/index.tsx

@@ -14,6 +14,7 @@ import {
   type SessionPanelMenuItem,
 } from "@opencode/plugin/gui"
 import { createSignal } from "solid-js"
+import { t } from "../i18n/index.ts"
 import { DeepSeekRpc, readModeResult, readStatus, type SearchStatus } from "../rpc.ts"
 import { DeepSeekPanel } from "./panel.tsx"
 
@@ -30,6 +31,10 @@ export default Plugin.define({
     const [error, setError] = createSignal<string | undefined>()
     const [busy, setBusy] = createSignal(false)
 
+    // The desktop side has no forced locale: the server resolves the language
+    // and carries it in `status`, so every label follows that signal.
+    const language = () => status()?.language ?? "en"
+
     const describeError = (e: unknown) => (e instanceof Error ? e.message : String(e)).slice(0, ERROR_MAX)
 
     // `status` takes a required first argument: plain JSON Schema degrades the
@@ -42,7 +47,7 @@ export default Plugin.define({
           setStatus(next)
           setError(undefined)
         } else {
-          setError("状态数据格式不符")
+          setError(t(language(), "toast.statusMalformed"))
         }
       } catch (e) {
         setError(describeError(e))
@@ -53,7 +58,7 @@ export default Plugin.define({
       setBusy(true)
       try {
         const result = readModeResult(await rpc.setMode({ mode: next }))
-        if (!result) ctx.toast.show({ title: "DeepSeek", description: "模式切换结果格式不符", variant: "error" })
+        if (!result) ctx.toast.show({ title: "DeepSeek", description: t(language(), "toast.modeMalformed"), variant: "error" })
         else if (!result.ok) ctx.toast.show({ title: "DeepSeek", description: result.message, variant: "error" })
       } catch (e) {
         ctx.toast.show({ title: "DeepSeek", description: describeError(e), variant: "error" })
@@ -96,18 +101,20 @@ export default Plugin.define({
     const openPanel = () => {
       const session = ctx.sessions.current()
       if (!session) {
-        ctx.toast.show({ title: "DeepSeek", description: "请先打开一个会话" })
+        ctx.toast.show({ title: "DeepSeek", description: t(language(), "toast.openSessionFirst") })
         return
       }
       ctx.layout.open(`${ctx.id}:main`, session)
     }
 
-    ctx.add(Command, {
+    // A factory, because the palette label has to follow the language that
+    // arrives with the status signal.
+    ctx.add(Command, (): Command => ({
       id: "open",
-      title: "DeepSeek: 打开统计面板",
+      title: t(language(), "command.open"),
       section: "session",
       run: openPanel,
-    })
+    }))
 
     // The new-tab launcher and the + menu list `session.panel` items, not panel
     // tabs, so without this the panel is reachable only by typing the command.
@@ -119,7 +126,7 @@ export default Plugin.define({
         menu: "session.panel",
         id: "open",
         title: "DeepSeek",
-        description: "搜索用量与接管开关",
+        description: t(language(), "menu.description"),
         icon: "globe",
         order: 60,
         opened,

package/src/gui/panel.tsx

@@ -3,6 +3,7 @@
 import type { JSX } from "solid-js"
 import { For, Show, createMemo, onCleanup, onMount } from "solid-js"
 import { usePlugin } from "@opencode/plugin/gui"
+import { t, type Key } from "../i18n/index.ts"
 import type { SearchStatus } from "../rpc.ts"
 import { sidebarRows, type SidebarRows } from "../status-view.ts"
 
@@ -28,9 +29,9 @@ const INK = {
   light: { on: "#1e7a4c", warn: "#8a5f08", error: "#b03931", off: "#6b7076", idle: "#6b7076", rule: "rgba(0,0,0,0.13)" },
 } as const
 
-const LABEL: Readonly<Record<Tone, string>> = {
-  on: "停用（交还原生搜索）", off: "启用（由 DeepSeek 接管）",
-  warn: "交还原生搜索", error: "重试", idle: "重试",
+const LABEL_KEY: Readonly<Record<Tone, Key>> = {
+  on: "panel.label.on", off: "panel.label.off",
+  warn: "panel.label.warn", error: "panel.label.error", idle: "panel.label.idle",
 }
 
 const ICON = { on: "arrow-undo-down", off: "globe", warn: "arrow-undo-down", error: "refresh", idle: "refresh" } as const
@@ -68,7 +69,11 @@ function help(action: string, mono: string): JSX.Element {
 
 export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
   const ctx = usePlugin()
-  const rows = createMemo(() => sidebarRows({ status: props.status, error: props.error, maxColumns: Infinity }))
+  // The desktop plugin has no forced locale: the server resolves one and carries
+  // it in `status`. The first frame has no status and renders the loader, so the
+  // fallback only ever shows that.
+  const language = () => props.status?.language ?? "en"
+  const rows = createMemo(() => sidebarRows({ status: props.status, error: props.error, maxColumns: Infinity, language: language() }))
   const ink = createMemo(() => INK[ctx.appearance.mode()])
   const mono = () => ctx.appearance.font("mono")
 
@@ -95,8 +100,8 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
         <h2 aria-live="polite" style={{ flex: 1, "min-width": 0, margin: 0, "font-size": "13px", "font-weight": 600, "line-height": "20px", "overflow-wrap": "anywhere" }}>
           {headline(rows().title, ink()[rows().tone])}
         </h2>
-        <ctx.ui.Tooltip value="刷新用量" placement="bottom">
-          <ctx.ui.IconButton icon="refresh" label="刷新用量" size="small" onClick={props.onRefresh} />
+        <ctx.ui.Tooltip value={t(language(), "panel.tooltip.refresh")} placement="bottom">
+          <ctx.ui.IconButton icon="refresh" label={t(language(), "panel.tooltip.refresh")} size="small" onClick={props.onRefresh} />
         </ctx.ui.Tooltip>
       </header>
 
@@ -106,7 +111,7 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
         ) : (
           <div style={{ display: "flex", "align-items": "center", gap: "8px", "margin-top": "14px", opacity: 0.7 }}>
             <ctx.ui.Loader size="small" />
-            <span style={{ "font-size": "12px" }}>正在读取用量…</span>
+            <span style={{ "font-size": "12px" }}>{t(language(), "panel.loading")}</span>
           </div>
         )
       ) : (
@@ -145,7 +150,7 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
       <Show when={rows().clickable && rows().tone !== "idle"}>
         <div style={{ "margin-top": "18px" }}>
           <ctx.ui.Button variant={rows().tone === "off" || rows().tone === "error" ? "contrast" : "neutral"} icon={ICON[rows().tone]} disabled={props.busy} busy={props.busy} onClick={props.onToggle}>
-            {LABEL[rows().tone]}
+            {t(language(), LABEL_KEY[rows().tone])}
           </ctx.ui.Button>
         </div>
       </Show>

package/src/i18n/en.ts

@@ -0,0 +1,151 @@
+// English copy: the source language and the fallback for every key.
+//
+// Every other locale is typed against `Key` (the keys of this table), so a
+// missing translation is a compile error rather than a silent English string.
+// Templates interpolate `{name}` through `format()` in ./index.ts; a brace group
+// that is not a known parameter (e.g. `{env:DEEPSEEK_API_KEY}`) is left alone.
+
+export const en = {
+  // ---------- sidebar states: full wording, then the short form used when the
+  // row cannot hold the full one ----------
+  "state.loading": "Loading…",
+  "state.loadingShort": "Loading…",
+  "state.failed": "Read failed",
+  "state.failedShort": "Failed",
+  "state.enabled": "Enabled",
+  "state.enabledShort": "On",
+  "state.disabled": "Disabled",
+  "state.disabledShort": "Off",
+  "state.unpatched": "websearch not taken over",
+  "state.unpatchedShort": "Not taken over",
+  "state.missingKey": "API key missing",
+  "state.missingKeyShort": "No API key",
+
+  // ---------- the clickable action on the card ----------
+  "action.disable": "Disable",
+  "action.enable": "Enable",
+  "action.release": "Release",
+  "action.retry": "Retry",
+
+  // ---------- desktop panel ----------
+  "panel.tooltip.refresh": "Refresh usage",
+  "panel.loading": "Reading usage…",
+  "panel.label.on": "Disable (release to native search)",
+  "panel.label.off": "Enable (take over with DeepSeek)",
+  "panel.label.warn": "Release to native search",
+  "panel.label.error": "Retry",
+  "panel.label.idle": "Retry",
+
+  // ---------- host chrome: commands, menus, toasts, dialogs ----------
+  "command.open": "DeepSeek: Open usage panel",
+  "command.toggle": "DeepSeek: Enable/disable search takeover",
+  "menu.description": "Search usage and the takeover switch",
+  "toast.openSessionFirst": "Open a session first",
+  "toast.statusMalformed": "Status payload has the wrong shape",
+  "toast.modeMalformed": "Mode switch result has the wrong shape",
+  "dialog.title": "DeepSeek search",
+  "dialog.enable": "Enable",
+  "dialog.enableDesc": "Take over the built-in websearch",
+  "dialog.disable": "Disable",
+  "dialog.disableDesc": "Return the built-in websearch to the host",
+  "dialog.refresh": "Refresh",
+  "dialog.refreshDesc": "Re-read status and usage",
+
+  // ---------- deepseek_mode output ----------
+  "mode.report": "Current search backend: {mode} (source: {source}){suffix}",
+  "mode.source.override": "deepseek_mode switch, persisted",
+  "mode.source.config": "config file options.mode",
+  "mode.suffix.patched": " · built-in websearch is served by DeepSeek",
+  "mode.suffix.notPatched": " · built-in websearch was not found, so nothing is taken over",
+  "mode.suffix.native": " · built-in websearch stays native",
+  "mode.notFound":
+    "Built-in {tool} tool not found; it cannot be switched at runtime. " +
+    'Set options.mode to "{mode}" in the config file instead.',
+  "mode.configCleared": "Persisted switch cleared; back to the config file ({mode}).",
+  "mode.persisted":
+    "Persisted: still {mode} after restarting OpenCode. " +
+    'To return to the config file, call deepseek_mode with mode: "config".',
+  "mode.statusOnly": "status only reports the current mode; it does not switch.",
+  "mode.invalid": "mode must be status / deepseek / native / config, got: {raw}",
+
+  // ---------- tool progress / bookkeeping ----------
+  "progress.fetch": "DeepSeek Fetch: fetching {url}",
+  "fetch.source": "Source: {url}",
+  "usage.reset": "Local stats cleared.",
+
+  // ---------- deepseek_usage report ----------
+  "usage.report.title":
+    "DeepSeek usage (local counts, estimated per successful request; current mode {mode}; ¥{price}/1000 requests)",
+  "usage.report.line":
+    "{label}: searches {search} · fetches {fetch} · empty/failed {skipped} (empty {empty} / failed {failed}) · est. {cost}",
+  "usage.report.note":
+    "Note: empty and failed requests are not billed; DeepSeek's account-side bill is authoritative, and these counts exclude other machines or tools.",
+  "usage.label.today": "Today",
+  "usage.label.month": "Month",
+  "usage.label.total": "Total",
+  "usage.summary.line": "Search {search} · Fetch {fetch} · empty/failed {skipped} · {cost}",
+
+  // ---------- errors ----------
+  "error.missingKey":
+    "DeepSeek API key is not configured. Set the DEEPSEEK_API_KEY environment variable " +
+    '(PowerShell: [Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY","sk-...","User")), ' +
+    'or write "apiKey": "{env:DEEPSEEK_API_KEY}" in the plugin options, then restart opencode.',
+  "error.http.400":
+    "Invalid DeepSeek request parameters (400){upstream}. Queries must be 1–128 characters; " +
+    "Fetch URLs must be valid absolute http(s) URLs.",
+  "error.http.401":
+    "Invalid DeepSeek API key (401){upstream}. Check the DEEPSEEK_API_KEY environment variable or options.apiKey.",
+  "error.http.402": "Insufficient DeepSeek account balance (402); failed requests are not billed. Top up and try again.",
+  "error.http.403": "DeepSeek Fetch was blocked by the target site's security policy (403){upstream}.{hint}",
+  "error.http.404": "DeepSeek could not extract the page body (404){upstream}. Check that the link is reachable.{hint}",
+  "error.http.408": "DeepSeek request timed out (408); one backoff retry also failed. Try again later.",
+  "error.http.413": "DeepSeek request body too large (413). Shorten the input.",
+  "error.http.429":
+    "DeepSeek rate limit hit (429; account limits: Search 100 QPS / Fetch 25 QPS); " +
+    "one backoff retry also failed. Try again later.",
+  "error.http.5xx":
+    "DeepSeek server error ({status}); one backoff retry also failed. " +
+    'You can set options.mode to "native" to use native search for now.',
+  "error.http.other": "DeepSeek request failed (HTTP {status}){upstream}",
+  "error.http.fetchHint": " You can use the built-in webfetch tool for this page.",
+  "error.parse": "DeepSeek returned an unparseable response (HTTP {status}). Try again later.",
+  "error.aborted": "DeepSeek request cancelled.",
+  "error.timeout": "DeepSeek request timed out ({seconds}s). Try again.",
+  "error.network": "Cannot reach {base} (network error: {message}). Check your network or proxy settings.",
+  "error.validate.queryEmpty": "Empty query: DeepSeek Search needs a non-empty query (1–128 characters).",
+  "error.validate.queryLong": "Query too long ({length} characters, limit {max}); shorten it and retry.",
+  "error.validate.urlScheme": 'Invalid URL: "{url}". DeepSeek Fetch only supports absolute http/https URLs.',
+  "error.validate.urlLong": "URL too long ({length} > {max} characters).",
+  "error.validate.urlHost": 'URL has no host: "{url}".',
+  "error.validate.urlUserinfo": "URL must not contain a username/password (userinfo).",
+  "error.validate.urlParse": 'Cannot parse URL: "{url}".',
+  "error.fetch.truncated":
+    "[DeepSeek Fetch truncated] The page is {raw} characters; the limit is {max}, so only the first {max} characters are kept.",
+} as const
+
+export type Key = keyof typeof en
+/** One locale's complete table: every key, no extras. */
+export type Messages = Record<Key, string>
+
+/**
+ * Usage-row ladder, richest first. Each entry is a complete row, so nothing is
+ * ever left dangling and no number is ever cut from its unit. `{label}` is the
+ * localized period label; `Search`/`Fetch` stay English in every language.
+ */
+export const enUsageForms: readonly string[] = [
+  "{label}  Search {search}  Fetch {fetch}  {cost}",
+  "{label} Search {search} Fetch {fetch} {cost}",
+  "{label}  Search {search}  Fetch {fetch}",
+  "{label} Search {search} Fetch {fetch}",
+  "{label}  {search}S  {fetch}F  {cost}",
+  "{label}  {search}S  {fetch}F",
+  "{label}  {search}S",
+]
+
+/** Missing-key hint ladder, richest first. The env var name is always present. */
+export const enHintForms: readonly string[] = [
+  "Set DEEPSEEK_API_KEY and restart",
+  "Set DEEPSEEK_API_KEY",
+  "Set API KEY",
+  "Set KEY",
+]

package/src/i18n/index.ts

@@ -0,0 +1,87 @@
+// The plugin's only copy source and the language resolver.
+//
+// The server resolves one `Language` at setup, puts it in the RPC `status`
+// payload, and the tools and both sidebars render with it — so the chat output
+// and the two sidebars can never disagree. Pure data and pure functions: no
+// plugin or host imports, so every runtime can load this module.
+
+import { isLanguage, type Language } from "../rpc.ts"
+import { en, enHintForms, enUsageForms, type Key, type Messages } from "./en.ts"
+import { ja, jaHintForms, jaUsageForms } from "./ja.ts"
+import { zh, zhHintForms, zhUsageForms } from "./zh.ts"
+
+export type { Key, Messages }
+
+/** One language's complete copy: strings plus the ladders that take widths. */
+export interface LocalePack {
+  readonly messages: Messages
+  /** Usage-row ladder, richest first; see `en.ts`. */
+  readonly usageForms: readonly string[]
+  /** Missing-key hint ladder, richest first. */
+  readonly hintForms: readonly string[]
+}
+
+const PACKS: Readonly<Record<Language, LocalePack>> = {
+  en: { messages: en, usageForms: enUsageForms, hintForms: enHintForms },
+  ja: { messages: ja, usageForms: jaUsageForms, hintForms: jaHintForms },
+  "zh-CN": { messages: zh, usageForms: zhUsageForms, hintForms: zhHintForms },
+}
+
+export function pack(language: Language): LocalePack {
+  return PACKS[language]
+}
+
+export function messages(language: Language): Messages {
+  return PACKS[language].messages
+}
+
+export type Params = Readonly<Record<string, string | number>>
+
+/**
+ * Fill `{name}` placeholders. A brace group that is not a supplied parameter is
+ * left verbatim, which keeps literals such as `{env:DEEPSEEK_API_KEY}` intact.
+ */
+export function format(template: string, params: Params = {}): string {
+  return template.replace(/\{(\w+)\}/g, (match, name: string) => (name in params ? String(params[name]) : match))
+}
+
+/** One message. An unknown key falls back to the key itself, never to a crash. */
+export function t(language: Language, key: Key, params?: Params): string {
+  const table: Readonly<Record<string, string>> = messages(language)
+  const template = table[key]
+  return template === undefined ? key : format(template, params)
+}
+
+// ---------- language resolution ----------
+
+/** The only environment the resolver looks at; both are POSIX locale names. */
+export interface LanguageEnv {
+  readonly LC_ALL?: string
+  readonly LANG?: string
+}
+
+export interface LanguagePick {
+  readonly language: Language
+  /** The raw option value when it was not a known language; the caller warns. */
+  readonly problem?: string
+}
+
+/**
+ * `options.language` wins; otherwise `LC_ALL` (which overrides `LANG` per
+ * POSIX), then `LANG`, then English. Prefix matching keeps `ja_JP.UTF-8` and
+ * `zh_CN.UTF-8` working without an alias table; anything else is English.
+ */
+export function resolveLanguage(option: unknown, env: LanguageEnv = {}): LanguagePick {
+  if (option !== undefined && option !== null && option !== "") {
+    if (isLanguage(option)) return { language: option }
+    return { language: fromEnv(env), problem: String(option) }
+  }
+  return { language: fromEnv(env) }
+}
+
+function fromEnv(env: LanguageEnv): Language {
+  const raw = (env.LC_ALL?.trim() || env.LANG?.trim() || "").toLowerCase()
+  if (raw.startsWith("ja")) return "ja"
+  if (raw.startsWith("zh")) return "zh-CN"
+  return "en"
+}