引擎建议 API

根据反馈生成提案,查看更改内容,并明确选择应用或驳回。

引擎建议针对术语表中的术语、规则和品牌语调变体提出更改提案。应用前,请审核提案内容及其目标位置。生成操作会将提案加入队列;应用提案则会更改引擎的指导内容。

引擎建议功能需要 Enterprise 方案。调用方还需具备引擎访问权限及相关建议权限。控制面板中的操作流程请参阅队列中的建议。

以下所有路由均使用 https://api.lingo.dev 和 API 身份验证。

请求生成 #

根据引擎收集的反馈生成提案:

http
POST /v2/engines/:engineId/engine-suggestions/generate
X-API-Key: YOUR_API_KEY

此请求无需请求体。如需直接提供反馈:

http
POST /v2/engines/:engineId/engine-suggestions/from-text
Content-Type: application/json
X-API-Key: YOUR_API_KEY
json
{
  "text": "In German account settings, use Abonnement for subscription. Avoid Mitgliedschaft for this product feature."
}

text 必须包含非空白内容,且不得超过 10,000 个字符。此模式直接根据提供的反馈生成提案,因此请注明希望如何修正,以及修正适用的语言。

两个路由均返回 HTTP 200,并包含:

json
{ "enqueued": true }

这仅表示请求已提交至队列,并不表示生成已完成。处理完成后,请获取引擎的待处理建议列表。如果没有可带来改进的更改,生成过程可能不会产生任何提案;请求后立即获取到空列表,并不表示请求失败。

列出提案 #

http
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25
查询参数含义
engineIds仅限所选引擎。
targetLocales语言区域范围,其中 * 表示跨语言区域适用的指导内容。
statusesPending、Applied 或 Dismissed;默认为 Pending。
ids获取指定 ID 对应的提案。
limit1 至 100 之间的整数;默认为 25。
cursor不透明分页游标。

如需传入多个值,请重复使用数组参数。响应包含 data 和 meta.nextCursor;请沿用相同的筛选条件继续获取,直到 nextCursor 为 null。

每个提案包含:

字段含义
id, organizationId, engineId提案的标识和归属信息。
targetLocale提议更改适用的语言区域范围。
change包含类型信息的更改,详见下文。
reasoning提案的说明。
sources证据引用,例如评分器的审核结果、人工编辑或工作项。
status对象,其 type 为 Pending、Applied 或 Dismissed。
destination接收更改的指导集;不可用时为 null。
createdAt, updatedAtISO 时间戳。

目标位置包含 kind(Glossary、Ruleset 或 BrandVoice)、可为空的 id、name 和 willCreate。请检查 willCreate,确认应用提案是否会创建指导集。已应用状态包含 at、可为空的 by 和可为空的 target;由系统驳回的提案可能包含 reason。

查看更改 #

change.type内容
AddGlossaryTermsourceLocale、sourceText、targetLocale、targetText、可为空的 description 和 nonTranslatable。
UpdateGlossaryTermtermId、可为空的 glossaryId 以及提供的替换字段。
AddRulename、text 和 targetLocale。
UpdateRuleruleId 以及提供的 name、text 或 targetLocale。
AddBrandVoiceVariationtargetLocale 和 text。
UpdateBrandVoiceVariationvariationId 以及提供的 targetLocale 或 text。

更新提案仅包含要更改的字段。在应用影响范围较广的更改前,请检查目标记录及其指导集的共享使用情况。

应用或驳回 #

http
POST /v2/engine-suggestions/:id/apply
http
POST /v2/engine-suggestions/:id/dismiss

两个请求均无需请求体,并返回更新后的提案。只有待处理提案才能被应用或驳回。应用会写入提议的指导内容;驳回则保持该指导内容不变。

如果目标已更改或已不存在,应用操作可能返回 EngineSuggestionConflicts 或 EngineSuggestionTargetGone。选择修正方式前,请刷新提案及其目标。对已作出决定的提案重复执行操作会返回 EngineSuggestionNotPending;如果无法确定响应结果,请先检查提案状态,不要盲目重复写入。

批量应用或驳回提案 #

通过 POST 请求将 { "ids": ["FIRST_ID", "SECOND_ID"] } 发送至:

  • /v2/engine-suggestions/apply-many:1–25 个不重复的 ID。
  • /v2/engine-suggestions/dismiss-many:1–1,000 个不重复的 ID。

应用操作返回 applied 和 failed;驳回操作返回 dismissed 和 failed。每个失败条目包含 id 和一个具名的 error。HTTP 成功响应也可能包含个别条目的失败结果。某个条目失败时,其他条目的成功结果仍会保留,因此请逐项处理结果。

使用修订后的指导内容 #

应用后,请查看引擎的术语表、规则或品牌语调,并用有代表性的内容进行测试。启动新任务前,请先应用已接受的指导内容。如需更新现有译文,请明确选择内容并请求刷新;仅应用指导内容并不等同于请求重新翻译。