@lark-base-open/base-database-cli 1.1.1 → 1.3.7

package/templates/database-starter/database-functions/README.md

@@ -0,0 +1,8 @@
+# Database Functions
+
+Place each Database Function in `database-functions/<functionId>/`:
+
+- `main.sql`: Write a query using the supported Database Function syntax. Refer to parameters as `$1`, `$2`, and so on.
+- `meta.json`: Declare `name`, `description`, and the parameter contract. Omit `meta` or `meta.params` when the query has no parameters.
+
+Database Functions read Base data. Use `server-functions/functions/` for writes. See the `lark-base-database` Skill's `database-function.md` for parameter, response, Catalog, and SQL dialect contracts.

package/templates/database-starter/mutations/README.md

@@ -0,0 +1,19 @@
+# Mutation Functions
+
+每个声明能完整表达的固定业务写入放在 `<functionId>/meta.json` 和 `<functionId>/spec.json`。表和字段必须来自根目录 `catalog.json`。
+
+`meta.json` 示例：
+
+```json
+{"name":"更新标题"}
+```
+
+`spec.json` 示例（替换真实 table / field ID）：
+
+```json
+{"table":{"table_id":"tblTasks"},"operation":"update","params":[{"kind":"RECORD_ID"},{"kind":"TEXT","max_length":100}],"precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":1}]},"set":{"fldTitle":{"param":2}},"returning":["rec_id","fldTitle"]}
+```
+
+单条调用 `invokeDatabaseFunction('updateTitle', ['recA', '新标题'])`；批量调用 `invokeDatabaseMutationBatch('updateTitle', [['recA', '标题 A'], ['recB', '标题 B']])`。编号从 1 开始；一批最多 200 条。CLI deploy 自动校验、打包并更新 Function，pull 保留声明。
+
+Mutation 负责基础单表写入；create 不带 precondition，其他操作通过 precondition 指定记录 ID。需要服务端业务校验、计算或编排时使用 FaaS。字段、附件、权限边界和完整协议见已安装的 lark-base-database Skill 的 `references/mutations.md`。

package/templates/database-starter/page/README.md

@@ -1,29 +1,35 @@
 # Page
 
-React + TypeScript + Vite 页面工程。依赖版本、样式库和脚本只以本目录 `package.json` 为准。
+React + TypeScript + Vite page project. This directory's `package.json` defines its dependencies, styling libraries, and scripts.
 
-`invokeDatabaseFunction`、响应结构和 Base 读写边界见 `lark-base-database` Skill 的 `development.md`。
+See the `lark-base-database` Skill's `development.md` for `invokeDatabaseFunction`, response shapes, and Base read and write boundaries.
 
-`vite.config.ts` 中的相对路径配置是应用部署约束。
+The relative path setting in `vite.config.ts` is required for deployment.
 
-## 运行态通信
+## Built-in component language
 
-应用产物运行在 BaseApp 页面的 iframe 中，不持有登录凭证，也不直连业务域名。
-`src/lib/database-runtime.ts` 是与宿主通信的唯一入口，基于
-`@lark-base-open/base-site-channel/runtime` 提供：
+The placeholder `App.tsx` page and the included user selector, account menu, edit button, page state, and attachment image components provide fixed Chinese, English, and Japanese interface text without a translation service. They resolve the language from the host Runtime Context locale, then the browser language, then English. The Page does not pass a language prop. When the host switches language and reloads the Page, they resolve it again. The starter HTML initially uses `lang="en"`; the resolved language updates that attribute. Replace the placeholder page before delivery. Application-specific text and runtime service errors remain the application's responsibility.
 
