Pular para o conteúdo
Pular para o conteúdo

Referência / SDK

Página traduzida automaticamente

Esta página foi traduzida automaticamente, então pode ter erros ou soar um pouco estranha. A versão em inglês é a fonte da verdade. Ler o original em inglês.

Executar traduções

translate, watch e os pontos de entrada em torno de uma execução, além de pseudolocales e catálogos tipados, tudo disponível para os seus scripts Node.js.

Traduzir e observar

translate

O fluxo de execução única: lê a origem, compara cada locale de destino com a linha de base do arquivo de lock, envia ao provedor as chaves ausentes e alteradas, executa as verificações de integridade, grava os arquivos de locale e atualiza o arquivo de lock. Use-o em scripts, etapas de build e jobs de CI.

Assinatura
function translate(
  input: TranslateInput,
  deps?: TranslateDeps,
): Promise<RunSummary>;

Propriedade

Tipo

Retorna: RunSummary

Lança: UNKNOWN_LOCALE, LOCALE_UNSUPPORTED_BY_PROVIDER, UNKNOWN_FORMAT, CONCURRENCY_INVALID, CONCURRENCY_BUDGET_CONFLICT, MAX_TOKENS_INVALID, LOCK_TIMEOUT_INVALID, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, PROVIDER_CONSTRUCTION_FAILED, NETWORK_POLICY_VIOLATION, CONFIG_INVALID, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID

Exemplo: Traduzir e ler o resumo

O que a tabela não cobre:

  • cache é o cache local de memória de tradução (verbatra.cache.json, também exportado como CACHE_FILE_NAME); veja O cache de tradução.
  • humanEdits (requer a 0.12.0 ou mais recente): por padrão, as chaves obsoletas que uma pessoa escreveu, importou ou alterou fora do verbatra são mantidas e listadas em LocaleSummary.protected. Veja Manter traduções humanas.
  • onProgress recebe os eventos de progresso abaixo (veja Eventos de progresso).
  • maxBatchSize e budgetBehavior existem só na configuração; não há substituição por execução.

Um problema que afeta a execução inteira lança um SdkError; a falha de um único locale nunca lança um erro e aparece como status: "failed" na entrada desse locale enquanto a execução continua. Veja A anatomia do RunSummary.

Eventos de progresso

O onProgress recebe um ProgressEvent, uma união discriminada por type. Uma versão minor pode acrescentar tipos, então ignore um que você não reconheça.

typeQuandoCampos
locale-startedo trabalho de um locale começalocale, localeIndex, totalLocales
locale-planneddepois que a memória de tradução é consultada, antes de o primeiro lote ser enviado; só quando um provedor é chamadolocale, keys, batches, cacheHits
sub-batchlogo antes de cada lote de tradução ser tentadolocale, batchIndex, totalBatches
provider-retryum provedor embutido tenta de novo uma requisição que falhou com um status que permite nova tentativaattempt, delayMs?, status?
repairum provedor de LLM pede de novo as chaves que sua primeira resposta deixou de foralocale, keys
split-retryum lote cuja saída foi cortada é tentado de novo em duas metadeslocale, keys
batch-finishedum lote terminou, tenha dado certo ou nãolocale, batchIndex, totalBatches, durationMs, usage?
writinglogo antes de o arquivo de um locale ser gravadolocale
locale-finishedo trabalho de um locale terminalocale, status, translated, localeIndex, totalLocales
run-finishedtodos os locales terminaramlocalesCompleted, localesFailed
change-detectedsó no watch: uma alteração no arquivo de origem se estabilizoupaths
idlesó no watch: uma execução terminou e nenhuma está na filanenhum

O provider-retry não nomeia nenhum locale, porque um único provedor atende a execução inteira. O Gemini informa o atraso e o status; o Anthropic, o OpenAI, o OpenCode e o openai-compatible informam a tentativa no momento em que o cliente deles a inicia; e o DeepL, o Google Cloud Translation e o LibreTranslate não informam nenhum dos dois. Uma simulação e uma estimativa emitem apenas locale-started, locale-finished e run-finished. Os registros de progresso do --json da CLI ficam nos quatro tipos originais: locale-started, sub-batch, locale-finished e run-finished.

O extract, o diff com unused e o doctor com literals recebem um onProgress próprio. Ele recebe um ScanProgressEvent, { type: "files-scanned", scanned, total }, uma vez após cada arquivo de código-fonte do aplicativo que a varredura lê.

