Referência / SDK
Página traduzida automaticamente
RunSummary
O que translate, importWorkbook e watch retornam, campo a campo, para que um script leia o uso e os avisos de uma execução.
A anatomia do RunSummary
translate, importWorkbook e cada execução bem-sucedida do watch retornam um 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
}O que vale saber:
- needsReview lista as chaves aceitas e gravadas que as heurísticas de revisão sinalizaram, cada uma com seus códigos
de motivo, listados e explicados em Sinalizações de revisão. O conjunto
vem como a tupla
REVIEW_, então monte qualquer schema de tempo de execução ou busca exaustiva a partir dela em vez de redigitar os membros. Uma sinalização de revisão é consultiva e nunca retém uma chave, então uma chave nunca aparece ao mesmo tempo emREASON_ CODES needsReviewe emintegrityMismatches. Veja Revisar no Studio para percorrer a fila. - notices ficam por locale, nunca no nível superior. Eles cobrem os avisos de provedores (por exemplo, uma degradação
do DeepL), listados em Avisos dos provedores, e os avisos do SDK,
cujos códigos formam a união
SdkNoticeCodee são explicados em Avisos da execução. Um aviso de toda a execução, como o aviso de cache (um arquivo, compartilhado por todos os locales), é anexado a cada locale da execução. - usage é
undefined, nunca um zero inventado, sempre que nada naquele escopo relatou uso: uma simulação nunca chama um provedor, e o DeepL nunca relata tokens.RunSummary.usageé a soma dos locales. - budget só aparece quando
maxTokensestá configurado ou é passado à execução:{ maxTokens, behavior, supported, tokensUsed, exceeded }.supporteddiz setokensUsedé inteiramente o uso relatado pelo próprio provedor; ele éfalseassim que uma requisição voltou sem um valor utilizável, e o total passa a ser em parte uma projeção do verbatra, que é contada e imposta do mesmo jeito. Uma simulação, ou qualquer execução que não enviou nenhuma requisição, relatasupported: truecomtokensUsed: 0: nada foi enviado, então nada foi projetado. Combehavior: "stop", o teto é verificado antes de cada requisição que a execução envia, inclusive cada metade de uma requisição dividida de novo, entãotokensUsedfica igual ou abaixo demaxTokens, exceto por um resíduo: a última requisição admitida é conferida com o que o provedor relatou, o que pode empurrar o total além do teto a posteriori. Nada mais é enviado quando isso acontece. Duas coisas ficam fora do que uma reserva consegue limitar, porque acontecem dentro de uma requisição que ela já admitiu: a camada do provedor envia uma chamada de reparo própria quando chaves voltam ausentes, então um lote admitido pode custar até cerca do dobro da projeção dele, e a contagem só é tão confiável quanto o que o provedor relata. As duas entram na conferência, e nada mais é admitido depois que isso acontece. O orçamento limita uma única chamada detranslate: owatchcomeça um novo a cada execução, e oretranslateEntrynão é coberto por ele de forma alguma. - error.code em um locale com falha é uma string preservada (o código subjacente do provedor ou do adaptador,
com
LOCALE_apenas como fallback), então não a trate como um conjunto fechado. Um localeFAILED failednem sempre trazerror: um cujas chaves foram todas retidas, e que portanto aparece emintegrityMismatches,providerFailuresoubudgetWithheld, falha sem que nada seja lançado. O motivo dele está nessas listas e nos seusnotices, comoSUB_para um lote de provedor com falha ouBATCH_ FAILED BUDGET_para o orçamento de tokens. TesteTOKENS_ EXCEEDED status, nunca a presença deerror. - cancelled só aparece quando o
signalda execução a abortou.RUN_diz o que isso deixa para trás.CANCELLED - estimate só aparece quando a execução pediu uma estimativa prévia. A lista
caveatsdela nunca é vazia e nomeia o que o valor deixa de fora, como membros deEstimateCaveatCode:CACHE_: a memória de tradução não é lida, então as chaves que uma execução real atenderia pelo cache continuam sendo contadas. Vale para toda estimativa.NOT_ CONSULTED SOURCE_: uma execução real envia um representante por string de origem idêntica; a estimativa conta todas as chaves. Vale para toda estimativa.DUPLICATES_ NOT_ DEDUPLICATED TRANSPORT_: uma chamada cobrável é contada por requisição planejada, embora os SDKs dos provedores possam tentar de novo uma chamada com falha por baixo, e uma tentativa repetida ainda possa ser cobrada. Vale para toda estimativa.RETRIES_ NOT_ COUNTED TRANSLATION_: a resposta é dimensionada a partir da origem mais uma margem fixa de expansão, então um idioma de destino mais longo relata mais tokens de resposta. Só para provedores cobrados por token.LENGTH_ IS_ ESTIMATED TOKEN_: os tokens são derivados de contagens de caracteres, não do tokenizador do próprio provedor. Só para provedores cobrados por token.COUNT_ IS_ HEURISTIC REPAIR_: a rodada de reparo para chaves que voltaram ausentes e a nova tentativa em metades para uma resposta cortada não são contadas. Só para provedores cobrados por token.REQUESTS_ NOT_ COUNTED
- cacheHits lista as chaves atendidas pelo cache da memória de tradução (veja O cache de tradução) em vez de
pelo provedor. fuzzyHits lista as chaves que reutilizaram uma tradução para uma string de origem
que havia mudado, cada uma com
key,similaritye opreviousSourcecom o qual correspondeu; ela fica vazia a menos quefuzzyCacheesteja ativado, e essas chaves nunca são contadas em cacheHits. unfilled, malformedRows e duplicateKeys só são preenchidas porimportWorkbook(uma execução detranslateas deixa vazias): uma linha em branco cuja chave ainda precisa de tradução no momento da importação (exportada comonewou comochanged), uma linha da pasta de trabalho que o leitor não conseguiu analisar e uma chave duplicada cuja primeira ocorrência prevaleceu. Olineopcional das duas últimas é a linha do arquivo em que o registro começa, presente só em uma importação de arquivo delimitado (csvoutsv). A única exceção é um projeto somente humano (veja Trabalhar sem tradução automática): nele,translateewatchlistam em unfilled toda chave para a qual a memória de tradução não tinha uma entrada exata, e fuzzyHits continua vazia porque a reutilização aproximada nunca é aplicada ali. - protected lista as chaves que uma execução de
translatedeixou como estavam, cada uma com seureason(human,import,externaloupinned) e, sobhumanEdits: "suggest", umasuggestion(a resposta do provedor ou uma entrada exata da memória de tradução, nunca uma correspondência aproximada), que não foi gravada, e umsuggestionStatus:plannedem uma simulação,suggested, ou o motivo de não ter sido (integrity-mismatch,provider-failure,budget-withheld,sensitive-withheld). Uma sugestão com falha nunca altera o status do locale. Elas não estão em translated, nunca alteram o status de um locale e continuam obsoletas para ocheck.importWorkbooka deixa vazia. Veja Manter traduções humanas.
Dois desses tipos de entrada são exportados por conta própria: cada entrada de protected é um ProtectedKey, e cada aviso do SDK em notices é um SdkNotice.
Propriedade
Tipo
Propriedade
Tipo
budgetStanding
Classifica um RunBudget em um de três valores de BudgetStanding, a mesma classificação que a linha de orçamento
da CLI, o Studio e a ferramenta de agente usage.summary relatam: "within" quando a execução nunca
chegou ao teto, "stopped-before-ceiling" quando um orçamento "stop" reteve uma requisição enquanto
tokensUsed ainda estava abaixo de maxTokens, e "reached" quando tokensUsed chegou a maxTokens ou o
passou. Use-a em vez de ler só exceeded, que é true nos dois últimos
casos.
function budgetStanding(budget: RunBudget): BudgetStanding;Retorna: BudgetStanding