Referência / SDK
Página traduzida automaticamente
Inspecionar um projeto
Pontos de entrada somente leitura por trás de doctor, check e diff, verificações de integridade e estado do arquivo de lock e da procedência. Nenhum grava.
Inspecionar o estado sem gravar
Nenhuma destas funções traduz nem altera o arquivo de lock. Só extract grava um arquivo (o catálogo de origem), e
só doctor com live faz uma requisição de rede (a lista de idiomas do provedor).
doctor
Valida a configuração do projeto e não gasta nada: não instancia nenhum provedor, não faz nenhuma requisição
de rede a menos que live peça uma, e lê o valor da chave de API só para essa única requisição da lista de
idiomas (o LibreTranslate não recebe chave de API). Toda verificação é executada mesmo quando uma anterior falhou, então uma
chamada relata todos os problemas independentes; o verbatra doctor lista as
verificações.
function doctor(
input?: DoctorInput,
deps?: DoctorDeps,
): Promise<DoctorResult>;Propriedade
Tipo
Retorna: DoctorResult
Lança: CONFIG_
A verificação network-policy falha quando a política de rede efetiva (veja Restringir o acesso à rede) recusa
o host ou o proxy do provedor, ou quando uma variável de rede é inválida, e passa para o provedor none.
As verificações informativas nunca falham e não renomeiam nada; um warn deixa ok verdadeiro, e a
tabela de verificações diz o que cada uma nomeia e quando fica skipped.
A verificação locales avalia todo locale configurado como o translate faz antes de gastar: ela falha
com um locale não aceito, fica skipped para none e retorna os veredictos em
DoctorResult.locales como um LocaleCapabilityReport. Com live: true, ela busca primeiro a lista atual de idiomas
do provedor, sem usar cota; LocaleCapabilityReport.live diz como isso foi.
Veja Verificar o suporte antes de uma execução.
Com literals definido, só as verificações config e untranslated-literals são executadas, como faz o
verbatra doctor --literals. O doctor carrega a
configuração por conta própria, então um projeto sem configuração recebe um relatório, não um erro lançado: ok é verdadeiro exatamente
quando nenhuma verificação falhou, e CONFIG_ é lançado só para um configPath explícito que
não existe.
Só uma verificação que falhou traz fix, um próximo passo no imperativo; como detail, ele nomeia variáveis e
caminhos, nunca o valor de uma chave de API.
dataFlow
Descreve para onde vão os dados de um projeto, para a configuração carregada, como um DataFlowManifest versionado. O verbatra doctor --data-flow o imprime e lista os seus campos; doctor({ dataFlow: true }) o retorna como DoctorResult.dataFlow. Ele não lê nenhuma chave de API e não faz nenhuma requisição de rede. Uma variável de rede inválida ou um arquivo de origem ilegível é relatado no manifesto em vez de lançado.
function dataFlow(
input?: DataFlowInput,
deps?: DataFlowDeps,
): Promise<DataFlowManifest>;Propriedade
Tipo
Retorna: DataFlowManifest
Lança: CONFIG_, CONFIG_
dataFlowManifestSchema
O schema zod de um DataFlowManifest, para que uma etapa de CI ou a ferramenta de quem revisa possa validar um. Os campos desconhecidos são mantidos, já que um verbatra mais novo pode adicionar campos dentro da versão 1; ignore os que você não conhece. DATA_ é a version que este build grava.
const dataFlowManifestSchema: z.ZodType<DataFlowManifest>;extract
Varre o código-fonte do seu app em busca de pontos de chamada de tradução e mescla o que encontra no catálogo do locale de origem, mesmo um que ainda não existe. Não instancia nenhum provedor, não lê nenhuma chave de API e não faz nenhuma requisição de rede.
function extract(
input: ExtractInput,
deps?: ExtractDeps,
): Promise<ExtractResult>;Propriedade
Tipo
Retorna: ExtractResult
Lança: EXTRACT_, EXTRACT_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_
Exemplo: Extrair chaves do seu código-fonte
Só as chaves realmente novas são adicionadas (O que ele grava). O que a
varredura não consegue resolver volta como dados em dynamic, conflicts e diagnostics, nunca lançado
(O que ele relata em vez de adivinhar), e o resultado nunca
traz o conteúdo de um arquivo de origem.
config.extract nomeia o framework e os diretórios-raiz do código-fonte. A descoberta precisa do membro opcional
readDirectory de SdkFs; sem ele, EXTRACT_.
check
Relata a divergência por locale em contagens: missing (na origem, ausente do destino), stale (origem
alterada desde a última tradução) e upToDate. Use-o como barreira na CI.
function check(
input: CheckInput,
deps?: CheckDeps,
): Promise<CheckSummary>;Propriedade
Tipo
Retorna: CheckSummary
Lança: UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, LOCK_, UNKNOWN_
Exemplo: Verificar na CI sem gravar
inSync é verdadeiro exatamente quando todo locale verificado não tem nada ausente nem obsoleto.
Com consistency: true, cada LocaleCheckSummary também traz inconsistencies: um
InconsistencyGroup por string de origem que o locale traduz de mais de uma forma sob chaves diferentes,
no formato que o relatório de consistência mostra. É só um
relatório: nunca altera inSync, uma contagem ou qualquer arquivo.
Cada LocaleCheckSummary também traz provenance: contagens byOrigin e byReviewState sobre as
chaves para as quais o locale tem um valor, lidas do verbatra.provenance.json
(valores de origin). Esse e todo outro campo de procedência
de um relatório é omitido, nunca um erro, quando o arquivo está corrompido ou vem de um verbatra mais novo.
Cada LocaleCheckSummary também traz protected, a parcela de stale que uma execução do translate deixaria para uma pessoa sob humanEdits e pinnedKeys (Chaves protegidas). Elas continuam contando como obsoletas, então inSync fica falso até uma pessoa resolvê-las; uma chave fixada ausente conta só como ausente.
Com qa: true, o check também executa a verificação de qualidade sobre todo
valor versionado, sem chave de API e sem gravar: cada LocaleCheckSummary traz um relatório qa e
os totais qa do resumo, nos formatos dessa seção. Os motivos de erro vêm de INTEGRITY_,
os motivos de alerta de REVIEW_, as severidades de QA_; qaSeverity: "error"
ignora os alertas. Ele nunca altera inSync: uma barreira na CI lê qa.errors, mais qa.warnings quando estrita.
Cada LocaleCheckSummary também traz incompletePlurals, ordenado por chave: um IncompletePlural
{ code: "PLURAL_ por plural que não tem categorias do CLDR
usadas pelo idioma de destino. É só um alerta;
categorias de plural lista os formatos e as regras.
Com requireReviewed: true, o check também executa a
barreira de revisão, sem chave de API e sem gravar: cada
LocaleCheckSummary traz review: { unreviewed }, as chaves da classe machine não aprovadas, e o
resumo traz review: { reviewed, unreviewed, code? } com os códigos que essa seção nomeia. O
relatório nunca altera inSync; uma barreira na CI lê review.reviewed.
Com sensitive: true, o check também executa a varredura de conteúdo sensível,
sem chave de API e sem gravar: o resumo traz sensitive: { findings, glossaryTerms }, um
{ key, fields, detectors } por chave sinalizada, nunca o texto encontrado. Uma barreira na CI falha com qualquer um dos dois.
checkFile
Verifica um arquivo de locale depois de uma edição. Ele lê esse arquivo, o arquivo de limites (um aviso se estiver inutilizável) e, para um locale de destino, o arquivo de origem; não chama nenhum provedor, não lê nenhuma chave de API e não grava nada.
function checkFile(
input: CheckFileInput,
deps?: CheckFileDeps,
): Promise<CheckFileSummary>;Propriedade
Tipo
Retorna: CheckFileSummary
Lança: NOT_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_
file é absoluto ou relativo a cwd; Um único arquivo mostra o formato de
CheckFileSummary. Um arquivo de destino é verificado como no check com qa: true, e o arquivo de origem só quanto à
sintaxe. Um arquivo que não pode ser analisado não gera erro lançado: o seu locale traz um QaSyntaxFinding,
com a posição que AdapterError.position relata para JSON e YAML. Um caminho que não é o arquivo de nenhum locale configurado, ou um arquivo ausente, lança NOT_.
diff
O irmão detalhado do check: o mesmo cálculo, mas retorna as listas de chaves por locale
(missing, changed, orphaned) em vez de contagens. As chaves órfãs só são relatadas e nunca invertem
hasPendingChanges, já que uma execução padrão não as remove.
function diff(
input: DiffInput,
deps?: DiffDeps,
): Promise<DiffSummary>;Propriedade
Tipo
Retorna: DiffSummary
Lança: UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, LOCK_, UNKNOWN_
Exemplo: Verificar na CI sem gravar
Com unused: true, ele também varre os roots do extract da configuração, somente leitura e sem chave de API, e adiciona um
relatório unused das chaves do locale de origem que nenhuma referência estática nomeia, separado de toda lista
orphaned e sem nunca inverter hasPendingChanges; Chaves de origem não usadas
explica os seus campos.
Cada LocaleDiff também traz changedOrigins, o origin do valor atual de cada chave changed
(como machine, human ou external): o trabalho de quem uma retradução substituiria.
Cada LocaleDiff também traz protected, as chaves ausentes e alteradas que uma execução do translate deixaria de lado, ordenadas; elas continuam contando como pendentes.
keyIntegrity
Relata, para as chaves alteradas de cada locale, se o valor de destino atual ainda corresponde aos
placeholders e à marcação inline da origem e é um ICU válido: cada entrada traz key,
hasPlaceholders, matches, os tokens missing e extra em caso de incompatibilidade, icuValid,
markupMatches e markupDetails, nunca o valor de uma string. Valores gravados antes de a barreira de gravação
existir ou editados fora do verbatra são avaliados do mesmo modo. O Studio mostra esse relatório por chave.
function keyIntegrity(
input: KeyIntegrityInput,
deps?: KeyIntegrityDeps,
): Promise<readonly LocaleKeyIntegrity[]>;Propriedade
Tipo
Retorna: readonly LocaleKeyIntegrity[]
Lança: UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, LOCK_, UNKNOWN_, UNKNOWN_
Cada entrada também traz icuArmsMatch e icuArmDetails: se os ramos plural,
selectordinal e select do ICU do valor servem ao idioma de destino, avaliados como a
barreira de gravação os avalia, com um
problema curto por ramo errado. icuArmsMatch é sempre verdadeiro para um formato que não verifica ramos.
keys restringe a verificação; só as chaves “changed” de um locale são verificadas.
localeIntegrity
Encontra toda tradução dos locales de destino que está quebrada agora: um placeholder ou uma marcação inline
perdida ou adicionada, um ICU inválido ou ramos de ICU que não servem ao idioma de destino. Ao contrário de
keyIntegrity, ele avalia toda chave presente na origem e em um locale de destino, seja qual for o seu estado
de sincronia, pelas mesmas regras, e retorna só as chaves com falha: uma lista entries vazia significa que o
locale passa.
function localeIntegrity(
input: LocaleIntegrityInput,
deps?: LocaleIntegrityDeps,
): Promise<readonly LocaleKeyIntegrity[]>;Propriedade
Tipo
Retorna: readonly LocaleKeyIntegrity[]
Lança: UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_
Cada chamada lê e analisa de novo o arquivo de origem e cada arquivo de destino pedido, sem cache.
lockState
Relata a existência do arquivo de lock, a sua versão e a divergência por locale (a contagem de chaves da linha de base mais as contagens de
ausentes, obsoletas e em dia). exists vem de uma sondagem explícita, então um arquivo de lock ausente e um vazio
continuam distinguíveis; quando ausente, o resultado é { exists: false } e nada mais é lido.
function lockState(
input: LockStateInput,
deps?: LockStateDeps,
): Promise<LockStateResult>;Propriedade
Tipo
Retorna: LockStateResult
Lança: UNKNOWN_, LOCK_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_
Cada locale também traz as mesmas contagens de provenance que o check relata.
loadLockFile
Lê o próprio arquivo de lock (verbatra.lock.json, também exportado como LOCK_) e retorna
o seu formato analisado: { version, locales }, em que cada locale mapeia chaves ao hash do conteúdo de origem a partir do qual
foram traduzidas pela última vez. Um arquivo ausente passa a ser tratado como um arquivo de lock vazio, o mesmo comportamento
de primeira execução em que o translate se apoia; use lockState quando precisar distinguir a ausência.
function loadLockFile(
input?: LoadLockFileInput,
deps?: LoadLockFileDeps,
): Promise<LockFile>;Propriedade
Tipo
Retorna: LockFile
Lança: LOCK_
Não precisa de configuração.
loadProvenance
Lê o próprio arquivo de procedência (verbatra.provenance.json, também exportado como
PROVENANCE_) e retorna o seu formato armazenado: { version, locales }, em que cada locale mapeia
chaves a um registro { origin, provider?, model?, valueHash, reviewState?, reviewer?, reviewedSourceHash? }, sem
nenhum texto traduzido. Um arquivo ausente, ou de um verbatra mais novo, é lido como vazio; um corrompido
lança PROVENANCE_. keyValue, localeValues, check, diff e lockState
relatam a visão interpretada (KeyProvenance), que também distingue unrecorded de external.
function loadProvenance(
input?: LoadProvenanceInput,
deps?: LoadProvenanceDeps,
): Promise<ProvenanceFile>;Propriedade
Tipo
Retorna: ProvenanceFile
Lança: PROVENANCE_
Não precisa de configuração.
runStatus
Lê o snapshot das sinalizações de revisão e do uso de tokens que a execução real (não simulada) mais recente do translate ou do watch
gravou em .verbatra-local/run-status.json. Nunca lança: um arquivo inutilizável
passa a available: false. O arquivo é telemetria feita na medida do possível, não uma linha de base para garantir a exatidão.
function runStatus(
input?: RunStatusInput,
deps?: RunStatusDeps,
): Promise<RunStatusResult>;Propriedade
Tipo
Retorna: RunStatusResult
Não precisa de configuração. Retorna { available: false, reason } (veja RUN_)
ou { available: true, version, generatedAt, usage?, budget?, locales, incomplete? }, em que incomplete: { failed, partial } conta os locales da execução registrada que falharam ou pararam no meio e é omitido quando nenhum o fez.
Um snapshot de antes de o orçamento de tokens ser aplicado ainda é lido, menos um budget com
supported: false (o seu tokensUsed: 0 não era uma contagem). Os novos snapshots só adicionam um campo marcador, então
um leitor mais antigo pode mostrar um orçamento estimado como não rastreado. Um motivo de revisão desconhecido é ignorado,
e uma entrada que fica sem nenhum é descartada.
reviewQueue
Lê a fila de revisão a partir dos arquivos versionados: toda chave cujo valor atual tem um origin da classe
machine (machine, memory, fuzzy ou agent, a tupla MACHINE_) e não está
aprovado, por locale de destino, na ordem da origem. Ele lê os arquivos de locale, o verbatra.lock.json e o
verbatra.provenance.json, então todos no mesmo commit veem a mesma fila. Uma chave sai dela quando
o seu valor é aprovado ou rejeitado, ou quando uma pessoa escreve ou importa um novo valor; um valor que um agente
reescreveu continua nela, e também uma aprovação dada antes de a origem mudar. O último snapshot do runStatus
só acrescenta detalhes: os reasons de cada entrada (vazios quando a execução não a sinalizou com um motivo conhecido),
os fuzzyHits do locale e lastRunAt.
function reviewQueue(
input: ReviewQueueInput,
deps?: ReviewQueueDeps,
): Promise<ReviewQueueResult>;Propriedade
Tipo
Retorna: ReviewQueueResult
Lança: UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, LOCK_
Exemplo: Percorrer a fila de revisão
Retorna { available: true, locales, lastRunAt? },
cada locale { locale, needsReview, approved?, fuzzyHits? } e cada entrada { key, reasons, provenance };
approved lista os valores aprovados da classe machine e só está presente com includeApproved: true.
Quando o arquivo de procedência está corrompido ou vem de um verbatra mais novo, retorna
{ available: false, reason: "provenance-unreadable" }. Um arquivo de origem, de destino ou de lock que não pode
ser lido faz a chamada falhar como faz o check falhar. Até a 0.11, a fila consistia só nas sinalizações da última execução.
provenanceReport
Monta o relatório por locale que o verbatra report provenance imprime: toda chave com um valor na origem
e em um locale de destino, na ordem da origem, com o seu origin, estado de revisão, provedor, modelo e
revisor, contada em um grupo de PROVENANCE_
(O relatório de procedência os define). Não chama nenhum
provedor e não grava nada.
function provenanceReport(
input: ProvenanceReportInput,
deps?: ProvenanceReportDeps,
): Promise<ProvenanceReportResult>;Propriedade
Tipo
Retorna: ProvenanceReportResult
Lança: UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, LOCK_
deps também aceita now, o relógio de generatedAt. O formato completo do resultado está em
O JSON Schema.
Quando o arquivo de procedência está corrompido ou vem de um verbatra mais novo, retorna
{ available: false, reason: "provenance-unreadable" }, já que todo valor seria lido como
unrecorded. Um arquivo de origem, de destino ou de lock que não pode ser lido faz a chamada falhar como faz o
check falhar. O relatório é uma evidência de apoio, não aconselhamento jurídico.
provenanceReportPage
Monta o mesmo relatório que o provenanceReport e retorna as suas entradas uma página por vez, opcionalmente só as de alguns buckets, com um cursor para a próxima página. Toda página mantém o total e os counts completos de cada locale. O report.provenance do servidor MCP pagina com ele. Somente leitura.
function provenanceReportPage(
input: ProvenanceReportPageInput,
deps?: ProvenanceReportDeps,
): Promise<ProvenanceReportPageResult>;Propriedade
Tipo
Retorna: ProvenanceReportPageResult
Lança: UNKNOWN_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, LOCK_, PAGE_, PAGE_
Cada locale traz entries só nas páginas que contêm uma delas. Uma página contém no máximo limit entradas, PAGE_ por padrão; devolva nextCursor como cursor, com os mesmos locales e buckets, até ele estar ausente. A chamada fica indisponível, ou falha, exatamente quando o provenanceReport fica.
previewIcuMessage
Renderiza uma mensagem ICU como ela é lida em um locale: uma linha por ramo, ou seja, cada categoria de plural, ramo exato e opção de select e cada lugar em que um aparece, variando um argumento por vez e mantendo os demais em amostras. Ele pré-visualiza só os formatos cujas mensagens usam a sintaxe ICU, next-intl-json e arb; qualquer outro formato, inclusive um custom:, responde supported: false. A mensagem é texto não confiável e a chamada nunca lança por causa dela: uma mensagem com mais de 20.000 caracteres, aninhada além de 16 chaves { }, com mais de 256 caracteres { e < ou que não é um ICU válido volta como valid: false com um reason, e o mesmo vale para um locale desconhecido. Ele não lê nem grava nenhum arquivo e não faz nenhuma requisição.
function previewIcuMessage(input: IcuPreviewInput): IcuPreviewResult;Propriedade
Tipo
Retorna: IcuPreviewResult
Números e datas usam os dados CLDR do Node deste runtime, e as datas, em um instante fixo em UTC, a menos que um número em args defina o instante, então o texto pode diferir do que o runtime do seu próprio app imprime. Uma linha contém segments de texto simples, do tipo text, argument ou tag, nunca marcação a interpretar. Uma linha de um argumento aninhado contém o argumento que o envolve no ramo que o contém, então mostra o ramo que nomeia, e o lista em held. Um valor em args para um argumento de plural, ordinal ou select adiciona uma linha marcada como supplied para cada eixo que ele controla, mostrando o ramo que esse valor alcança; um valor que não alcança nenhum ramo de um eixo não adiciona nenhuma. No máximo 24 linhas voltam, dentro de um único orçamento de saída; linhas com o mesmo rótulo e texto são fundidas, e truncated é definido quando um ramo alcançável ficou de fora.