Propriedade

Tipo

Um CreateProvider personalizado recebe um terceiro argumento, CreateProviderHooks, sempre que uma execução informa progresso. Chame o onRetry dele com { attempt, delayMs?, status? } e as novas tentativas do seu provedor aparecem como eventos provider-retry.

resolveDryRun

Responde se um conjunto de opções de execução equivale a uma simulação. Recebe o dryRun e o estimate que você está prestes a passar ao translate e retorna se essa execução vai instanciar um provedor, gravar um arquivo ou gastar alguma coisa. É o único lugar em que se decide a regra de que estimate implica dryRun, então recorra a ele sempre que algo em volta de uma execução precisar saber de antemão, em vez de repetir a implicação e se afastar dela.

Assinatura
function resolveDryRun(input: {
  readonly dryRun?: boolean | undefined;
  readonly estimate?: boolean | undefined;
}): boolean;

Retorna: boolean

Exemplo
import { resolveDryRun, translate, type VerbatraConfig } from "@verbatra/sdk";

declare const config: VerbatraConfig;

const options = { dryRun: false, estimate: true };
resolveDryRun(options); // true

const summary = await translate({ config, ...options });

watch

Observa o arquivo de locale de origem e executa translate de novo a cada alteração com debounce. Dispara uma execução inicial logo na inicialização e depois uma execução por alteração estabilizada. As execuções são serializadas: as alterações durante uma execução se reduzem a uma única execução seguinte.

Assinatura
function watch(
  input: WatchInput,
  deps?: WatchDeps,
): Promise<WatchController>;

Propriedade

Tipo

Retorna: WatchController

Lança: UNKNOWN_LOCALE, LOCALE_UNSUPPORTED_BY_PROVIDER, CONCURRENCY_INVALID, LOCK_TIMEOUT_INVALID, CONCURRENCY_BUDGET_CONFLICT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, NETWORK_POLICY_VIOLATION, PROVIDER_CONSTRUCTION_FAILED, CONFIG_INVALID

Exemplo: Observar em um processo de longa duração

O debounceMs tem padrão 300. O onRun é chamado uma vez por execução com um WatchRunResult: { status: "succeeded", summary } ou { status: "failed", error: { code, message, causeCode?, hint? } }, em que causeCode nomeia o erro com código que a falha envolve e hint é o próximo passo que o errorHint fornece. O onReady é chamado uma vez, depois que as verificações de inicialização passam e logo antes da execução inicial, para que você possa anunciar a sessão antes da saída dessa execução. Se o onReady lançar um erro, o processo do watch é fechado e a Promise de watch é rejeitada com esse erro antes de qualquer execução começar. O SDK não faz nenhum log; o onRun é a única saída. concurrency, cache, onProgress, onLockWait e lockAcquireTimeoutMs são repassados a cada execução e se comportam exatamente como no translate. O locales restringe cada execução da sessão a esse subconjunto e é validado uma vez na inicialização, não a cada ciclo.

Retorna um WatchController com um único método, stop(), que fecha o processo do watch e aguarda a execução em andamento. Todo código da linha Lança é recusado na inicialização, antes de o processo do watch existir, então a Promise de watch é rejeitada em vez de retornar um controlador. Dois deles pesam mais em uma sessão do que em uma execução: um concurrency acima de 1 com uma configuração que define maxTokens sempre lança CONCURRENCY_BUDGET_CONFLICT, porque não existe um watch com simulação, e, com a 0.12.0 ou mais recente, um provedor que não pode ser instanciado, como um cuja variável da chave de API não está definida, lança PROVIDER_CONSTRUCTION_FAILED uma única vez em vez de fazer cada execução falhar. Toda falha depois da inicialização é exposta pelo onRun e a observação continua.

releaseHeldLocks

Exclui toda trava de escrita que o processo atual mantém, para um processo prestes a sair sem deixar suas execuções em andamento terminarem: a CLI a chama quando uma interrupção para o translate ou o import, e quando uma segunda interrupção força a parada do watch. As execuções que adquiriram essas travas perdem a proteção, então chame-a só imediatamente antes de o processo sair. Não recebe argumentos, e a Promise só é rejeitada, com um AggregateError que nomeia os caminhos das travas, quando uma trava mantida não pôde ser excluída, depois de tentar todas as travas. Uma trava que uma operação ainda em execução está adquirindo, ou tenta adquirir, enquanto a releaseHeldLocks está em execução, é recusada com RUN_CANCELLED e não deixa nenhum arquivo para trás; a releaseHeldLocks espera no máximo três segundos por uma aquisição dessas.

