Referência / SDK
Página traduzida automaticamente
Configuração e glossário
Pontos de entrada do SDK que carregam e validam a configuração do verbatra e editam o glossário, mais o que detecta se um diretório contém um projeto.
Carregar a configuração
loadConfig
Encontra, carrega e valida a configuração do projeto, retornando uma VerbatraConfig. configOverride
(valida um objeto em memória) tem prioridade sobre configPath (carrega um arquivo explícito), que tem prioridade sobre uma busca
a partir de cwd na ordem de busca. Um glossary dado como
caminho de arquivo é lido e validado aqui, então o código a jusante sempre vê um glossário em memória: um
mapa da versão 1 de termo de origem para tradução, ou uma definição da versão 2.
function loadConfig(
options?: LoadConfigOptions,
): Promise<VerbatraConfig>;Propriedade
Tipo
Retorna: VerbatraConfig
Lança: CONFIG_, CONFIG_
Exemplo: Uma configuração sem arquivo
Veja Arquivo de configuração para o schema. fs é a porta do sistema de arquivos pela qual
um arquivo de glossário é lido, como descrito em O ponto de injeção de dependências.
loadConfigWithMeta
O mesmo carregamento, mais a procedência: retorna { config, source, glossary }, em que source informa se
a configuração veio de um resultado de busca, de um caminho explícito ou de uma substituição em memória (com o
filepath absoluto quando há um), e glossary registra se o glossário estava ausente, inline ou
resolvido a partir de um arquivo. Use-o quando precisar exibir de onde a configuração veio.
function loadConfigWithMeta(
options?: LoadConfigOptions,
): Promise<LoadedConfig>;Propriedade
Tipo
Retorna: LoadedConfig
Lança: CONFIG_, CONFIG_
As duas aceitam fresh: true para avaliar de novo um arquivo de configuração JavaScript ou TypeScript em vez de reutilizar
o que um carregamento anterior no mesmo processo avaliou; um processo de longa duração que recarrega a configuração
depois de uma edição o define. As configurações JSON, YAML e package.json são sempre lidas do zero.
configCandidatePaths
Lista todo arquivo de onde loadConfigWithMeta poderia ler uma configuração com o mesmo { cwd?, configPath? }:
só o arquivo explícito quando configPath está definido; caso contrário, cada local de busca em cada diretório da
cadeia de busca, do mais próximo ao mais distante, exista ou não. Observe-os, por exemplo pelo horário de modificação, para notar uma configuração sendo criada, editada ou
removida sem carregá-la a cada requisição. O arquivo de glossário não é incluído; loadConfigWithMeta o nomeia em glossary.
function configCandidatePaths(
options?: ConfigCandidateOptions,
): readonly string[];Propriedade
Tipo
Retorna: readonly string[]
resolveProjectRoot
Retorna a raiz do projeto a partir da qual os fluxos resolvem caminhos relativos: o diretório do arquivo de
configuração encontrado, de modo que um processo iniciado em um subdiretório trabalhe sobre os próprios arquivos de locale, o arquivo de lock
e o .verbatra-local/ do projeto, ou cwd para uma configuração vinda de configPath. Um fluxo que recebe a configuração que
loadConfig ou loadConfigWithMeta retornou já assume essa raiz como padrão de seu cwd. Passe resolveProjectRoot(loaded.source, cwd) como
cwd quando copiar ou reconstruir a configuração, e para loadLockFile, loadProvenance e
runStatus, que não recebem configuração.
function resolveProjectRoot(
source: ConfigSource,
cwd: string,
): string;Retorna: string
Glossário
readGlossaryFile
Lê um glossário baseado em arquivo do zero a partir do disco e o retorna como um Glossary normalizado:
{ version, terms, doNotTranslate }, em que version é 1 para um mapa plano de termos e 2 para um
glossário por locale, e cada termo traz source, um target opcional,
targets, forbidden, caseSensitive e um note e um partOfSpeech opcionais. A sua entrada
glossary é o GlossaryProvenance vindo de loadConfigWithMeta, então o arquivo que ele lê é sempre
o que a configuração nomeia. Use-o em uma ferramenta de longa duração que mostra o
glossário como ele está agora, e não como estava no carregamento.
function readGlossaryFile(
input: GlossaryFileInput,
deps?: GlossaryFileDeps,
): Promise<Glossary>;Propriedade
Tipo
Retorna: Glossary
Lança: GLOSSARY_, CONFIG_
Lança GLOSSARY_ quando o glossário é inline ou está ausente, e CONFIG_ quando
o arquivo viola as regras do arquivo de glossário ou declara outra versão.
Até a 0.11, ele retornava o próprio mapa plano de termos.
updateGlossaryTerm
Adiciona, altera ou remove exatamente um termo em um glossário baseado em arquivo e retorna o glossário normalizado
como ele fica depois. translation é
o novo texto ou null para remover o termo. O resto do arquivo mantém a ordem das chaves e a
indentação, a gravação é atômica, e todo o ciclo de ler, modificar e gravar é mantido sob uma trava de glossário
válida para o projeto inteiro, então duas edições concorrentes são serializadas em vez de intercaladas.
function updateGlossaryTerm(
input: UpdateGlossaryTermInput,
deps?: GlossaryFileDeps,
): Promise<Glossary>;Propriedade
Tipo
Retorna: Glossary
Lança: GLOSSARY_, CONFIG_, LOCK_, LOCK_, RUN_, GLOSSARY_
Ele aceita também locale (então translation é a tradução própria desse locale e null remove só ela),
forbidden (as traduções que locale nunca deve usar; null ou [] as remove), note,
partOfSpeech (cada um com null para remover), caseSensitive e doNotTranslate (true adiciona o termo
aos termos mantidos sem tradução, false o remove; não pode ser combinado com os campos do termo).
Um arquivo da versão 1 continua na versão 1 enquanto uma edição só define ou remove uma tradução para todos os
locales; qualquer outra edição o reescreve como versão 2, com cada termo existente mantendo sua tradução como
target. translation: null sem locale remove só a tradução compartilhada; o próprio termo é removido quando não lhe sobra nenhuma tradução nem tradução proibida, o que, para um termo da versão 1, acontece na hora.
Com sourceLocale, um termo que difere de um já guardado só pelas maiúsculas e minúsculas (nenhum dos dois com caseSensitive) atualiza o termo guardado, mantendo a grafia dele; sem ele, só uma correspondência exata atualiza. Um glossário inline é recusado com
GLOSSARY_ em vez de convertido. Um term ausente, um campo em branco, uma edição que não define nenhum campo ou mistura doNotTranslate
com os campos do termo, traduções proibidas sem um locale, um locale inválido, uma edição que deixaria
um glossário inválido e uma edição cujo resultado excederia o limite de 1 MiB do glossário são
recusados com CONFIG_; uma gravação que falha, inclusive a da trava de glossário, é GLOSSARY_, com o erro do sistema de arquivos como cause. Uma edição que deixa o
glossário como já está tem êxito e não grava nada.
Ele aceita também lockAcquireTimeoutMs, que limita a espera pela trava de glossário antes de a chamada falhar com LOCK_ (dez minutos por padrão); um limite inválido falha com LOCK_ antes de qualquer coisa ser lida.
glossaryForLocale
Resolve a parte de um glossário que se aplica a um locale de destino:
glossaryForLocale(config.glossary, "de") retorna { terms, doNotTranslate }, cada termo com o
target do locale (a entrada própria dele, depois a do idioma-base, depois a compartilhada), suas
traduções forbidden, caseSensitive e seu note e partOfSpeech, ou undefined quando nada no
glossário se aplica ali. É exatamente o que uma requisição de tradução para esse locale carrega como
TranslateRequest.glossary, e o que as verificações de revisão e a impressão digital do cache desse locale
enxergam.
function glossaryForLocale(
glossary: GlossaryInput | Glossary | undefined,
locale: string,
): LocaleGlossary | undefined;Retorna: LocaleGlossary | undefined
glossaryHits
glossaryHits({ glossary, locale, sourceLocale, source }) retorna as entradas do glossário que se aplicam
a um texto de origem em um locale de destino, como { terms, doNotTranslate } no formato que
glossaryForLocale retorna: todo termo cuja origem ocorre em source como um termo inteiro, com a
tradução e as traduções proibidas a que esse locale está sujeito, e todo termo a manter sem tradução
que ocorre nele. Um termo corresponde com ou sem diferenciar maiúsculas de minúsculas, conforme ele declara, com a conversão de maiúsculas e minúsculas feita segundo as regras do locale
sourceLocale. Ele usa a mesma correspondência que uma execução de translate aplica ao sinalizar um termo do glossário
não usado, e não lê nada.
function glossaryHits(
input: GlossaryHitsInput,
): LocaleGlossary;Propriedade
Tipo
Retorna: LocaleGlossary
glossaryDraftCheck
glossaryDraftCheck({ glossary, locale, sourceLocale, source, draft }) confere um rascunho de tradução
contra as entradas do glossário que glossaryHits encontra no texto de origem, antes de você gravá-lo. Cada
termo volta com targetUsed (se o rascunho traz a tradução exigida, ausente para um
termo que só proíbe traduções) e forbiddenUsed (as traduções proibidas que o rascunho usa
e a origem não), e cada termo a manter sem tradução volta com kept. Estas são as regras que uma execução de
translate usa para sinalizar GLOSSARY_ e GLOSSARY_. Ele não lê nada.
function glossaryDraftCheck(
input: GlossaryDraftCheckInput,
): GlossaryDraftCheck;Propriedade
Tipo
Retorna: GlossaryDraftCheck
normalizeGlossary
Converte um glossário em qualquer um dos formatos, um mapa plano da versão 1 ou uma definição da versão 2, no
Glossary normalizado que readGlossaryFile retorna, com todo valor padrão preenchido. Use-o para mostrar
um glossário inline do mesmo jeito que um baseado em arquivo. Ele não valida de novo; o loadConfig já validou.
function normalizeGlossary(
glossary: GlossaryInput | Glossary,
): Glossary;Retorna: Glossary
sharedGlossaryTranslations
Projeta um Glossary normalizado em um mapa plano que associa cada termo com target compartilhado a essa
tradução, na ordem do glossário. As traduções por locale, as traduções proibidas e os termos que não devem ser traduzidos
ficam de fora, então use-o apenas onde um consumidor não consegue mostrar nada além de um mapa plano de termos. Um termo
chamado _ continua sendo uma chave própria.
function sharedGlossaryTranslations(
glossary: Glossary,
): Readonly<Record<string, string>>;Propriedade
Tipo
Retorna: Readonly<Record<string, string>>
redactGlossary
Passa cada termo de origem, tradução, tradução proibida, nota, classe gramatical e
termo que não deve ser traduzido de um Glossary normalizado por redact, e retorna { glossary, redactedTerms }, em que redactedTerms nomeia cada termo
que teve um valor substituído, com um termo de origem ocultado aparecendo como [REDACTED], para que a lista nunca
repita um segredo. O servidor
MCP e o Studio o usam antes de um glossário sair do processo.
function redactGlossary(glossary: Glossary): RedactedGlossary;Propriedade
Tipo
Retorna: RedactedGlossary
readCurrentGlossary
Lê o glossário que uma configuração carregada nomeia, como ele está agora: readCurrentGlossary({ loaded }),
em que loaded é o que loadConfigWithMeta retorna. Um glossário baseado em arquivo é lido do zero a partir do disco,
um inline vem da configuração, e, de qualquer modo, o resultado é o Glossary normalizado, ou
undefined quando a configuração não declara nenhum. Para ver a que um locale de destino está sujeito, passe o resultado
a glossaryForLocale.
function readCurrentGlossary(
input: ReadCurrentGlossaryInput,
deps?: GlossaryFileDeps,
): Promise<Glossary | undefined>;Propriedade
Tipo
Retorna: Glossary | undefined
Lança: CONFIG_
editConfiguredGlossaryTerm
updateGlossaryTerm para uma ferramenta que mantém uma configuração carregada: recebe loaded no lugar de glossary,
com os mesmos campos de edição, trata um campo deixado como undefined como ausente e confere antes locale contra os
locales de destino configurados, falhando com UNKNOWN_ e sem gravar nada quando ele não é
um deles. O servidor MCP e o Studio gravam o glossário por ele.
function editConfiguredGlossaryTerm(
input: EditConfiguredGlossaryTermInput,
deps?: GlossaryFileDeps,
): Promise<Glossary>;Propriedade
Tipo
Retorna: Glossary
Lança: UNKNOWN_, GLOSSARY_, CONFIG_, LOCK_, LOCK_, RUN_, GLOSSARY_
Limites de tamanho
setKeyLengthLimit
Define, altera ou remove o limite de tamanho de uma chave no verbatra.limits.json, o arquivo versionado ao lado do arquivo de lock que guarda os limites que o maxLength da configuração não cobre. A chave precisa existir na origem, um limite para uma chave que o maxLength da configuração define é recusado, e null remove a entrada do arquivo, inclusive a de uma chave que saiu da origem ou que a configuração define. O ciclo de ler, modificar e gravar é executado sob uma trava de limites válida para o projeto inteiro e o arquivo é substituído de forma atômica, então chamadas concorrentes de um processo ou de vários não perdem nenhuma atualização. Uma chamada que não muda nada não grava nada, e um arquivo que não pode ser lido como arquivo de limites nunca é sobrescrito.
function setKeyLengthLimit(
input: SetKeyLengthLimitInput,
deps?: SetKeyLengthLimitDeps,
): Promise<SetKeyLengthLimitResult>;Propriedade
Tipo
Retorna: SetKeyLengthLimitResult
Lança: LENGTH_, LOCK_, UNKNOWN_, LOCALE_, LOCALE_, SOURCE_, SOURCE_, UNKNOWN_, LOCK_, RUN_, LIMITS_, LIMITS_
Criação, detecção e modo somente humano
defineConfig
Um auxiliar de identidade para um verbatra.config.ts tipado: retorna o argumento sem alterá-lo, para a inferência de tipos
e o autocompletar do editor, inclusive os IDs de modelo conhecidos do provedor selecionado (só na criação;
em tempo de execução qualquer string não vazia passa). Todo provedor, exceto opencode, openai-compatible,
libretranslate e none, também ganha uma sobrecarga que recebe AuthoringConfigFor<"<id>">, como
AuthoringConfigFor<"anthropic">, restringindo o bloco provider às opções desse provedor; esses
quatro usam o fallback AuthoringConfig abaixo.
function defineConfig(config: AuthoringConfigFor<"anthropic">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"openai">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"gemini">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"deepl">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfigFor<"google-translate">): VerbatraConfigInput;
function defineConfig(config: AuthoringConfig): VerbatraConfigInput;Retorna: VerbatraConfigInput
Exemplo: Adicionar um arquivo de origem e uma configuração
verbatraConfigSchema
O schema zod com o qual loadConfig valida, exportado para que suas próprias ferramentas validem um objeto de
configuração do mesmo jeito que o SDK. As opções desconhecidas no nível superior são rejeitadas, para que um segredo esquecido não possa
se esconder na configuração, exceto $schema: uma string opcional, ignorada em tempo de execução, que permite a uma configuração JSON ou
YAML apontar um editor para o @verbatra/sdk/config-schema.json do pacote.
const verbatraConfigSchema: z.ZodObject<{ ... }, z.core.$strict>;Seu bloco rates é um RateCard, a tabela de preços que transforma uma estimativa (veja Estimar o custo antes de uma execução) em dinheiro:
Propriedade
Tipo
scaffoldingMetadata
Metadados somente leitura de que o comando init da CLI deriva suas perguntas: providerEnv (o id do provedor para
a variável de ambiente da qual a chave de API dele é lida), scaffoldModels (um modelo de geração padrão por provedor
de LLM), providerTokenLimitKeys (o nome da opção sob o qual cada provedor de LLM recebe seu limite de tokens de saída)
e supportedFormats (o conjunto fechado de ids de formato). Leia o nome da opção do limite de tokens em
providerTokenLimitKeys em vez de supor um, já que os nomes diferem (Provedores);
o DeepL e o Google Cloud Translation não têm entrada porque não recebem limite de tokens. O tipo ScaffoldableProviderId é
Exclude<ProviderId, "openai-compatible" | "libretranslate" | "none">: todo provedor que não precisa
de nada além do seu id. openai-compatible e libretranslate precisam cada um de um baseUrl que só você pode
fornecer e não têm variável de ambiente obrigatória, e none não chama provedor nenhum.
const scaffoldingMetadata: {
readonly providerEnv: { ... };
readonly scaffoldModels: { ... };
readonly providerTokenLimitKeys: { ... };
readonly supportedFormats: readonly [...];
readonly humanOnlyProviderId: "none";
readonly openAiCompatibleKeyEnv: "OPENAI_COMPATIBLE_API_KEY";
readonly libreTranslateKeyEnv: "LIBRETRANSLATE_API_KEY";
readonly configSearchPlaces: readonly string[];
};scaffoldingMetadata.humanOnlyProviderId é "none", o id que desativa a tradução automática. Ele não tem entrada em providerEnv, já que não lê nenhuma chave de API.
scaffoldingMetadata.libreTranslateKeyEnv é "LIBRETRANSLATE_, a variável da qual um provedor libretranslate lê a sua chave de API. Ela é opcional: um servidor iniciado sem --api-keys não precisa de nenhuma, então um gerador deve deixá-la sem definir.
scaffoldingMetadata.openAiCompatibleKeyEnv é "OPENAI_, a variável que um provedor openai-compatible lê quando suas opções não nomeiam um apiKeyEnvVar. scaffoldingMetadata.configSearchPlaces lista todo nome de arquivo que loadConfig procura como configuração, na ordem em que os confere; um gerador que grava verbatra.config.ts deve recusar quando outro deles já existe, já que o primeiro encontrado prevalece.
detectProject
Detecta o formato e o layout dos arquivos de locale de um projeto a partir dos seus arquivos, do jeito que o verbatra init faz antes de gravar uma configuração. Ele não grava nada e não chama nenhum provedor. Varre o diretório (ignorando diretórios ocultos, node_ e a saída de build, dentro de uma profundidade e de um número de entradas limitados) em busca de arquivos que um adaptador registrado assume, encontra em cada um o segmento de caminho que contém o código de um locale e mantém o padrão de arquivo que cobre mais locales. O formato é aquele cujo adaptador canHandle assume todo arquivo correspondente, dado o conteúdo dele; para o JSON, em que todo adaptador JSON assume esses arquivos, uma única biblioteca i18n correspondente no package.json decide.
function detectProject(
input?: DetectProjectInput,
deps?: DetectProjectDeps,
): Promise<ProjectDetection>;Propriedade
Tipo
Retorna: ProjectDetection
import { detectProject } from "@verbatra/sdk";
const detection = await detectProject({ cwd: "/path/to/project" });
if (detection.ambiguities.length > 0) {
// several formats or file patterns fit: choose one of detection.ambiguities[0].candidates
}
const format = detection.format?.id; // for example "yaml"
const pattern = detection.layout?.pattern; // for example "config/locales/{locale}.yml"O resultado traz format (com from: input, files ou dependencies), layout (pattern, localeStyle, locales, sourceLocale, files, unqualifiedSourceFile), ambiguities (cada uma com um subject de format ou layout e seus candidates), uma confidence de high, medium, low ou none, e reasons, uma frase por decisão. Os empates são relatados como ambiguidades, nunca adivinhados. As entradas opcionais format, pattern e sourceLocale restringem a busca, e deps.fs e deps.adapterRegistry trocam o sistema de arquivos e os adaptadores, então os arquivos de um adaptador de terceiros também são detectados. Um arquivo ausente, ilegível ou malformado nunca lança erro; ele só deixa o relatório menos completo. layout.unqualifiedSourceFile nomeia um arquivo ao lado do layout que guarda strings sem nome de locale, como messages.properties ou um template .pot do gettext; o locale de origem fica então em aberto, já que a origem é lida do arquivo que o padrão nomeia para ela.
isMachineTranslationEnabled
Retorna false exatamente quando a configuração define provider: { id: "none" }, o modo somente humano (veja Trabalhar sem tradução automática) em que nenhum provedor é jamais instanciado e nenhuma chave de API é lida. Uma interface que oferece ações que gastam com provedor o lê para omiti-las por completo, que é como o Studio e o servidor MCP deixam de oferecer gastos mesmo com --allow-spend.
function isMachineTranslationEnabled(
config: Pick<VerbatraConfig, "provider">,
): boolean;Retorna: boolean
assertMachineTranslationEnabled
Recebe a configuração e uma frase curta que nomeia a ação, e lança SdkError MACHINE_ sob provider: { id: "none" }. Chame-o antes de envolver translate em uma ação explícita de “traduzir tudo o que está pendente”, para que a ação falhe do mesmo jeito que retranslateEntry em vez de preencher em silêncio só a partir da memória de tradução.
function assertMachineTranslationEnabled(
config: Pick<VerbatraConfig, "provider">,
action: string,
): void;Retorna: void
Lança: MACHINE_
assertTargetLocale
Recebe a configuração e um locale, e lança SdkError UNKNOWN_ quando o locale não é um dos targetLocales configurados, com a mesma mensagem que toda função do SDK que recebe um filtro locales usa. Chame-o em uma interface que recebe um único locale próprio, como faz o glossary.get do servidor MCP, para que um locale errado falhe exatamente como no SDK.
function assertTargetLocale(
config: Pick<VerbatraConfig, "targetLocales">,
locale: string,
): void;Retorna: void
Lança: UNKNOWN_