Engine Suggestions API

关于翻译的反馈，很少是通过仪表板上的一次点击出现的。它更可能是你客服工具里的一句话、审校者留的一条备注，或 QA 队列中的一行——“别再翻译产品名了”“德语请使用正式语体”。Engine Suggestions API 能把这类自由文本反馈转成可由代码驱动的引擎变更：你只需提交反馈文本，平台就会基于这些内容进行推理，并返回针对引擎术语表、指令或品牌语气的具体、结构化编辑，供你直接应用。

这就是仪表板功能对应的程序化方式。在仪表板里，当 AI Reviewers 给某条翻译打了低分，系统会自动生成建议；而在这里，信号由你以文本形式提供。无论入口是哪一种，输出都一样——都是等待你审核并应用的待处理建议。

整个流程分成两部分。生成是异步的——你提交反馈后，平台会在后台完成推理，并把待处理建议落到对应引擎上。审核是同步的——你列出待处理建议，查看每条建议具体要改什么，再决定逐条应用或忽略。本文会覆盖这两部分。想了解仪表板体验——例如根据低审查分数自动生成、Suggestions 标签页和通知——请参阅 Engine Suggestions。

这是配置端点，不是翻译端点

这些端点读取和修改的是引擎的配置——也就是术语表、指令和品牌语气。它们通过引擎的 :id 作用于单个引擎，并使用与其他 API 相同、组织级作用域的 X-API-Key 进行身份验证。它们不会翻译任何内容，也不会改动历史翻译；建议一旦应用，会在该引擎下一次翻译时生效。

身份验证

请在 X-API-Key 请求头中传入你的 API key。密钥是组织级作用域，可访问该组织下的所有引擎。详见 Authentication；关于本页所有端点共用的错误模型，请参阅 Errors and status codes。

根据反馈生成#

text

POST /engines/:id/suggestions/from-text

发送一段纯文本，描述引擎哪里出了问题。平台会基于这段文本以及引擎当前配置进行推理，并提出原子级编辑——对于引擎里已经存在的内容，不会重复建议。生成是异步执行的，因此调用会在任务被接受时立即返回，而不是等建议准备好之后才返回。

参数	类型	说明
`id`（路径）	string	要为其生成建议的引擎。
`text`	string	关于引擎输出的自由文本反馈。长度为 1–10,000 个字符；且必须至少包含一个非空白字符。

javascript

const response = await fetch(
  `https://api.lingo.dev/engines/${engineId}/suggestions/from-text`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Our German (de-DE) translations keep using the informal 'du'. For our B2B audience they must always use the formal 'Sie'.",
    }),
  },
);

const { enqueued } = await response.json();
console.log(enqueued); // true – generation accepted, running in the background

json

{ "enqueued": true }

enqueued: true 仅表示平台已接受这项任务，并不代表建议已经生成。生成只是后台流程中的一步——它会读取你的文本，结合当前配置进行推理，与已有内容去重，并持久化它提出的建议。一次运行完全可能不给出任何建议（比如反馈过于模糊，或引擎本身已经覆盖了相关问题）。你可以稍后通过列出引擎建议查看结果。

空反馈会被拒绝

text 必须包含真实内容。空字符串或只包含空白字符都会被 400 拒绝——系统不会悄悄把它当成另一种请求。请提交一些模型确实可以据此推理的信息。

也可以改为根据审查分数生成

驱动仪表板的同一低分触发机制，也可以通过代码调用：POST /engines/:id/suggestions/generate（空请求体）会要求平台根据引擎近期低分的 AI reviews 来提出编辑，而不是根据文本反馈。返回的同样是 { "enqueued": true }，产出的也同样是待处理建议。已有明确书面反馈时，用 from-text；想直接从审校者已经标记的问题中提取建议时，用 generate。

列出待处理建议#

text

GET /engines/:id/suggestions

返回该引擎的建议——即任意一次生成任务的结果，无论它是由文本触发、手动按钮触发，还是由低审查分数自动触发。每一项都是一条附带推理依据的建议编辑。

