查询任务状态

同步查询单个翻译任务当前的执行状态与进度。专为轮询场景设计 —— 服务端不写调用日志，可以放心高频调用（建议间隔 ≥ 3s）。

适用场景

集成方未配置 callback_url，或网络环境无法接收外部回调
Agent / 命令行脚本希望同步等待任务完成
排查任务卡住时人工确认进度

如果只是想及时拿到事件，优先使用回调（见创建翻译任务 · 回调机制），效率更高且无需轮询。

请求地址

GET {BASE_URL}/api/open/v1/tasks/status

也支持 POST（task_id 放在 body 里，JSON 格式）。

和创建翻译任务完全一样：

Header	值
`X-Loxily-AppKey`	项目 App Key
`X-Loxily-Timestamp`	Unix 秒（5 分钟有效）
`X-Loxily-Sign`	`MD5(timestamp + "" + appSecret)` —— GET 无 body，body 以空字符串参与签名

查询参数

参数	类型	必填	说明
`task_id`	string	是	创建任务时返回的 `task_id`

响应字段

成功（HTTP 200）：

json

{
  "success": true,
  "code": 0,
  "msg": "ok",
  "trace_id": "8a3f12ab-4d2a-9f51-7e2c6d8a9101",
  "data": {
    "task_id": "68a12cb7e1f9a88b4ea23c77",
    "name": "Q2 新手引导文案",
    "status": "running",
    "current_stage": "translate",
    "current_step": "translateBatch",
    "source_language": "zh-hans",
    "target_languages": ["en", "ja", "ko"],
    "strings_count": 512,
    "words_count": 512,
    "progress": {
      "rows_total": 1536,
      "rows_done": 612
    },
    "jobs": [
      {
        "job_id": "translate_68a12cb7_...",
        "job_type": "TRANSLATE",
        "status": "RUNNING",
        "step": "translateBatch",
        "row_count": 1536,
        "error": null,
        "created_at": "2026-04-22T10:22:35.001Z",
        "updated_at": "2026-04-22T10:25:11.301Z"
      }
    ],
    "smart_optimize_status": "pending",
    "requires_confirmation": false,
    "is_completed": false,
    "is_failed": false,
    "failure_reason": null,
    "failure_code": null,
    "accepted_at": "2026-04-22T10:22:31.123Z",
    "updated_at": "2026-04-22T10:25:11.301Z"
  }
}

`status` 的 9 种取值

status	含义	典型 `current_stage`
`pending`	任务刚受理，后台尚未开始任何处理	`pending`
`importing`	后台正在解析 `strings` / 下载 `xlsx_url` / 生成 CSV / 上传 GCS / 触发首个工作流	`import`
`scanning`	TB_SCAN（术语扫描）工作流执行中	`tb_scan`
`term_translating`	新术语自动分类+翻译中，完成后带译文入库（仅 `auto_apply_terms=true` 且扫描出新术语时出现）	`tb_translate`
`waiting_confirmation`	TB_SCAN 完成，等待集成方调用 `/tasks/confirm-terms` 显式确认（仅 `auto_apply_terms=false`）	`tb_scan`
`running`	TRANSLATE 工作流执行中。`current_step` 取值见下表	`translate`
`optimizing`	智能优化（TRANSLATE_QA）工作流执行中。任务译文已生成，但低分行正在重译，建议等 `completed` 再导出	`translate_qa`
`completed`	全链路完成（含智能优化）。可以调 `/export/ini` 导出结果	`done`
`failed`	任一阶段终止失败，`failure_reason` / `failure_code` 携带详情	`failed`

completed 的双终态保证

completed 要求翻译终态 + 智能优化终态同时落定：翻译刚结束、系统还在判断是否需要智能优化的窗口期内，status 会保持 optimizing 而不会提前放出 completed。所以看到 completed 即可安全发布 / 导出，不需要额外等待。

`smart_optimize_status` —— 智能优化的独立状态

取值	含义
`pending`	智能优化决策未做（翻译还没跑完，或刚结束正在统计低分行）
`running`	智能优化（TRANSLATE_QA）工作流执行中
`completed`	智能优化完成
`skipped`	无低分行，本次任务不需要智能优化
`failed`	智能优化失败（不影响任务整体 `completed`，译文仍可用，只是未经优化）
`null`	旧任务（功能上线前创建），无此字段

status='completed' 时该字段保证已是终态（completed / skipped / failed）。

auto_apply_terms=true 的全自动术语链路

