Referência / SDK
Página traduzida automaticamente
Revisar e retraduzir
Leia valores em massa ou página por página, aprove, rejeite ou retraduza uma chave, ou revise e retraduza várias de uma vez.
Operações em uma única chave
Estas são as chamadas que o Verbatra Studio aciona; use-as para construir sua própria ferramenta de revisão. As que recebem um locale e uma key os resolvem de novo a cada chamada e lançam UNKNOWN_ ou UNKNOWN_ quando qualquer um dos dois não existe.
keyValue
Lê o valor de origem atual de uma chave e, quando existe, o valor de destino atual dela para um locale. Somente leitura.
function keyValue(
input: KeyValueInput,
deps?: KeyValueDeps,
): Promise<KeyValueResult>;Propriedade
Tipo
Retorna: KeyValueResult
Lança: UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_
Exemplo: Editar e retraduzir uma única chave
Retorna { source, target? }; target está ausente exatamente quando a chave ainda não existe nesse locale e, quando presente, vem com provenance, o KeyProvenance interpretado da chave: { origin, provider?, model?, reviewState, reviewer? }.
O resultado também traz description quando o arquivo de origem dá uma à chave: um @key.description do ARB, uma nota do XLIFF, ou um comentário do gettext, do .strings da Apple ou do .resx do .NET.
keyContext
Lê o que um tradutor precisa para escrever uma chave em um locale de destino: tudo o que keyValue retorna, mais os termos do glossário que se aplicam ao texto de origem e o maxLength da chave. Passe um draft para conferi-lo com esses termos. Somente leitura. Para reler do disco um glossário em arquivo, ele recebe loaded de loadConfigWithMeta, não uma configuração simples.
function keyContext(
input: KeyContextInput,
deps?: KeyContextDeps,
): Promise<KeyContext>;Propriedade
Tipo
Retorna: KeyContext
Lança: UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_
Um glossário ilegível não lança erro: glossary fica vazio e glossaryNotice traz o código do erro e a mensagem ocultada. draftCheck diz, por termo aplicável, se o rascunho usa a tradução exigida e quais traduções proibidas ele usa.
localeHistory
Lista os commits recentes do git que tocaram o arquivo do locale de origem ou de um locale de destino, do mais novo ao mais antigo. Somente leitura; executa git log pelo execFile injetável.
function localeHistory(
input: LocaleHistoryInput,
deps?: LocaleHistoryDeps,
): Promise<LocaleHistoryResult>;Propriedade
Tipo
Retorna: LocaleHistoryResult
Lança: LOCALE_, LOCALE_
Cada commit traz hash, author (o nome depois do .mailmap, nunca o e-mail), authorDate, subject e touchedPaths. limit tem como padrão LOCALE_ (50), no máximo LOCALE_ (200), no mínimo 1. author e subject perdem caracteres de controle e de direção, têm chaves de API conhecidas substituídas por [REDACTED] e são cortados em 200 e 500; um commit com metadados ilegíveis fica de fora. Um repositório ilegível, ou um git log que passe de LOCALE_ ou LOCALE_, dá { available: false, reason } com um motivo de LOCALE_. Veja Studio e MCP.
localeGitStatus
Lista quais arquivos de locale, verbatra.lock.json e verbatra.provenance.json diferem do último commit, e o branch em uso. Somente leitura; não recebe nenhum caminho de quem chama.
function localeGitStatus(
input: LocaleGitStatusInput,
deps?: LocaleGitStatusDeps,
): Promise<LocaleGitStatusResult>;Propriedade
Tipo
Retorna: LocaleGitStatusResult
Lança: LOCALE_, LOCALE_
Cada arquivo alterado traz path, locales e um state de LOCALE_. Um arquivo atrás de um link simbólico ou dentro de um submódulo nunca é listado; o apple-strings também observa o arquivo .stringsdict. O executor padrão inicia o git com um ambiente mínimo (configuração global só a partir de HOME) e com travas opcionais, core.fsmonitor, repositórios bare, busca sob demanda (lazy fetch), submódulos e filtros de conteúdo configurados desativados, compara caminhos literalmente e o encerra depois de LOCALE_ ou LOCALE_; um execFile que você injetar deve fazer o mesmo. Um clone parcial precisa do git 2.45 ou mais recente, senão git-too-old. O verbatra.config.ts de um projeto ainda é código que o verbatra executa. Quando o git não consegue ler o repositório, ou um files.pattern coloca um arquivo de locale fora da pasta do projeto (outside-project), o resultado é { available: false, reason }, com um motivo de LOCALE_.
localeGitDiff
Compara o arquivo de um locale em HEAD com o arquivo em disco, chave por chave. Somente leitura; recebe um locale, nunca um caminho, e não executa nenhum git diff, driver de conversão de texto nem diff externo.
function localeGitDiff(
input: LocaleGitDiffInput,
deps?: LocaleGitDiffDeps,
): Promise<LocaleGitDiffResult>;Propriedade
Tipo
Retorna: LocaleGitDiffResult
Lança: UNKNOWN_, LOCALE_, LOCALE_
added e removed listam { key, value }, changed lista { key, before, after }, e state é o estado do arquivo ou unchanged; um arquivo conflicted ou unchanged não lista nenhuma diferença. O arquivo versionado é lido com git cat-file blob, só se for um arquivo regular de no máximo LOCALE_. No máximo LOCALE_ chaves são listadas e cada texto é cortado em LOCALE_ caracteres, e qualquer um dos dois define truncated. Só o diff responde custom-adapter, para um formato custom: ou um adapterRegistry; um lado ausente é vazio, e um que não é um arquivo regular ou não pode ser analisado dá revision-unreadable ou working-file-unreadable. Os outros motivos são os de localeGitStatus.
retranslateEntry
Executa o provedor de novo para uma chave e um locale pelo caminho do provedor e pela barreira de integridade que o translate usa e, se o valor for aceito, grava o arquivo de locale e a entrada do arquivo de lock somente dessa chave.
function retranslateEntry(
input: RetranslateEntryInput,
deps?: RetranslateEntryDeps,
): Promise<RetranslateEntryResult>;Propriedade
Tipo
Retorna: RetranslateEntryResult
Lança: MACHINE_, LOCK_, UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_, KEY_, KEY_, PROVIDER_, NETWORK_, CONFIG_, LOCK_, RUN_, TARGET_, LOCALE_, LOCK_, PROVENANCE_, SENSITIVE_
Exemplo: Editar e retraduzir uma única chave
Retorna { accepted: true, value, reviewReasons } ou a recusa que editEntry retorna. Diferente do translate, uma falha do provedor aqui lança um erro: um ProviderError, exportado de @verbatra/sdk, com um code estável como RATE_ ou AUTH_. Sob provider: { id: "none" }, ele lança MACHINE_ primeiro, antes de ler ou travar qualquer coisa.
Os dois resultados trazem usage, as contagens de tokens do provedor, só quando ele as informa.
O novo valor é registrado em verbatra.provenance.json como machine, com o id do provedor que respondeu e o modelo configurado. Um provedor vindo do seu createProvider é registrado sob o próprio id, e sem o modelo quando ele difere do configurado. Um arquivo de procedência corrompido lança PROVENANCE_ antes de o provedor ser chamado.
Uma chave cujo valor uma pessoa escreveu, importou ou alterou fora do verbatra lança KEY_ dentro da trava de escrita, antes de o provedor ser chamado, a menos que includeHuman: true seja passado ou a configuração defina humanEdits: "overwrite"; sob um arquivo de procedência de um verbatra mais novo, qualquer valor existente conta como protegido. Uma chave que corresponde a pinnedKeys lança KEY_ antes de o provedor ser instanciado, mesmo com includeHuman.
approveEntry
Registra que uma pessoa revisou o valor atual de uma chave em um locale e o aceita. Grava somente verbatra.provenance.json, nunca um arquivo de locale nem o arquivo de lock, e não chama nenhum provedor. A aprovação também guarda o hash de origem do arquivo de lock para a chave, então ela volta a ser lida como não revisada quando a origem muda; qualquer gravação posterior que altere o valor inicia um registro novo, não revisado.
function approveEntry(
input: ReviewDecisionInput,
deps?: ReviewDecisionDeps,
): Promise<ReviewDecisionResult>;Propriedade
Tipo
Retorna: ReviewDecisionResult
Lança: REVIEWER_, LOCK_, UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_, LOCK_, RUN_, REVIEW_, LOCALE_, REVIEW_, LOCK_, PROVENANCE_, PROVENANCE_
Exemplo: Percorrer a fila de revisão
Passe exatamente um entre expectedValue e expectedValueHash, este último com a dependência valueMarker: os dois, nenhum, um expectedValue que não é uma string, ou um hash sem o seu marcador lançam REVIEW_ antes de qualquer leitura. expectedValue é o texto que quem revisou viu, ou passe expectedValueHash com o valueMarker que o produziu: a chamada lança REVIEW_ quando a chave não tem valor ou tem um diferente, e REVIEW_ quando a origem mudou desde que o valor foi gravado. reviewer é texto livre opcional de 1 a 64 caracteres, sem caracteres de controle (REVIEWER_ caso contrário), guardado no arquivo versionado e nunca preenchido pelo verbatra. Retorna { locale, key, provenance }. Um valor sem registro ainda, ou alterado fora do verbatra, é registrado com o origin unknown.
rejectEntry
Registra que uma pessoa revisou o valor atual de uma chave em um locale e o recusa, e o remove do arquivo de locale e do arquivo de lock, então check e diff o relatam como ausente e o próximo translate o preenche de novo (sob provider: { id: "none" }, ele continua ausente até alguém escrever um). O registro de procedência permanece como rejected, com um hash do texto removido, e a entrada correspondente na memória desta máquina é descartada; um translate posterior ignora qualquer acerto exato ou aproximado da memória para a chave que corresponda a esse hash, então a memória de nenhuma máquina traz o texto de volta. Não chama nenhum provedor.
function rejectEntry(
input: ReviewDecisionInput,
deps?: ReviewDecisionDeps,
): Promise<ReviewDecisionResult>;Propriedade
Tipo
Retorna: ReviewDecisionResult
Lança: REVIEWER_, LOCK_, UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_, LOCK_, RUN_, REVIEW_, LOCALE_, TARGET_, REVIEW_, REVIEW_, LOCK_, PROVENANCE_, PROVENANCE_
Exemplo: Percorrer a fila de revisão
A entrada é verificada como no approveEntry, exceto que uma origem obsoleta não bloqueia uma rejeição. Retorna { locale, key, provenance }. Um formato que mantém uma chave que não lhe foi dada, o XLIFF, lança REVIEW_ depois de restaurar o arquivo.
As duas chamadas obtêm a trava de escrita do locale com lockAcquireTimeoutMs e onLockWait, como no editEntry; LOCK_ significa que o limite não é um número inteiro de milissegundos de pelo menos 0. O tempo limite não limita a trava sobre o arquivo de lock obtida para registrar a decisão, que sempre permite o padrão de dez minutos.
Nenhuma das duas relata uma decisão que não conseguiu salvar: um arquivo de procedência de um verbatra mais novo, ou um que a decisão faria crescer além do tamanho que o verbatra lê de volta, lança PROVENANCE_ antes de qualquer gravação.
createValueMarker
Cria o marcador que uma interface usa para mostrar um valor sem o texto dele: mark(value) retorna [redacted length=<n> hash=<h>], e hash(value) retorna h, um HMAC hexadecimal de 16 dígitos cuja chave é um salt aleatório (ou o salt informado), então um hash só corresponde sob o mesmo marcador. Passe esse marcador como valueMarker a approveEntry ou rejectEntry para aceitar expectedValueHash no lugar de expectedValue. O verbatra mcp --redact-values cria um a cada início do servidor.
function createValueMarker(salt?: Uint8Array): ValueMarker;Retorna: ValueMarker
Leituras de conteúdo em massa
localeValues
Lê o texto de origem e de destino atual de todas as chaves nos locales de destino pedidos, em uma única passagem pelos arquivos em disco, por exemplo para buscar valores e não nomes de chaves: a contrapartida em massa de keyValue. Somente leitura.
function localeValues(
input: LocaleValuesInput,
deps?: LocaleValuesDeps,
): Promise<readonly LocaleValues[]>;Propriedade
Tipo
Retorna: readonly LocaleValues[]
Lança: UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_
Exemplo: Ler todos os valores em massa
Um locales omitido cobre todos os locales de destino configurados. Retorna um { locale, keys, values } por locale: keys lista todas as chaves na ordem da origem e depois as que existem só no destino, e values mapeia cada chave para { source?, target? }. Sem target significa que ainda não foi traduzida ali; sem source significa órfã (ausente da origem). values não tem protótipo, então toda chave, até _ ou constructor, é uma propriedade própria e uma chave ausente é lida como undefined.
Cada par com um target também traz provenance, o mesmo KeyProvenance que keyValue informa.
localeValuesPage
Lê uma página de localeValues, opcionalmente restrita a keys exatas ou a uma query comparada com a chave e com o texto de origem e de destino, sem diferenciar maiúsculas de minúsculas, e retorna um cursor para a próxima página. O servidor MCP e a ferramenta de agente verbatra_ do Studio paginam com ela. Somente leitura.
function localeValuesPage(
input: LocaleValuesPageInput,
deps?: LocaleValuesDeps,
): Promise<LocaleValuesPage>;Propriedade
Tipo
Retorna: LocaleValuesPage
Lança: UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_, PAGE_, PAGE_
Retorna { locales, nextCursor? }: cada locale com uma entrada na página traz entries, cada uma { key, source?, target?, provenance? } como localeValues informa, ordenadas por locale e depois por chave. Uma página tem no máximo limit entradas: PAGE_ (200) por padrão, PAGE_ (1000) no máximo. Passe nextCursor de volta como cursor, com os mesmos filtros, até ele estar ausente. Toda chamada lê os arquivos de novo, então um cursor cuja chave se moveu ou sumiu é recusado em vez de pular ou repetir entradas.
Um cursor tem no máximo PAGE_ (512) caracteres. O servidor MCP e o Studio aceitam uma query de no máximo LOCALE_ (500) caracteres.
Revisão e retradução em lote
Cada uma destas executa a chamada de chave única correspondente uma vez por entrada, em ordem, e retorna { results } com um resultado por entrada. Uma entrada com falha não interrompe o lote: o resultado dela é { locale, key, ok: false, code, message }, com o código do SdkError, do erro de adaptador ou do ProviderError e uma mensagem ocultada. Qualquer outro erro interrompe o lote com um BatchInterruptedError. Uma lista entries vazia retorna um results vazio.
approveEntries
Executa approveEntry por entrada, com as mesmas verificações; reviewer vale para todas as entradas. Um resultado bem-sucedido é { ok: true, locale, key, provenance }. lockAcquireTimeoutMs limita a espera de cada entrada pela trava de escrita do locale dela, e onLockWait informa essa espera. Uma entrada cuja trava continua ocupada além do tempo limite falha com LOCK_, e toda entrada posterior que precisa da mesma trava recebe { locale, key, ok: false, skipped: true, code: "LOCK_ em vez de esperar de novo; as entradas de outros locales ainda são decididas.
function approveEntries(
input: ReviewEntriesInput,
deps?: ReviewDecisionDeps,
): Promise<ReviewEntriesResult>;Propriedade
Tipo
Retorna: ReviewEntriesResult
Lança: LOCK_
rejectEntries
Executa rejectEntry por entrada, removendo cada valor rejeitado. Um resultado bem-sucedido é { ok: true, locale, key, provenance }. Um tempo limite de trava pula as entradas posteriores que precisam dessa trava, como no approveEntries.
function rejectEntries(
input: ReviewEntriesInput,
deps?: ReviewDecisionDeps,
): Promise<ReviewEntriesResult>;Propriedade
Tipo
Retorna: ReviewEntriesResult
Lança: LOCK_
approveLocale
Aprova a fila de revisão inteira de um locale, ou só os valores dele com uma das origins, em uma única gravação de verbatra.provenance.json sob a trava de escrita do locale, cada um registrado como o approveEntry registra um. Ele não recebe valor esperado e aprova o que a fila contém quando é executado, então mostre antes a fila a quem revisa. Retorna { locale, approved, sourceChanged }: as chaves aprovadas e as chaves da fila deixadas como não revisadas porque a origem delas mudou desde que foram gravadas. Não chama nenhum provedor e falha com PROVENANCE_ em vez de relatar aprovações que não conseguiu salvar.
function approveLocale(
input: ApproveLocaleInput,
deps?: ApproveLocaleDeps,
): Promise<ApproveLocaleResult>;Propriedade
Tipo
Retorna: ApproveLocaleResult
Lança: REVIEWER_, LOCK_, UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, LOCK_, RUN_, LOCALE_, LOCK_, PROVENANCE_, PROVENANCE_
retranslateEntries
Executa retranslateEntry por entrada, então faz até uma chamada ao provedor por entrada. Não é uma execução de translate: maxTokens e budgetBehavior não se aplicam, e o número de entradas é o único limite do que ele gasta. Um resultado concluído é { ok: true, locale, key, result }, em que result é o que retranslateEntry retornou, inclusive um valor que a barreira de integridade recusou. Um valor que uma pessoa escreveu falha com KEY_, a menos que includeHuman: true seja passado. As opções de trava funcionam como no approveEntries, e a espera termina antes de o provedor ser chamado.
function retranslateEntries(
input: RetranslateEntriesInput,
deps?: RetranslateEntryDeps,
): Promise<RetranslateEntriesResult>;Propriedade
Tipo
Retorna: RetranslateEntriesResult
Lança: LOCK_
Um erro que faria todas as entradas falharem do mesmo modo interrompe as chamadas ao provedor: MISSING_, AUTH_, RATE_ (que cobre uma cota esgotada), NETWORK_, PROVIDER_, CONFIG_ ou MACHINE_. A entrada que o encontrou falha como de costume, e toda entrada depois dela recebe { locale, key, ok: false, skipped: true, code, message } nomeando esse código, sem outra chamada ao provedor.
Um tempo limite de trava pula as entradas posteriores que precisam dessa trava com LOCK_, como no approveEntries; para um formato que guarda todos os locales em um único arquivo, isso vale para toda entrada posterior.
BatchInterruptedError
Lançado por approveEntries, rejectEntries e retranslateEntries quando um erro que não é o resultado de uma entrada, como uma falha inesperada do sistema de arquivos, interrompe um lote no meio. results guarda os resultados das entradas concluídas antes dele, em ordem, cujas gravações permanecem em disco; entry nomeia o { locale, key } que estava em execução, e cause é o erro original. As entradas depois de entry não foram executadas.
class BatchInterruptedError<R = ReviewBatchOutcome | RetranslateBatchOutcome> extends ErrorPropriedade
Tipo