Assinatura
function releaseHeldLocks(): Promise<void>;

Retorna: void

Uma trava que sobrou mesmo assim, por um processo encerrado à força, não precisa dela: uma execução em espera na mesma máquina vê que o processo registrado não existe mais e recupera a trava por conta própria. Veja A trava de escrita.

Pseudolocalização

pseudolocalize

Gera um locale falso só a partir das strings de origem, de modo que cortes de layout e strings que nunca foram extraídas para tradução apareçam antes de existir qualquer chave de API. Todo valor é acentuado, expandido em cerca de um terço do seu comprimento traduzível e envolvido por marcadores de limite [ e ], enquanto os placeholders ficam intocados em toda sintaxe que os adaptadores reconhecem, inclusive ramos de plural e de select do ICU, tags de marcação e sequências de escape. Não instancia nenhum provedor, não lê nenhuma chave de API e não faz nenhuma requisição de rede.

Assinatura
function pseudolocalize(
  input: PseudolocalizeInput,
  deps?: PseudolocalizeDeps,
): Promise<PseudolocalizeResult>;

Propriedade

Tipo

Retorna: PseudolocalizeResult

Lança: PSEUDO_OUTPUT_CONFLICT, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, TARGET_UNWRITABLE

Exemplo: Gerar um pseudolocale

Todo valor gerado é submetido à mesma barreira de integridade que uma tradução de provedor precisa passar. Um que não passaria é copiado da origem literalmente e nomeado em copied, em vez de gravado de forma quebrada, de modo que a entrada continua presente e continua sendo renderizada.

O mode escolhe a transformação de PSEUDO_MODES: accented, o padrão, ou bidi, que em vez disso envolve cada palavra do texto traduzível em uma marca de direção da direita para a esquerda e uma substituição de direção, deixa placeholders, sintaxe ICU, marcação, dígitos e pontuação fora dele e não acentua nada. No modo bidi, o locale tem padrão ar-XB, um código que resolve para a direção da direita para a esquerda; veja verbatra pseudo para saber como as regras de plural do árabe desse código se combinam com as formas de plural da sua origem.

O locale tem padrão en-XA e o out tem padrão .verbatra-local/pseudo, que o verbatra init já adiciona ao .gitignore; o files.pattern configurado é expandido dentro dele, então o arquivo mantém o layout que o aplicativo espera. Um pseudolocale que nomeia um locale configurado, ou que cairia em um arquivo de locale configurado, é recusado com PSEUDO_OUTPUT_CONFLICT antes de qualquer leitura ou gravação, então não pode sobrescrever uma tradução real nem ocupar o lugar de uma; o mesmo vale para um out que é absoluto, sai de cwd ou nomeia o próprio cwd, como ., e, quando deps.fs implementa realpath, como o padrão faz, para um que, depois de resolvidos os links simbólicos, faz qualquer uma dessas coisas, cai no diretório de um arquivo de locale configurado ou cai em outro arquivo de que o projeto depende. Como o arquivo fica fora de files.pattern, o translate nunca gasta com ele e o check e o diff nunca o relatam como divergente.

Retorna um PseudolocalizeResult: o locale, o mode, o path absoluto, quantas entries foram processadas, quantas foram transformed, as chaves que foram copied e se algo foi written. A transformação é determinística, então uma segunda execução sobre uma origem inalterada não reescreve nada e informa written como falso. Para xliff e apple-xcstrings, cujos gravadores só aplicam alterações a um documento que já existe, a saída é copiada de novo da origem a cada gravação, então uma chave adicionada à origem depois da primeira execução ainda chega ao pseudolocale, e um XLIFF copiado tem o target-language reescrito para o pseudolocale.

Catálogos tipados

generateTypes

Declara o catálogo de origem de um projeto como TypeScript: uma união de todas as chaves que ele contém e, por chave, os argumentos que a mensagem interpola. Tipe uma função de tradução com base no resultado e uma chave escrita errada ou um argumento de interpolação ausente vira um erro de compilação em vez de uma falha de busca em tempo de execução. Não gasta nada: nenhum provedor é instanciado, nenhuma variável de ambiente de chave de API é lida e nenhuma requisição de rede é feita.