scan_terms=true + auto_apply_terms=true 时，扫描出的新术语会自动分类、翻译成项目全部目标语言并写入术语库，随后才启动任务翻译 —— 本次任务即可应用这批术语的统一译法。术语翻译阶段失败时自动降级为"仅导入源术语并继续翻译"，任务不会因此卡住。

`current_step` 的 7 种取值（仅 `status='running'` 时有值）

TRANSLATE 工作流内部 7 个子步骤，对应创建任务文档中的回调事件名：

step	中文	step_index
`tmMatching`	翻译记忆库匹配	1
`tbMatching`	术语匹配	2
`kbExtraction`	知识库抽取	3
`translateBatch`	翻译	4
`lqaBatch`	LQA 质检	5
`translateEnhanceBatch`	翻译增强	6
`aiScoringBatch`	AI 评分	7

`progress` 字段

字段	类型	说明
`rows_total`	number	当前阶段的总行数（通常 = `strings_count` × `target_languages.length`）
`rows_done`	number	已处理行数（来自最新 RUNNING job 的 `detail.rows_processed`）

rows_done 的语义

进度只反映当前 sub-step，子步骤切换时会回到 0。如果只需要"整体完成度"，建议改看 current_step 的 step_index（1-7）。

失败时的额外字段

status='failed' 时：

字段	说明
`failure_reason`	人类可读的错误原因
`failure_code`	内部 HTTP code（400 / 422 / 500 / 502 等）

错误码

code	说明
400	`task_id` 缺失
401	签名无效 / 时间戳过期
403	任务不属于当前 App Key（跨项目访问）
404	`task_id` 不存在
500	系统错误

示例

cURL（GET）

bash

APP_KEY="5685414646a54423c891d87194d87f3f"
APP_SECRET="<你的 App Secret>"
BASE_URL="https://api.loxily.com"
TASK_ID="68a12cb7e1f9a88b4ea23c77"

TIMESTAMP=$(date +%s)
# GET 无 body，body 以空字符串参与签名
SIGN=$(printf '%s' "${TIMESTAMP}${APP_SECRET}" | md5)

curl -s "${BASE_URL}/api/open/v1/tasks/status?task_id=${TASK_ID}" \
  -H "X-Loxily-AppKey: ${APP_KEY}" \
  -H "X-Loxily-Timestamp: ${TIMESTAMP}" \
  -H "X-Loxily-Sign: ${SIGN}"

Node.js 轮询直到完成

javascript

import crypto from 'crypto';

async function waitForTask(taskId, { timeoutMs = 30 * 60 * 1000, intervalMs = 3000 } = {}) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const timestamp = Math.floor(Date.now() / 1000).toString();
    const sign = crypto.createHash('md5')
      .update(`${timestamp}${process.env.LOXILY_APP_SECRET}`, 'utf8')
      .digest('hex');

    const resp = await fetch(
      `${process.env.LOXILY_BASE_URL}/api/open/v1/tasks/status?task_id=${taskId}`,
      {
        headers: {
          'X-Loxily-AppKey': process.env.LOXILY_APP_KEY,
          'X-Loxily-Timestamp': timestamp,
          'X-Loxily-Sign': sign,
        },
      },
    );
    const { data } = await resp.json();

    if (data.is_completed) return data;
    if (data.is_failed) throw new Error(`Task failed: ${data.failure_reason}`);

    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error(`Polling timeout (${timeoutMs}ms)`);
}

const final = await waitForTask('68a12cb7e1f9a88b4ea23c77');
console.log('Done in stage', final.current_stage);

FAQ

Q：和 term_scan.completed / task.completed 回调有什么区别？ 回调是推送，状态接口是拉取。回调及时但需要公网入口；状态接口需要轮询但对任何环境通用（包括本地脚本、Agent 沙箱、命令行）。两者数据来源完全一致。

Q：任务完成后，怎么拿翻译结果？ 任务完成后调 /export/ini 或后续的"导出"系列接口下载译文。状态接口不返回译文内容，避免大响应。

Q：调用频率有限制吗？ 本接口不写调用日志，无单独限流。建议轮询间隔 ≥ 3s，过于频繁不会更快拿到结果。

查询任务状态 ​

请求地址 ​

鉴权 Header ​

查询参数 ​

响应字段 ​

status 的 9 种取值 ​

smart_optimize_status —— 智能优化的独立状态 ​

current_step 的 7 种取值（仅 status='running' 时有值） ​

progress 字段 ​

失败时的额外字段 ​

错误码 ​

示例 ​

cURL（GET） ​

Node.js 轮询直到完成 ​

FAQ ​