ES Documentation
手册
API
手册
API
简体中文

批量导入翻译

验证状态：已源码核验、未联调；适用基线：Web 7fe6dd10、services 89bd222c；核验日期：2026-09-12

用途与 App 场景

从 XLSX 导入批量翻译词条。当前 Web 翻译管理列表页的导入入口提交本操作。接口本身是「受理即返回」，词条的实际落库由仓内 JMS 消费者异步完成（与票 15 八族 importList 的仓外消费者边界不同，本操作消费链在本仓源码内闭合）。

Web 使用位置

页面/功能 角色或空间分支 调用证据
列表页 XLSX 导入 前端入口要求 administrator 或 configuration-translation:create（route.tsx:26-29，importRows 仅在该权限下注册，route.tsx:427） app/routes/($lng).$spaceId.configuration.translation._index/route.tsx:427；app/.common/hooks/use-xlsx-table-io.ts

协议身份

项 值
operationId http-post-main-service-system-api-configuration-translation-importlist-e931ff42
method + path POST /main-service/system-api/configuration/translation/importList
base URL 当前 Web 使用同源相对 URL
headers Content-Type: application/json；Authorization: Bearer <token>
序列化 array body 由公共 wrapper 执行 JSON.stringify（fetchTimeoutResponseJson）

前置条件与权限

需要有效登录态，并满足 administrator 角色或 configuration-translation:create（TranslationController.java:75）。落库租户来自登录态：TenantBoundPublishExecutor.execute(TenantIdSupplierExecutor.execute(), …) 把当前认证租户绑定进 JMS 信封，消费者以信封为可信租户来源（TranslationListener.java:90-91 注释：payload 的 tenantId 置 null，INSERT fill 使用信封 scope）。认证与空间。

输入

JSON 路径/参数 JSON 类型 位置 必填 可空 默认值 枚举/范围/单位 说明 字段证据
body array body 是 否 []（前端默认参数） 元素为 TranslationSaveRequestDTO 结构 XLSX 行按字符串读取发送（use-xlsx-table-io.ts；revision 在 wire 上是字符串数字，服务端 Long 反序列化行为未联调证实） TranslationController.java:77-78 @Valid @RequestBody List<TranslationSaveRequestDTO>；TranslationSaveRequestDTO.java

元素字段：translationId（≤32，可选）、language（必填 ≤128）、namespace（必填 ≤128）、key（必填）、value（必填）、revision（可选）。注意：XLSX 导入行不经过 Web 端 nanoid 生成 translationId，由消费端按自然键命中复用或新建。

输出、应答或事件

JSON 路径 JSON 类型 出现条件 可空 枚举/范围/单位 说明 字段证据
timestamp/status/error/localizedError/path 同信封 JSON 响应 — — 受理成功 status=200 gt-common-core/src/main/java/tech/gt/api/ApiResult.java
extraData object 成功 否 — 恒为 {} 同上
data boolean 受理成功 否 true 表示消息已发布，非已落库 TranslationController.java:84

副作用链（仓内闭合）：发布到 translation import list 通道（ConfigurationChannelContracts.java:8）→ TranslationListener.importList 消费（@JmsListener，TranslationListener.java:77-114）→ 逐行按自然键（language+namespace+key）查重，命中则复用既有 translationId 做 upsert，未命中新建 → saveOrUpdateBatch 落库 → requestPublishInNextRound 触发最终视图刷新。

完成判据

status=200 表示 JMS 发布受理完成；逐行落库、自然键 upsert 与视图刷新均为异步。不提供逐行成功/失败回执；校验失败（如缺列）在消费端以日志记录后继续或整体失败的具体行为未联调核验。

示例

按已核验契约构造的示例，不是真实联调记录。

请求：

1[
2  {
3    "language": "zh-CN",
4    "namespace": "translation",
5    "key": "Add",
6    "value": "新增"
7  },
8  {
9    "language": "en",
10    "namespace": "translation",
11    "key": "Add",
12    "value": "Add"
13  }
14]

成功响应：

1{
2  "timestamp": 1789142400000,
3  "status": 200,
4  "error": null,
5  "localizedError": null,
6  "path": null,
7  "extraData": {},
8  "data": true
9}

错误与边界

认证失败/权限失败/请求校验失败。@Valid 对 List 元素的级联校验行为未由本仓源码/测试证明（与票 15 同名缺口的判定一致）；重复导入同一自然键由消费端幂等合并（复用既有 translationId），可安全重试。

调用关系与资源清理

无长连接资源。导入完成后列表页 reload。

已知缺口

消费端逐行异常的失败粒度（跳过/中断）、@Valid 级联校验、XLSX 字符串数值的服务端反序列化行为未联调核验；translation import list 通道的消费虽在本仓闭合，但多实例部署下的消费语义未验证。 仅完成双仓静态源码核验，未执行真实 HTTP、数据库或 JMS 联调。

验证状态与依据

结论 状态 仓库/基线 路径、符号及定位 内容指纹（脏文件）
Web 方法、路径、序列化与消费 已源码核验 web 7fe6dd10 translationApi.ts:40 configurationTranslationImportListApi；route.tsx:427；use-xlsx-table-io.ts 证据文件与 HEAD 一致
权限、输入与受理语义 已源码核验 services 89bd222c TranslationController.java:76 importList；ConfigurationChannelContracts.java:8 证据文件与 HEAD 一致
消费端落库语义（仓内） 已源码核验 services 89bd222c TranslationListener.java:77-114（自然键 upsert、信封租户、批量落库） 证据文件与 HEAD 一致
真实部署联调 未执行 — 未发送请求、未连接 JMS —
目录