参考 / SDK
机器翻译页面
本页面为自动翻译,可能有错误或表述不够自然。内容以英文版本为准。阅读英文原文。
RunSummary
translate、importWorkbook 和 watch 兑现的结果,逐字段说明,方便脚本读取一次运行的用量和通知。
RunSummary 的结构
translate、importWorkbook 以及每次成功的 watch 运行都会兑现(resolve)为一个 RunSummary:
interface RunSummary {
dryRun: boolean; // true when nothing was written and no provider was called
locales: LocaleSummary[]; // one entry per target locale, in config order
succeeded: string[]; // locales whose run succeeded
partial: string[]; // locales written with keys still missing; the CLI exits 1 on these
failed: string[]; // locales whose run failed
usage?: UsageSummary; // summed input/output tokens; absent when no call reported usage
budget?: RunBudget; // present when maxTokens is configured or passed to the run
estimate?: RunEstimate; // present only when the run was asked for a pre-run estimate
cancelled?: true; // present only when the run's signal aborted it
}
interface LocaleSummary {
locale: string;
status: "succeeded" | "partial" | "failed";
translated: string[]; // keys translated this run (in dry-run, keys that would be)
cacheHits: string[]; // keys served from the translation-memory cache this run
fuzzyHits: FuzzyCacheHit[]; // reuses for a source string that changed, with their scores
unchanged: string[]; // keys already up to date
orphaned: string[]; // target keys with no matching source key (always reported)
pruned: string[]; // orphaned keys removed this run; empty unless pruning is on
invalidIcuSource: string[]; // source keys skipped for invalid ICU
emptySource?: string[]; // source keys with an empty value; nothing is sent or written for them
integrityMismatches: string[]; // translations the integrity gate withheld
integrityRefusals?: { key: string; reason: string; details?: string[] }[]; // why each was withheld; translate, watch, and importWorkbook
providerFailures: string[]; // keys withheld because nothing was translated for them
budgetWithheld: string[]; // keys never sent because a "stop" budget already tripped
sensitiveWithheld: string[]; // keys sensitiveData kept from the provider (block or redact)
generated: string[]; // CLDR plural forms synthesized this run
unfilled: string[]; // blank import rows, or keys a human-only translate left for a human
protected: { key: string; reason: string; suggestion?: string; suggestionStatus?: string }[]; // keys left for a person
malformedRows: { row: number; line?: number; column: string }[]; // import only: rows the reader could not parse
duplicateKeys: { key: string; row: number; line?: number }[]; // import only: later rows for a duplicated key
notices: LocaleNotice[]; // provider notices and SDK notices for this locale
needsReview: { key: string; reasons: string[] }[]; // accepted keys flagged for a second look
usage?: UsageSummary; // this locale's summed tokens; absent if nothing reported usage
error?: { code: string; message: string }; // only on a "failed" locale, and not on every one
}值得了解的部分:
- needsReview 列出审校启发式规则标记的、已接受并已写入的键,每个键带有它的原因码,这些原因码在审校标记中列出并解释。这个集合以
REVIEW_元组的形式发布,所以请据此构建任何运行时 schema 或穷举查找,而不要重新输入这些成员。审校标记只是建议,从不搁置任何键,所以一个键不会同时出现在REASON_ CODES needsReview和integrityMismatches中。处理队列的方法见在 Studio 中审校。 - notices 按语言环境存放,从不在顶层。它们包括提供商通知(例如 DeepL 的降级),列在提供商通知下;以及 SDK 通知,其代码构成
SdkNoticeCode联合类型,在运行通知下解释。整次运行范围的通知(例如缓存通知,一个文件由所有语言环境共用)会附加到该次运行中的每个语言环境上。 - 当该范围内没有任何调用报告用量时,usage 是
undefined,而不是编造的零:试运行从不调用提供商,DeepL 也从不报告 token。RunSummary.usage是各语言环境用量之和。 - budget 只有在配置了
maxTokens或把它传给该次运行时才会出现:{ maxTokens, behavior, supported, tokensUsed, exceeded }。supported表示tokensUsed是否完全来自提供商自己报告的用量;只要有一个请求返回时没有可用的数字,它就是false,此时总数中有一部分是 verbatra 的推算值,它同样会被计数和执行。试运行或没有发出任何请求的运行,会报告supported: true和tokensUsed: 0:什么都没有发送,所以没有任何推算。在behavior: "stop"下,上限会在运行发出的每个请求之前检查(包括被重新拆分的请求的每一半),所以tokensUsed会落在maxTokens或以下,只有一个遗留例外:最后被放行的请求会按提供商报告的数字核对,这可能事后把总数推过上限。一旦如此,就不再发送任何内容。有两件事超出预留所能约束的范围,因为它们发生在已经放行的请求内部:键缺失返回时,提供商层会自行发送一次补救调用,所以一个被放行的批次最多可能花费其推算值的约两倍;并且计数只和提供商报告的内容一样准确。两者都在核对时体现,一旦发生,就不再放行任何内容。预算约束一次translate调用:watch每次运行都重新开始,retranslateEntry则完全不在其范围内。 - 失败的语言环境上的 error.code 是原样保留的字符串(底层的提供商或适配器的错误码,只有在没有时才回退到
LOCALE_),所以不要把它当作封闭集合。状态为FAILED failed的语言环境并不总是带有error:如果它的每个键都被搁置,从而列在integrityMismatches、providerFailures或budgetWithheld中,它会在没有抛出任何错误的情况下失败。它的原因在这些列表和它的notices中,例如提供商批次失败时的SUB_,或 token 预算的BATCH_ FAILED BUDGET_。请检查TOKENS_ EXCEEDED status,不要检查error是否存在。 - cancelled 只有在运行的
signal中止了它时才会出现。RUN_说明了这会留下什么。CANCELLED - estimate 只有在要求该次运行给出运行前估算时才会出现。它的
caveats列表从不为空,并以EstimateCaveatCode成员的形式指出这个数字排除了什么:CACHE_:不读取翻译记忆库,所以真实运行时由缓存提供的键在估算中仍会计入。适用于每一次估算。NOT_ CONSULTED SOURCE_:真实运行对每个相同的源字符串只发送一个代表;估算则统计每个键。适用于每一次估算。DUPLICATES_ NOT_ DEDUPLICATED TRANSPORT_:每个计划的请求只计一次计费调用,尽管提供商的 SDK 可能在其下重试失败的调用,被重试的尝试仍可能计费。适用于每一次估算。RETRIES_ NOT_ COUNTED TRANSLATION_:响应的大小按源值加上固定的扩展余量来估算,所以篇幅更长的目标语言会报告更多的补全 token。仅适用于按 token 计费的提供商。LENGTH_ IS_ ESTIMATED TOKEN_:token 由字符数推算,而不是来自提供商自己的分词器。仅适用于按 token 计费的提供商。COUNT_ IS_ HEURISTIC REPAIR_:针对缺失键的补救轮次,以及对被截断的响应对半拆分后的重试,都不计入。仅适用于按 token 计费的提供商。REQUESTS_ NOT_ COUNTED
- cacheHits 列出由翻译缓存而不是提供商提供的键。fuzzyHits 列出源字符串已更改、但复用了原有译文的键,每个都带有
key、similarity和它匹配到的previousSource;除非启用了fuzzyCache,否则它为空,并且这些键从不计入 cacheHits。unfilled、malformedRows 和 duplicateKeys 只由importWorkbook填充(translate运行会让它们保持为空):分别是导入时仍需翻译的键所在的空白行(无论它导出时是new还是changed)、读取器无法解析的工作簿行,以及首次出现者胜出的重复键。后两者的可选line是该记录起始的文件行,只有在分隔符文件(csv或tsv)导入时才有。唯一的例外是纯人工项目(见不用机器翻译运行):在那里,translate和watch会把翻译记忆库中没有精确条目的每个键都列在 unfilled 中,而 fuzzyHits 保持为空,因为那里从不应用模糊复用。 - protected 列出
translate运行未动的键,每个键带有它的reason(human、import、external或pinned);在humanEdits: "suggest"下还带有suggestion(提供商的回答或翻译记忆库的精确条目,从不是模糊匹配),它不会被写入,以及suggestionStatus:试运行时为planned,否则为suggested,或为说明未能给出建议原因的值(integrity-mismatch、provider-failure、budget-withheld、sensitive-withheld)。失败的建议译文从不改变该语言环境的状态。它们不在 translated 中,从不改变语言环境的状态,并且对check保持过期。importWorkbook会让它保持为空。见保留人工翻译。
这些条目类型中有两个是单独导出的:每个 protected 条目是一个 ProtectedKey,notices 中的每个 SDK 通知是一个 SdkNotice。
属性
类型
属性
类型
budgetStanding
把 RunBudget 归入三个 BudgetStanding 值之一,这与 CLI 的预算行、Studio 和 usage.summary 智能体工具所报告的分类相同:"within" 表示运行从未达到上限;"stopped-before-ceiling" 表示 "stop" 预算搁置了一个请求,而此时 tokensUsed 仍低于 maxTokens;"reached" 表示 tokensUsed 达到或超过了 maxTokens。请使用它,而不要只读 exceeded,因为在后两种情况下 exceeded 都是 true。
function budgetStanding(budget: RunBudget): BudgetStanding;返回:BudgetStanding