-- `fetch` / `invokeHttp`：业务 HTTP 经父页面同源代发，URL 只能是以单个 `/` 开头的相对路径
-- `invokeDatabaseFunction(functionId, params)`：Function 调用，打统一网关的
-  `POST /space/api/bitable/site/v1/:token/invoke_function/:function_id`，请求体为 `{"params": ...}`
-- `resolveDatabaseContext()`：解析应用 token 与 `prod` / `preview` 环境，**宿主下发优先**，
-  宿主未提供时回退 `getDatabaseContext()` 的产物路径推断；业务代码用这个异步版本
-- `getDatabaseContext()`：同步的产物路径推断，仅作兜底，不要在业务代码里直接依赖
-- `siteRuntime`：`ready()` 与 `reportLoadFailed()` 生命周期上报
+Optional AI Function example components use the same language selection for their built-in text. See `src/examples/ai-function/README.md` before reusing or moving them.
 
-不要在业务代码里直接使用 `postMessage`、raw Channel Client 或直连业务域名的 `fetch`。
+## Runtime communication
 
-## CSRF 防护
+The application runs in a BaseApp iframe. It does not hold login credentials or call business domains directly. `src/lib/database-runtime.ts` is the single entry point for communication with the host, using `@lark-base-open/base-site-channel/runtime`:
 
-`vite.config.ts` 通过 `@lark-base-open/base-site-js/vite` 提供的
-`createArgusCsrfPlugin()` 启用 CSRF 防护。修改配置时必须保留该插件，不得复制
-插件实现或手写 CSRF Header。
+- `fetch` / `invokeHttp`: The parent page proxies business HTTP requests from its own origin. Business paths must start with a single `/`.
+- `invokeDatabaseFunction(functionId, params)`: Calls `POST /space/api/bitable/site/v1/:token/invoke_function/:function_id` through the unified gateway with a `{"params": ...}` body.
+- `src/lib/database-function-inputs.generated.ts`: The CLI generates Page input types from Database Function and FaaS metadata during `check` and Preview `deploy`. Do not edit this file. Page compilation checks Function IDs, query parameter order, and required FaaS fields and enum values. Callers still declare response types and validate them at runtime.
+- `resolveDatabaseContext()`: Resolves the app token and `prod` or `preview` environment. Host-provided context takes precedence; otherwise it infers values from the artifact path through `getDatabaseContext()`. Use this asynchronous function in business code.
+- `getDatabaseContext()`: Synchronous artifact-path inference for fallback use only.
+- `callSiteAIFunction({ functionKey, capability, variables?, messages?, input? })`: Calls the configured AI Function and returns a discriminated result with `type: 'text' | 'image_task' | 'video_task'`. Poll media tasks by task ID and render by `result.type`.
+- `invokeSiteAIFunctionStream({ functionKey, messages, variables? })`: Streams text or image understanding results. It provides subscribable updates and a `destroy()` method. Consume both `delta.reasoningContent` and `delta.content` and render them separately. See `src/examples/ai-function/TextStreamOperation.tsx`.
+- `createSiteAIFunctionTask(params)` / `getSiteAIFunctionTask(functionKey, taskId)`: Submit and poll image or video generation tasks.
+- `siteRuntime`: Reports lifecycle events through `ready()` and `reportLoadFailed()`.
+
+Do not call `postMessage`, use the raw Channel Client, or fetch a business domain directly from business code.
+
+Declare the model, System Prompt, reasoning depth, image size, video duration, and related settings in `ai/<functionKey>/meta.json` at the project root. Validate with `base-database-cli ai-functions validate <functionKey>` and sync through `deploy`. The page sends call-specific `variables` and `messages` or `input` for the selected `functionKey`. Preview uses the draft configuration; Prod uses it only after production publication. Before calling a Function, confirm that its `functionKey` has been synced and that `disabled` is not `true`.
+
+## Request identity and CSRF
+
+The parent page proxies business HTTP requests and handles identity and CSRF. The Page must not inject a CSRF script, read host cookies, or set a CSRF header itself. See the `lark-base-database` Skill's `verification.md` for migration and request troubleshooting.

package/templates/database-starter/page/package-lock.json