Assinatura
function generateTypes(
  input: GenerateTypesInput,
  deps?: GenerateTypesDeps,
): Promise<GenerateTypesResult>;

Propriedade

Tipo

Retorna: GenerateTypesResult

Lança: TYPES_OUTPUT_CONFLICT, TYPES_UNWRITABLE, UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID

Exemplo: Gerar um catálogo tipado

Ele lê um arquivo (o catálogo do locale de origem) e grava um arquivo (a declaração); um arquivo de locale de destino nunca é tocado. As chaves são exatamente o que o adaptador de formato já produziu, na ordem do documento, então duas execuções sobre um catálogo inalterado gravam bytes idênticos. Os argumentos vêm dos placeholders que o adaptador extraiu, exceto nos formatos de mensagem ICU (next-intl-json e arb), em que cada mensagem é lida com o mesmo parser ICU que o adaptador usa. Toda chave é emitida como um literal de string entre aspas, então uma chave com ponto, palavra reservada, dígito inicial, aspa, ou uma chave vazia, é declarada literalmente em vez de descartada ou dividida de novo, e uma chave que o adaptador relatou em excludedLeafPaths nunca é declarada.

O que ele se recusa a afirmar importa tanto quanto o que declara. Uma mensagem sem placeholders recebe um formato em que passar qualquer argumento é um erro de tipo; uma cujos placeholders nomeiam seus argumentos recebe um formato de objeto; uma cujos placeholders são numerados ou anônimos recebe uma tupla somente leitura. Um argumento ICU que só alguns ramos de select ou plural usam é declarado como membro opcional. Os tipos dos argumentos vêm apenas do que o catálogo registra: number para um argumento ICU number, plural ou selectordinal e para um formatador ou conversão numérica, Date | number para um argumento ICU date ou time e um formatador datetime do i18next, string para um argumento ICU select e uma conversão de string do printf, e um alias string | number em todo o resto, nunca um any permissivo. Uma interpolação sem escape do i18next ({{- name}}) é declarada pelo nome que vem depois do prefixo. Uma mensagem que o adaptador relatou como inválida, uma que parece nomear e numerar seus argumentos ao mesmo tempo e uma cujo índice de placeholder está fora do intervalo são declaradas com seus argumentos relatados em unresolved, em vez de declaradas em silêncio como se não recebessem nenhum. As formas de plural irmãs nunca são fundidas: cada uma é declarada separadamente, e as que o adaptador marcou como plural são listadas.

O out tem padrão DEFAULT_TYPES_PATH (verbatra-types.d.ts). Antes de qualquer leitura ou gravação, TYPES_OUTPUT_CONFLICT recusa um out que não nomeia nenhum arquivo (inclusive um que termina com um separador de caminho), é absoluto, sai de cwd com .., nomeia o próprio cwd (.) ou não termina em .ts, .mts ou .cts, e um que nomeia um arquivo de locale configurado, o arquivo de lock, o arquivo de procedência, o cache de memória de tradução, um arquivo em que o verbatra busca sua configuração, configPath, o arquivo de configuração de onde config foi carregado, ou glossaryPath, o arquivo de glossário que ele nomeia; os nomes são comparados sem diferenciar maiúsculas de minúsculas e, quando deps.fs implementa realpath, como o padrão faz, as mesmas verificações são executadas de novo no lugar onde o caminho cai depois de resolvidos os links simbólicos. Uma execução que gera o arquivo também se recusa, com o mesmo código, a substituir um arquivo existente que não começa com a linha de cabeçalho que o verbatra grava, e deixa esse arquivo intocado. A lista completa está na página verbatra types. Com check definido, nada é gravado, nada é recusado pelo conteúdo, e a execução só informa se o arquivo versionado ainda confere, que é o formato de que uma barreira de CI precisa.

Retorna um GenerateTypesResult: o path absoluto, o sourcePath a partir do qual foi montado, quantas keys foram declaradas e quantas delas recebem pelo menos um argumento que o verbatra conseguiu determinar (withArguments, que nunca conta uma chave unresolved), as chaves unresolved e as excluded e plural, se algo foi written, se o arquivo no disco estava stale quando a execução começou, se estava missing por completo (um arquivo ausente também é stale) e se esta foi uma execução check.

Editar no GitHub

Nesta página