json

[
  {
    "id": "egs_A1b2C3d4E5f6G7h8",
    "ownerOrganizationId": "org_X1y2Z3a4B5c6D7e8",
    "ownerEngineId": "eng_X1y2Z3a4B5c6D7e8",
    "actionType": "add_instruction",
    "targetKind": "instruction",
    "targetId": null,
    "targetLocale": "de-DE",
    "payload": { "instruction": "Use the formal 'Sie' form in all German translations; never use the informal 'du'." },
    "reasoning": "Feedback states the B2B audience requires formal address, but the engine has no instruction enforcing it.",
    "sourceReviewLogIds": [],
    "status": "pending",
    "appliedTargetId": null,
    "createdAt": "2026-06-18T10:30:00.000Z"
  }
]

字段	说明
`id`	带有 `egs_` 前缀的建议标识符。将它传给 apply 或 dismiss。
`actionType`	以下之一：`add_glossary_item`、`update_glossary_item`、`add_instruction`、`update_instruction`、`add_brand_voice`、`update_brand_voice`。
`targetKind`	这次编辑涉及的引擎部分：`glossary_item`、`instruction` 或 `brand_voice`。
`targetId`	对于 `update_` 操作，这里是要修改的条目 id（`gli_` / `ins_` / `bvc_`）。对于 `add_` 操作，则为 `null`。
`targetLocale`	该建议适用的 locale。
`payload`	可直接应用的编辑内容。其字段取决于 `targetKind`——它与创建/更新操作所需的数据完全一致，因此应用时无需你再提供额外输入。
`reasoning`	对为什么提出这项编辑的简短说明。
`sourceReviewLogIds`	促成这条建议的审查日志失败记录（`esrl_` ids）；如果建议来自反馈文本，则为空。
`status`	`pending`、`applied` 或 `dismissed`。
`appliedTargetId`	建议应用后会创建或更新的条目；在待处理状态时为 `null`。

payload 是让 apply 成本很低的关键：建议的变更在生成时就已经被完整结构化，所以 apply 只是一次普通写入，不需要再来一轮 AI。最终由你决定，平台不会再次推理。

应用建议#

text

POST /engine-suggestions/:id/apply

将建议中的变更写入引擎，并把该建议标记为 applied。这只是把你已经在列表里看到的 payload 做一次确定性写入——不会有第二次 AI 调用，所以你审核过的内容，和最终写入的内容完全一致。add_* 建议会创建新的术语表项、指令或品牌语气；update_* 建议则会修改由 targetId 指定的现有条目。

javascript

const response = await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/apply`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);

const applied = await response.json();
console.log(applied.status);          // "applied"
console.log(applied.appliedTargetId); // "ins_…" – the instruction it just created

响应会返回该建议的 applied 状态，此时 appliedTargetId 会指向它实际创建或更新的引擎条目。从这一刻起，这个条目就是普通的术语表项、指令或品牌语气——你可以像处理任何其他条目一样打开、编辑或删除它。

应用改的是配置，不是历史翻译

apply 修改的是引擎配置。已经翻译过的内容会保持现有输出；变更会在引擎下一次翻译时体现。apply 本身不会重新本地化任何内容。

忽略建议#

text

POST /engine-suggestions/:id/dismiss

丢弃你不想要的建议，将其标记为 dismissed，同时不对引擎做任何改动。当某条提议并不适合你的产品时，就用这个操作——引擎保持不变，这条建议也不会再显示为待处理。

javascript

await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/dismiss`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);
// The suggestion is now "dismissed"; nothing was written to the engine.

完整闭环#

这四个端点组成了一个你可以完全通过代码驱动的闭环：输入反馈，查看系统提出了什么，然后提交你认可的编辑。

生成

调用 POST …/suggestions/from-text 提交书面反馈（或调用 …/suggestions/generate，改为根据低审查分数生成）。你会立即收到 { "enqueued": true }。

列出