@@ -8,8 +8,7 @@
       "name": "page",
       "version": "0.0.0",
       "dependencies": {
-        "@lark-base-open/base-site-channel": "https://lf3-static.bytednsdoc.com/obj/eden-cn/vlseh7bfnuhps/@lark-base-open-base-site-channel-0.0.1-alpha.35.tgz",
-        "@lark-base-open/base-site-js": "https://lf3-static.bytednsdoc.com/obj/eden-cn/jjjpceh7nulojvhj/@lark-base-open-base-site-js-0.0.1-alpha.25.tgz",
+        "@lark-base-open/base-site-channel": "0.1.3",
         "@radix-ui/react-slot": "^1.3.0",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
@@ -25,7 +24,7 @@
         "@types/react-dom": "^19.2.3",
         "@vitejs/plugin-react": "^6.0.3",
         "oxlint": "^1.42.0",
-        "prettier": "^3.7.4",
+        "prettier": "3.6.2",
         "tailwindcss": "^4.3.2",
         "typescript": "~7.0.2",
         "vite": "^8.1.4",
@@ -120,20 +119,13 @@
       }
     },
     "node_modules/@lark-base-open/base-site-channel": {
-      "version": "0.0.1-alpha.35",
-      "resolved": "https://lf3-static.bytednsdoc.com/obj/eden-cn/vlseh7bfnuhps/@lark-base-open-base-site-channel-0.0.1-alpha.35.tgz",
-      "integrity": "sha512-GzpLpH4cZavVv54GghWwhg1ztZOnwPpLrkCkByqhJWtfWPiFjjKlwXeKHIa5PR+HPoOeTHuKtyhwUpRkoj0M0A==",
-      "license": "ISC",
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/@lark-base-open/base-site-channel/-/base-site-channel-0.1.3.tgz",
+      "integrity": "sha512-wdc8zRkAX2P7pwBkyoun7oHrUP95xYCgAhhwsq4cUOg7ozIf9Em1DQken7kUeMc58pzDM5ONroWavoa1/oQiEg==",
       "dependencies": {
         "lodash-es": "^4.17.21"
       }
     },
-    "node_modules/@lark-base-open/base-site-js": {
-      "version": "0.0.1-alpha.25",
-      "resolved": "https://lf3-static.bytednsdoc.com/obj/eden-cn/jjjpceh7nulojvhj/@lark-base-open-base-site-js-0.0.1-alpha.25.tgz",
-      "integrity": "sha512-FtdohEY5YrYIRGxL/FIU8dSQ4326nf7QDZHEZm1HE59RIBAvlkPnqZlE+8AuvQZ+3KL+vmg6ZPmxONlghFyhbw==",
-      "license": "ISC"
-    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "1.1.6",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.6.tgz",
@@ -2254,9 +2246,9 @@
       }
     },
     "node_modules/prettier": {
-      "version": "3.9.5",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.9.5.tgz",
-      "integrity": "sha512-/FVl766LpUfB5vXgCYOYa0MeV/441Ia99AeICQIQFTY/Nw0roZwULcXpku5i1/m5kt/baz+s4Zogspd839HSMg==",
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
+      "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
       "dev": true,
       "license": "MIT",
       "bin": {

package/templates/database-starter/page/package.json

@@ -18,8 +18,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@lark-base-open/base-site-channel": "https://lf3-static.bytednsdoc.com/obj/eden-cn/vlseh7bfnuhps/@lark-base-open-base-site-channel-0.0.1-alpha.35.tgz",
-    "@lark-base-open/base-site-js": "https://lf3-static.bytednsdoc.com/obj/eden-cn/jjjpceh7nulojvhj/@lark-base-open-base-site-js-0.0.1-alpha.25.tgz",
+    "@lark-base-open/base-site-channel": "0.1.3",
     "@radix-ui/react-slot": "^1.3.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -35,7 +34,7 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
     "oxlint": "^1.42.0",
-    "prettier": "^3.7.4",
+    "prettier": "3.6.2",
     "tailwindcss": "^4.3.2",
     "typescript": "~7.0.2",
     "vite": "^8.1.4",

package/templates/database-starter/page/src/App.tsx

@@ -1,4 +1,25 @@
+import { useUiLanguage, type UiLanguage } from './lib/ui-language'
+
+const APP_COPY = {
+  en: {
+    heading: 'Start with a real business workflow',
+    description:
+      'Build the interface with page components. Read Base data through Database Functions and write through FaaS Functions. Replace this starter content before delivery.',
+  },
+  zh: {
+    heading: '从真实业务任务开始构建',
+    description:
+      '使用页面组件承载交互，通过 Database Function 读取 Base 数据、通过 FaaS Function 写入，并在交付前替换这段起始内容。',
+  },
+  ja: {
+    heading: '実際の業務フローから構築を始めましょう',
+    description:
+      'ページコンポーネントで操作画面を作成します。Base データは Database Function で読み込み、FaaS Function で書き込みます。公開前にこの初期コンテンツを置き換えてください。',
+  },
+} satisfies Record<UiLanguage, { heading: string; description: string }>
+
 export default function App() {
+  const copy = APP_COPY[useUiLanguage()]
   return (
     <main className="flex min-h-screen items-center justify-center bg-background px-6 py-12 text-foreground">
       <section className="w-full max-w-2xl rounded-3xl border border-border bg-card p-8 shadow-sm sm:p-12">
@@ -6,11 +27,10 @@ export default function App() {
           Base Database
         </p>
         <h1 className="mt-4 text-3xl font-semibold tracking-tight text-balance sm:text-5xl">
-          从真实业务任务开始构建
+          {copy.heading}
         </h1>
         <p className="mt-5 max-w-xl text-base leading-7 text-muted-foreground sm:text-lg">
-          使用页面组件承载交互，通过受控 Function 连接 Base SQL 与
-          FaaS，并在交付前替换这段起始内容。
+          {copy.description}
         </p>
       </section>
     </main>

package/templates/database-starter/page/src/components/UserSelectorEditor/index.tsx

@@ -9,6 +9,7 @@ import React, {
 } from 'react'
 
 import { cn } from '../../lib/cn'
+import { useUiLanguage, type UiLanguage } from '../../lib/ui-language'
 import UserSelectorPanel, {
   type User,
   type UserSelectorAction,
@@ -38,6 +39,31 @@ export interface UserSelectorEditorProps {
   onBlur?: FocusEventHandler<HTMLButtonElement>
 }
 
+const USER_SELECTOR_EDITOR_COPY = {
+  en: {
+    clearSelected: 'Clear selected members',
+    removeMember: (name: string) => `Remove member ${name}`,
+    selectMembers: 'Select members',
+  },
+  zh: {
+    clearSelected: '清除已选成员',
+    removeMember: (name: string) => `移除成员 ${name}`,
+    selectMembers: '选择成员',
+  },
+  ja: {
+    clearSelected: '選択したメンバーをクリア',
+    removeMember: (name: string) => `メンバー ${name} を削除`,
+    selectMembers: 'メンバーを選択',
+  },
+} satisfies Record<
+  UiLanguage,
+  {
+    clearSelected: string
+    removeMember: (name: string) => string
+    selectMembers: string
+  }
+>
+
 /**
  * 展示受控成员值，并闭环管理 UserSelectorPanel 的打开、关闭与值回传。
  */
@@ -61,6 +87,8 @@ export default function UserSelectorEditor(
     onFocus,
     onBlur,
   } = props
+  const uiLanguage = useUiLanguage()
+  const i18n = USER_SELECTOR_EDITOR_COPY[uiLanguage]
   const [open, setOpen] = useState(false)
   const rootRef = useRef<HTMLDivElement>(null)
   const panelOpen = open
@@ -175,8 +203,8 @@ export default function UserSelectorEditor(
                   <button
                     aria-label={
                       isMultiple
-                        ? `移除成员 ${selectedUser.name}`
-                        : '清除已选成员'
+                        ? i18n.removeMember(selectedUser.name)
+                        : i18n.clearSelected
                     }
                     className="relative ml-0 flex size-3.5 shrink-0 cursor-pointer items-center justify-center rounded-sm border-0 bg-transparent p-0 !text-[#646a73] outline-none hover:!text-[#0442d2]"
                     onClick={(event) => {
@@ -214,7 +242,7 @@ export default function UserSelectorEditor(
               ))
             ) : (
               <button
-                aria-label="选择成员"
+                aria-label={i18n.selectMembers}
                 aria-expanded={panelOpen}
                 aria-haspopup="listbox"
                 className="flex h-full min-w-0 flex-1 items-center gap-1 border-0 bg-transparent p-0 text-left text-inherit outline-none"
@@ -223,7 +251,7 @@ export default function UserSelectorEditor(
                 type="button"
               >
                 <span className="min-w-0 flex-1 truncate text-[#8f959e]">
-                  选择成员
+                  {i18n.selectMembers}
                 </span>
               </button>
             )}

package/templates/database-starter/page/src/components/UserSelectorPanel/index.tsx

@@ -8,6 +8,7 @@ import React, {
 } from 'react'
 
 import { cn } from '../../lib/cn'
+import { useUiLanguage, type UiLanguage } from '../../lib/ui-language'
 import './index.css'
 import { requestUsers, type SearchUsersData, type User } from './user-search'
 
@@ -24,6 +25,57 @@ const SEARCH_CACHE_TTL_MS = 30_000
 const RECORD_CREATOR_AVATAR_URL =
   'https://lf-package-cn.feishucdn.com/obj/feishu-static/ccm/static_resource/scm_upload/base_filter_current_user.png'
 
+const USER_SELECTOR_PANEL_COPY = {
+  en: {
+    invalidResponse: 'Member search response has an invalid structure',
+    loading: 'Loading...',
+    memberList: 'Member list',
+    noMatches: 'No matching members. Try another search term.',
+    noRecommendations: 'No recommended members yet',
+    recordCreator: 'Add the person who created this record',
+    searchFailed: 'Member search failed',
+    searchFailedCode: (code: number) =>
+      `Could not search members (error code ${code})`,
+    searchMembers: 'Search members',
+  },
+  zh: {
+    invalidResponse: '成员搜索响应结构无效',
+    loading: '加载中...',
+    memberList: '成员列表',
+    noMatches: '没有匹配的成员，请换个关键词',
+    noRecommendations: '暂无推荐成员',
+    recordCreator: '添加此记录的人员',
+    searchFailed: '搜索成员失败',
+    searchFailedCode: (code: number) => `搜索成员失败（错误码 ${code}）`,
+    searchMembers: '搜索成员',
+  },
+  ja: {
+    invalidResponse: 'メンバー検索の応答形式が正しくありません',
+    loading: '読み込み中...',
+    memberList: 'メンバー一覧',
+    noMatches: '一致するメンバーがいません。別のキーワードで検索してください。',
+    noRecommendations: 'おすすめのメンバーがいません',
+    recordCreator: 'このレコードの作成者を追加',
+    searchFailed: 'メンバーの検索に失敗しました',
+    searchFailedCode: (code: number) =>
+      `メンバーを検索できませんでした（エラーコード ${code}）`,
+    searchMembers: 'メンバーを検索',
+  },
+} satisfies Record<
+  UiLanguage,
+  {
+    invalidResponse: string
+    loading: string
+    memberList: string
+    noMatches: string
+    noRecommendations: string
+    recordCreator: string
+    searchFailed: string
+    searchFailedCode: (code: number) => string
+    searchMembers: string
+  }
+>
+
 interface SearchUsersCacheEntry {
   expiresAt: number
   request: Promise<SearchUsersData>
@@ -72,6 +124,8 @@ export default function UserSelectorPanel(
     mode,
     onKeyDown,
   } = props
+  const uiLanguage = useUiLanguage()
+  const i18n = USER_SELECTOR_PANEL_COPY[uiLanguage]
   const isValueControlled = Object.prototype.hasOwnProperty.call(props, 'value')
   const [innerValue, setInnerValue] = useState(defaultValue)
   const [query, setQuery] = useState('')
@@ -94,28 +148,31 @@ export default function UserSelectorPanel(
     activeIndex >= 0 ? `${generatedListboxId}-option-${activeIndex}` : undefined
   const isEmpty = !loading && optionCount === 0
 
-  const getSearchResult = useCallback((keyword: string) => {
-    const cacheKey = keyword.trim()
-    const cachedResult = searchUsersCache.get(cacheKey)
-    if (cachedResult && cachedResult.expiresAt > Date.now()) {
-      return cachedResult.request
-    }
-    searchUsersCache.delete(cacheKey)
-
-    const request = requestUsers(cacheKey)
-      .then(normalizeSearchUsersResponse)
-      .catch((error: unknown) => {
-        if (searchUsersCache.get(cacheKey)?.request === request) {
-          searchUsersCache.delete(cacheKey)
-        }
-        throw error
+  const getSearchResult = useCallback(
+    (keyword: string) => {
+      const cacheKey = `${uiLanguage}:${keyword.trim()}`
+      const cachedResult = searchUsersCache.get(cacheKey)
+      if (cachedResult && cachedResult.expiresAt > Date.now()) {
+        return cachedResult.request
+      }
+      searchUsersCache.delete(cacheKey)
+
+      const request = requestUsers(keyword.trim(), uiLanguage)
+        .then((value) => normalizeSearchUsersResponse(value, uiLanguage))
+        .catch((error: unknown) => {
+          if (searchUsersCache.get(cacheKey)?.request === request) {
+            searchUsersCache.delete(cacheKey)
+          }
+          throw error
+        })
+      searchUsersCache.set(cacheKey, {
+        expiresAt: Date.now() + SEARCH_CACHE_TTL_MS,
+        request,
       })
-    searchUsersCache.set(cacheKey, {
-      expiresAt: Date.now() + SEARCH_CACHE_TTL_MS,
-      request,
-    })
-    return request
-  }, [])
+      return request
+    },
+    [uiLanguage],
+  )
 
   const updateQuery = useCallback(
     (nextQuery: string, action: UserSelectorSearchAction) => {
@@ -149,7 +206,9 @@ export default function UserSelectorPanel(
       } catch (searchError) {
         if (requestSequence !== requestSequenceRef.current) return
         setError(
-          searchError instanceof Error ? searchError.message : '搜索成员失败',
+          searchError instanceof Error
+            ? searchError.message
+            : i18n.searchFailed,
         )
         setUsers([])
       } finally {
@@ -158,7 +217,7 @@ export default function UserSelectorPanel(
         }
       }
     },
-    [getSearchResult],
+    [getSearchResult, i18n],
   )
 
   useEffect(() => {
@@ -312,14 +371,14 @@ export default function UserSelectorPanel(
         }}
         onCompositionStart={() => setIsComposing(true)}
         onKeyDown={handleKeyDown}
-        placeholder="搜索成员"
+        placeholder={i18n.searchMembers}
         ref={inputRef}
         role="searchbox"
         value={query}
       />
 
       <div
-        aria-label="成员列表"
+        aria-label={i18n.memberList}
         aria-multiselectable={isMultiple || undefined}
         className={cn(
           'flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto px-1 py-1 [scrollbar-color:#bbbfc4_transparent] [scrollbar-width:thin] [&::-webkit-scrollbar-thumb]:rounded-full [&::-webkit-scrollbar-thumb]:border [&::-webkit-scrollbar-thumb]:border-transparent [&::-webkit-scrollbar-thumb]:bg-[#bbbfc4] [&::-webkit-scrollbar-thumb]:bg-clip-padding [&::-webkit-scrollbar]:w-2',
@@ -351,7 +410,9 @@ export default function UserSelectorPanel(
               className="mr-2 size-8 shrink-0 rounded-full object-cover"
               src={RECORD_CREATOR_AVATAR_URL}
             />
-            <span className="min-w-0 flex-1 truncate">添加此记录的人员</span>
+            <span className="min-w-0 flex-1 truncate">
+              {i18n.recordCreator}
+            </span>
             <span aria-hidden="true" className="ml-[5px] size-3 shrink-0" />
           </button>
         ) : null}
@@ -427,7 +488,7 @@ export default function UserSelectorPanel(
                 />
               </svg>
             </span>
-            <span className="sr-only">加载中...</span>
+            <span className="sr-only">{i18n.loading}</span>
           </div>
         ) : null}
         {isEmpty ? (
@@ -436,8 +497,8 @@ export default function UserSelectorPanel(
               {error
                 ? error
                 : query.trim()
-                  ? '没有匹配结果，换个关键词试试吧'
-                  : '暂无推荐成员'}
+                  ? i18n.noMatches
+                  : i18n.noRecommendations}
             </div>
           </div>
         ) : null}
@@ -446,19 +507,28 @@ export default function UserSelectorPanel(
   )
 }
 
-function normalizeSearchUsersResponse(value: unknown): SearchUsersData {
+function normalizeSearchUsersResponse(
+  value: unknown,
+  language: UiLanguage,
+): SearchUsersData {
+  const i18n = USER_SELECTOR_PANEL_COPY[language]
   if (!isRecord(value) || typeof value.code !== 'number') {
-    throw new Error('搜索用户返回结构不正确')
+    throw new Error(i18n.invalidResponse)
   }
 
   if (value.code !== 0) {
-    throw new Error(
-      typeof value.msg === 'string' && value.msg ? value.msg : '搜索成员失败',
+    const message = typeof value.msg === 'string' ? value.msg.trim() : ''
+    throw Object.assign(
+      new Error(message || i18n.searchFailedCode(value.code)),
+      {
+        code: String(value.code),
+        cause: value,
+      },
     )
   }
 
   if (!isRecord(value.data) || !Array.isArray(value.data.users)) {
-    throw new Error('搜索用户返回结构不正确')
+    throw new Error(i18n.invalidResponse)
   }
 
   return {

package/templates/database-starter/page/src/components/UserSelectorPanel/user-search.test.ts

@@ -17,7 +17,11 @@ const recommendPayload = {
         department: '研究部',
         en_name: 'Ada',
         id: '6882577547121393684',
-        i18n_department: { en_us: 'Research', zh_cn: '研究部' },
+        i18n_department: {
+          en_us: 'Research',
+          zh_cn: '研究部',
+          ja_jp: '研究部門',
+        },
         is_external: false,
       },
       '6882577547121393685': {
@@ -26,7 +30,11 @@ const recommendPayload = {
         department: '外部组织',
         en_name: 'Grace',
         id: '6882577547121393685',
-        i18n_tenant: { en_us: 'External tenant', zh_cn: '外部租户' },
+        i18n_tenant: {
+          en_us: 'External tenant',
+          zh_cn: '外部租户',
+          ja_jp: '外部組織',
+        },
         is_external: true,
       },
     },
@@ -40,9 +48,7 @@ const recommendPayload = {
 
 beforeEach(() => {
   runtime.fetch.mockReset()
-  vi.stubGlobal('document', {
-    documentElement: { lang: 'zh-CN' },
-  })
+  vi.stubGlobal('navigator', { language: 'en-US' })
   projectMeta.fetchProjectMeta.mockReset()
   projectMeta.fetchProjectMeta.mockResolvedValue({
     baseBindings: [{ baseToken: 'bascnDemo', tableIds: ['tblDemo'] }],
@@ -96,20 +102,28 @@ describe('requestUsers', () => {
   it('fails before transport when the Site has no bound Base', async () => {
     projectMeta.fetchProjectMeta.mockResolvedValue({ baseBindings: [] })
 
-    await expect(requestUsers('ada')).rejects.toThrow('应用未绑定 Base')
+    await expect(requestUsers('ada')).rejects.toThrow(
+      'application is not bound to a Base',
+    )
+    await expect(requestUsers('ada', 'zh')).rejects.toThrow(
+      '无法搜索成员：应用尚未绑定多维表格',
+    )
+    await expect(requestUsers('ada', 'ja')).rejects.toThrow(
+      'メンバーを検索できません：アプリにBaseが関連付けられていません',
+    )
     expect(runtime.fetch).not.toHaveBeenCalled()
   })
 
   it('reports an HTTP failure without attempting to parse the body', async () => {
     runtime.fetch.mockResolvedValue(new Response('', { status: 503 }))
 
-    await expect(requestUsers('ada')).rejects.toThrow('HTTP 状态码：503')
+    await expect(requestUsers('ada')).rejects.toThrow('HTTP 503')
   })
 })
 
 describe('normalizeRecommendUsersResponse', () => {
   it('keeps recommendation order and maps localized names and descriptions', () => {
-    const result = normalizeRecommendUsersResponse(recommendPayload, 'en-US')
+    const result = normalizeRecommendUsersResponse(recommendPayload, 'en')
 
     expect(result.users).toEqual([
       expect.objectContaining({
@@ -146,7 +160,7 @@ describe('normalizeRecommendUsersResponse', () => {
         },
         result_list: [{ token: 'token_ada', type: 0 }],
       },
-      'en-US',
+      'en',
     )
 
     expect(result.users).toEqual([
@@ -162,14 +176,44 @@ describe('normalizeRecommendUsersResponse', () => {
     expect(
       normalizeRecommendUsersResponse(
         { code: 0, data: recommendPayload, msg: 'ok' },
-        'zh-CN',
+        'zh',
       ).users.map((user) => user.name),
     ).toEqual(['格蕾丝', '艾达'])
   })
 
+  it('uses Japanese names and descriptions when provided', () => {
+    const localizedPayload = {
+      ...recommendPayload,
+      entities: {
+        users: {
+          ...recommendPayload.entities.users,
+          '6882577547121393684': {
+            ...recommendPayload.entities.users['6882577547121393684'],
+            display_name: { ja_jp: 'エイダ' },
+          },
+        },
+      },
+    }
+    const result = normalizeRecommendUsersResponse(localizedPayload, 'ja')
+    expect(result.users.map((user) => user.name)).toEqual(['Grace', 'エイダ'])
+    expect(result.users.map((user) => user.description)).toEqual([
+      '外部組織',
+      '研究部門',
+    ])
+  })
+
   it('surfaces backend business errors', () => {
     expect(() =>
       normalizeRecommendUsersResponse({ code: 123, msg: '无权限' }),
-    ).toThrow('无权限')
+    ).toThrow(/^无权限$/)
+    expect(() =>
+      normalizeRecommendUsersResponse({ code: 123, msg: '无权限' }, 'zh'),
+    ).toThrow(/^无权限$/)
+    expect(() =>
+      normalizeRecommendUsersResponse({ code: 123, msg: '無権限' }, 'ja'),
+    ).toThrow(/^無権限$/)
+    expect(() =>
+      normalizeRecommendUsersResponse({ code: 123, msg: '  ' }, 'en'),
+    ).toThrow('Could not search members (error code 123)')
   })
 })