稍后调用 GET /engines/:id/suggestions 查看待处理建议；每条建议都会附带其 payload 和 reasoning。

应用或忽略

调用 POST /engine-suggestions/:id/apply 提交这项编辑，或调用 …/dismiss 将其丢弃。应用后会在引擎下一次翻译时生效。

后续步骤#

Engine Suggestions（功能）

仪表板视图、基于低审查分数的自动生成，以及通知。

AI Reviewers

根据你的配置为翻译打分——这正是自动建议触发器读取的信号。

术语表

术语表建议会写入的强制翻译与不可翻译规则。

指令

指令建议会创建或更新的各 locale 规则。

这是配置端点，不是翻译端点

身份验证

根据反馈生成#

text

POST /engines/:id/suggestions/from-text

参数	类型	说明
`id`（路径）	string	要为其生成建议的引擎。
`text`	string	关于引擎输出的自由文本反馈。长度为 1–10,000 个字符；且必须至少包含一个非空白字符。

javascript

const response = await fetch(
  `https://api.lingo.dev/engines/${engineId}/suggestions/from-text`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Our German (de-DE) translations keep using the informal 'du'. For our B2B audience they must always use the formal 'Sie'.",
    }),
  },
);

const { enqueued } = await response.json();
console.log(enqueued); // true – generation accepted, running in the background

json

{ "enqueued": true }

空反馈会被拒绝

也可以改为根据审查分数生成

列出待处理建议#

text

GET /engines/:id/suggestions

json

[
  {
    "id": "egs_A1b2C3d4E5f6G7h8",
    "ownerOrganizationId": "org_X1y2Z3a4B5c6D7e8",
    "ownerEngineId": "eng_X1y2Z3a4B5c6D7e8",
    "actionType": "add_instruction",
    "targetKind": "instruction",
    "targetId": null,
    "targetLocale": "de-DE",
    "payload": { "instruction": "Use the formal 'Sie' form in all German translations; never use the informal 'du'." },
    "reasoning": "Feedback states the B2B audience requires formal address, but the engine has no instruction enforcing it.",
    "sourceReviewLogIds": [],
    "status": "pending",
    "appliedTargetId": null,
    "createdAt": "2026-06-18T10:30:00.000Z"
  }
]

字段	说明
`id`	带有 `egs_` 前缀的建议标识符。将它传给 apply 或 dismiss。
`actionType`	以下之一：`add_glossary_item`、`update_glossary_item`、`add_instruction`、`update_instruction`、`add_brand_voice`、`update_brand_voice`。
`targetKind`	这次编辑涉及的引擎部分：`glossary_item`、`instruction` 或 `brand_voice`。
`targetId`	对于 `update_` 操作，这里是要修改的条目 id（`gli_` / `ins_` / `bvc_`）。对于 `add_` 操作，则为 `null`。
`targetLocale`	该建议适用的 locale。
`payload`	可直接应用的编辑内容。其字段取决于 `targetKind`——它与创建/更新操作所需的数据完全一致，因此应用时无需你再提供额外输入。
`reasoning`	对为什么提出这项编辑的简短说明。
`sourceReviewLogIds`	促成这条建议的审查日志失败记录（`esrl_` ids）；如果建议来自反馈文本，则为空。
`status`	`pending`、`applied` 或 `dismissed`。
`appliedTargetId`	建议应用后会创建或更新的条目；在待处理状态时为 `null`。

应用建议#

text

POST /engine-suggestions/:id/apply

javascript

const response = await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/apply`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);

const applied = await response.json();
console.log(applied.status);          // "applied"
console.log(applied.appliedTargetId); // "ins_…" – the instruction it just created

应用改的是配置，不是历史翻译

apply 修改的是引擎配置。已经翻译过的内容会保持现有输出；变更会在引擎下一次翻译时体现。apply 本身不会重新本地化任何内容。

忽略建议#

text

POST /engine-suggestions/:id/dismiss

javascript

await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/dismiss`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);
// The suggestion is now "dismissed"; nothing was written to the engine.