Referência / Configuração
Página traduzida automaticamente
Arquivo de configuração
Cada opção de configuração com seu tipo, padrão e a versão que a adicionou, além de onde o arquivo pode ficar e como uma configuração inválida falha.
O verbatra lê um único objeto de configuração sem segredos e o valida antes de qualquer trabalho. Nenhuma chave de API é lida dele (veja As chaves de API vêm do ambiente), então a configuração é segura para versionar.
Uma configuração mínima
import { defineConfig } from "@verbatra/cli";
export default defineConfig({
// Locales and files: required
sourceLocale: "en",
targetLocales: ["de", "fr"],
format: "i18next-json",
files: {
// {locale} is the only token
pattern: "locales/{locale}.json",
},
// Provider: required; the API key comes from the environment, never from here
provider: {
id: "gemini",
options: {
// example model id; use your provider's current one
model: "gemini-2.5-flash",
maxOutputTokens: 4096,
},
},
// Optional groups, each off or at its default until you add it:
// tone: "informal",
// glossary: "glossary.json",
// network: { policy: "local-only" },
// sensitiveData: { mode: "warn" },
// maxTokens: 200000,
// budgetBehavior: "stop",
});Veja locales e arquivos, provider, glossary, network, dados sensíveis, orçamento, rates e extract.
defineConfig só tipa seu argumento: options.model completa com os ids de modelo do provedor, embora qualquer string não vazia seja aceita em tempo de execução.
Todas as opções
Opções desconhecidas são rejeitadas em todos os níveis, exceto $schema e mapas cujas chaves você mesmo nomeia, como maxLength, rates.table, localeMap e um glossary inline, então uma chave de API não pode ficar na configuração.
| Opção | Tipo | Padrão | Desde | Efeito |
|---|---|---|---|---|
$schema | string | nenhum | 0.9.0 | Aponta um editor para o JSON Schema (veja Validação no editor); ignorado em tempo de execução. |
sourceLocale | código de locale | obrigatório | 0.1.0 | O locale em que suas strings de origem são escritas. |
targetLocales | array de códigos de locale | obrigatório | 0.1.0 | Pelo menos um; nunca sourceLocale, nunca dois iguais sem diferenciar maiúsculas de minúsculas. |
format | id de formato | obrigatório | 0.1.0 | O formato dos seus arquivos de locale, ou um id custom: para um adaptador externo (veja Formatos e Escrever um adaptador de formato personalizado). |
files.pattern | string | obrigatório | 0.1.0 | O caminho de cada arquivo de locale, com um placeholder {locale}. |
files.localeStyle | "literal", "posix", "android" | "literal" | 0.7.0 | Como {locale} é escrito no caminho. |
provider.id | id de provedor | obrigatório | 0.1.0 | O provedor de tradução, ou none para nenhuma tradução automática. |
provider.options | objeto | obrigatório, exceto para none | 0.1.0 | As opções próprias do provedor (veja Provedores). |
glossary | objeto ou caminho de arquivo | nenhum | 0.1.0 | Traduções fixas, traduções proibidas e termos que não devem ser traduzidos. |
tone | "formal", "informal", "neutral" ou um mapa | nenhum | 0.1.0 | O tom a usar na tradução, aplicado por provedor (veja Tom e glossário entre provedores). Um mapa define um tom por locale de destino, mais default. novo |
prune | booleano | false | 0.3.0 | Remove as chaves órfãs dos arquivos de destino e do arquivo de lock; translate --prune a sobrepõe. |
generatePlurals | booleano | false | 0.3.0 | Sintetiza as formas de plural do CLDR de que um idioma de destino precisa. |
fuzzyCache.enabled | booleano | obrigatório no bloco | 0.11.0 | Reutiliza a tradução de uma origem ligeiramente alterada. |
fuzzyCache.threshold | número, de 0.5 a 1 | 0.9 | 0.11.0 | O quanto a origem antiga e a nova precisam se parecer. |
humanEdits | "protect", "suggest", "overwrite" | "protect" | 0.12.0 | O que uma execução faz com uma chave obsoleta que uma pessoa escreveu. |
pinnedKeys | array de strings | nenhum | 0.12.0 | Padrões de chave (curinga *) que nenhuma gravação feita por máquina toca. |
network.policy | "any", "local-only", "allowlist" | "any" | 0.12.0 | A quais hosts um provedor pode se conectar (veja Restringir o acesso à rede). |
network.allowedHosts | array de strings | nenhum; obrigatório para "allowlist" | 0.12.0 | Hosts permitidos adicionais: nomes, curingas *.suffix, IPs ou intervalos CIDR. |
sensitiveData.mode | "off", "warn", "block", "redact" | obrigatório no bloco; "off" sem o bloco | 0.12.0 | O que uma execução faz com conteúdo sensível antes de enviar (veja Proteção de conteúdo sensível). |
sensitiveData.detectors | array de ids de detector | secret, email, iban, credit-card | 0.12.0 | Detectores a executar; phone, ip e private-host precisam ser ativados explicitamente. |
sensitiveData.patterns | array de strings | nenhum | 0.12.0 | Expressões regulares para seus próprios termos, como nomes de código. |
sensitiveData.allow | array de strings | nenhum | 0.12.0 | Trechos encontrados que nunca são relatados; * é um curinga e maiúsculas e minúsculas são ignoradas. |
maxBatchSize | inteiro positivo | 50 | 0.3.0 | O máximo de entradas por requisição ao provedor. |
maxLength | mapa de chave para inteiro positivo | nenhum | 0.11.0 | Limites de tamanho por chave, em clusters de grafemas. |
maxTokens | inteiro positivo | nenhum | 0.5.0 | Um orçamento de tokens para a execução inteira. |
budgetBehavior | "warn", "stop" | "warn" | 0.5.0 | Se atingir maxTokens apenas avisa ou interrompe o envio. |
rates.asOf | data YYYY-MM-DD | obrigatório no bloco | 0.11.0 | A data em que você leu os preços. |
rates.currency | três letras maiúsculas | obrigatório no bloco | 0.11.0 | A moeda de todos os preços, como USD. |
rates.table | mapa de chave de preço para preço | obrigatório no bloco | 0.11.0 | Preços por chave de preço (veja rates). |
extract.framework | "i18next" | obrigatório no bloco | 0.11.0 | Quais pontos de chamada a varredura do código-fonte procura. |
extract.roots | array de strings | obrigatório no bloco | 0.11.0 | Os diretórios a varrer, pelo menos um. |
extract.exclude | array de strings | nenhum | 0.11.0 | Nomes de diretório extras a ignorar. |
extract.literals.ignore | array de strings | nenhum | 0.11.0 | Textos exatos que o doctor --literals exclui. |
extract.unused.ignore | array de strings | nenhum | 0.11.0 | Chaves ou padrões * que o diff --unused nunca relata. |
Locales e arquivos
-
files.patternprecisa conter{locale}, seu único placeholder, e é resolvido a partir da raiz do projeto:locales/{locale}.jsonviralocales/de.json. É um caminho literal, nunca um glob, então uma configuração aponta para um arquivo por locale; oapple-xcstringsresolve todos os locales para um único catálogo (veja Layouts de namespace e Xcode String Catalogs (.xcstrings)). -
files.localeStyledecide no que o placeholder se expande:literalgrava o código como configurado, como a maioria dos layouts precisa.posixtroca-por_para o gettext e para omessages_do Java ({locale}.properties pt-BRvirapt_); uma variante comoBR de-1996não tem grafia posix. Ogettext-poescreve os sistemas de escrita do jeito do gettext (próxima seção).androidse expande para um diretório de recursos, escrito comores/{locale}/strings.xml:valuespara a origem, depoisvalues-de,values-pt-rBR,values-b+zh+Hans.
Um estilo recusa um locale que não consegue escrever.
Nomes de locale do gettext
Com format: "gettext-po" e localeStyle: "posix", os arquivos recebem nomes do gettext (language_) enquanto a configuração mantém códigos BCP 47:
| Código na configuração | Nome do arquivo |
|---|---|
pt-BR | pt_ |
es-419 | es_ |
sr-Latn | sr@latin |
sr-Latn-RS | sr_ |
uz-Cyrl | uz@cyrillic |
ks-Deva-IN | ks_ |
zh-Hant-TW | zh_ |
sr-Cyrl-RS | sr_ |
Um sistema de escrita que o idioma e a região já implicam é omitido, então zh-TW e zh-Hant-TW juntos falham com LOCALE_; um sistema de escrita sem modificador do gettext, como zh-Hant sozinho, falha com LOCALE_. O verbatra init lê esses nomes de volta. Os outros formatos mantêm a grafia ICU (sr_).
Códigos de locale
Todo código de locale precisa ser uma tag que o Intl.getCanonicalLocales aceita, com uma subtag de idioma de duas ou três letras, ou o carregamento falha com CONFIG_: pt_ (escreva pt-BR com localeStyle: "posix") e german são rejeitados. Um código válido não canônico, como zh-hant-tw ou o iw, já descontinuado, funciona como escrito.
provider
provider.id seleciona um dos provedores, ou none, cujas options podem ser omitidas e, caso contrário, precisam ser {} (veja Trabalhar sem tradução automática). Todos os outros provedores aceitam options.localeMap e options.requestTimeoutMs (veja Códigos de locale enviados ao provedor); com a 0.12.0 ou mais recente, uma opção fora do lugar sob provider, como localeMap, falha com CONFIG_.
glossary
Termos traduzidos de um jeito fixo, inline ou como um caminho para um arquivo JSON com o mesmo formato (nunca mesclados). A versão 1 mapeia cada termo de origem a uma tradução para todos os locales:
export default defineConfig({
// ...
glossary: {
"Sign in": "Anmelden",
},
// or: glossary: "glossary.json",
});Um caminho relativo é resolvido a partir do diretório do arquivo de configuração; o arquivo precisa ser UTF-8 e ter no máximo 1 MiB, e é lido uma vez no carregamento. Um arquivo ausente, um JSON inválido ou um formato inválido falha com CONFIG_, nomeando o caminho e, na versão 2, o campo. Coloque um termo _ em um arquivo; um literal JavaScript o transforma no protótipo.
Glossário por locale (versão 2)
A versão 2 acrescenta traduções por locale, traduções proibidas e termos a manter como estão escritos:
{
"version": 2,
"terms": [
{
"source": "Dashboard",
"targets": { "de": "Übersicht", "fr": "Tableau de bord" },
"forbidden": { "de": ["Instrumententafel"] },
"note": "The start page after sign-in",
"partOfSpeech": "noun"
},
{ "source": "Sign in", "target": "Anmelden", "caseSensitive": true }
],
"doNotTranslate": ["verbatra", { "term": "Acme", "caseSensitive": false }]
}| Campo | Significado |
|---|---|
version | Sempre 2; qualquer outro número falha. |
terms[].source | O termo de origem; cada termo aparece uma vez. |
terms[].target | A tradução para todo locale sem uma entrada própria em targets. |
terms[].targets | Traduções por locale. Um locale usa sua própria entrada, depois a do seu idioma base (de cobre de-AT), depois target; os códigos são comparados de forma canônica, sem diferenciar maiúsculas de minúsculas. |
terms[].forbidden | Traduções que um locale nunca deve usar; um locale regional também obedece à lista do seu idioma base. |
terms[].caseSensitive | Compara o termo, as traduções e as traduções proibidas diferenciando maiúsculas de minúsculas. Padrão false. |
terms[].note, terms[].partOfSpeech | Contexto em texto livre, enviado a um provedor de LLM como dados. |
doNotTranslate | Termos copiados sem tradução. Uma string simples mantém as maiúsculas e minúsculas; { "term", "caseSensitive": false } pode alterá-las. |
Cada termo precisa de um target, de uma entrada em targets ou de uma lista forbidden; ele não pode proibir a própria tradução, nomear um locale duas vezes nem aparecer em doNotTranslate. Nenhum texto pode ficar em branco; um termo tem no máximo 200 caracteres, uma tradução ou tradução proibida 2.000, uma note 500 e um partOfSpeech 50. A impressão digital do cache de um locale cobre apenas os termos dele (veja O cache de tradução). Um arquivo da versão 1 mantém sua impressão digital; o updateGlossaryTerm o reescreve como versão 2 apenas para uma edição que a versão 1 não consegue expressar.
O Studio edita só a forma de arquivo, um termo por vez (veja Revisar no Studio). Tom e glossário entre provedores diz quais provedores o aplicam; toda saída é verificada depois (veja Segurança da tradução).
generatePlurals
Quando é true, o verbatra sintetiza as formas de plural do CLDR de que um destino precisa mas a origem não tem, como few e many em polonês, e as chaves ordinais (<key>_) pelas regras ordinais do CLDR. Só o i18next-json com um provedor de LLM aceita isso; qualquer outro caso, e um locale sem regras CLDR, recebe o alerta de plural (os ordinais supõem other; veja Plurais). Não há flag da CLI; o translate() do SDK aceita uma substituição por execução.
fuzzyCache
fuzzyCache: { enabled: true } permite que uma origem alterada reutilize a tradução da sua forma anterior quando a semelhança entre as duas é de pelo menos threshold, sempre sinalizada com FUZZY_ (veja Reutilização aproximada); --no-cache a ignora.
humanEdits e pinnedKeys
humanEdits cobre uma chave obsoleta cujo valor uma pessoa escreveu (procedência human, import ou external; veja Procedência: quem escreveu cada valor); uma chave que corresponde a pinnedKeys (como ["legal.*", "brand.name"]) nunca é gravada por máquina, seja qual for o valor de humanEdits. * corresponde a qualquer sequência de caracteres, pontos inclusive, e a correspondência diferencia maiúsculas de minúsculas. O que cada modo faz está em Manter traduções humanas.
network
Veja Restringir o acesso à rede.
network: { policy: "local-only", allowedHosts: ["gpu.lan"] }maxBatchSize
As entradas ausentes e alteradas saem em sublotes sequenciais de no máximo esse tamanho (veja Envio em lotes). Nenhuma flag da CLI o substitui.
maxLength
Limites de tamanho por chave, para strings sob uma restrição de layout:
maxLength: {
"nav.dashboard": 18,
"cta.submit": 12,
}- Aqui ou em
verbatra.limits.json. As chaves correspondem literalmente, nunca como globs; uma chave que não está definida em nenhum dos dois nunca é medida.setKeyLengthLimitaceita só chaves de origem, então o Studio não pode limitar uma forma de plural gerada; uma entrada escrita manualmente para a própria chave se aplica. O arquivo ao lado do arquivo de lock aceita{ "version": 1, "maxLength": { ... } }, a configuração prevalece, chave a chave, e osetKeyLengthLimito grava. - Clusters de grafemas. O tamanho conta caracteres percebidos, espaços em branco inclusive: um emoji, uma letra acentuada ou um caractere CJK conta como um. O limite é inclusivo.
- Quando. Todo valor que o
translateproduz para a chave, reutilizações do cache inclusive; uma chave em dia só quandocheck --qa,check --fileouexport --include-unchangeda lê. - Apenas indicativo. Um estouro ainda é gravado e registrado no arquivo de lock, e sinalizado com
MAX_para revisão.LENGTH_ EXCEEDED
maxTokens e budgetBehavior
maxTokens é um orçamento da execução inteira: tokens de entrada mais tokens de saída em toda chamada ao provedor (tradução e geração de plural) e em todo locale de destino. O translate --max-tokens pode apertá-lo em uma execução, nunca afrouxá-lo, e sempre como um "stop" rígido.
budgetBehavior decide o que acontece então:
"warn", o padrão, conta o gasto e sinaliza o estouro, mas continua."stop"faz dele um teto para todo provedor. Antes de cada requisição, a execução projeta o custo como a estimativa prévia (veja Estimar o custo antes de uma execução) e recusa uma que passaria demaxTokens. As chaves dessa requisição e todas as ainda não tentadas (o restante do locale e todo locale posterior, cujo diff e relato de órfãs ainda são executados) ficam retidas, mantêm o hash anterior no arquivo de lock e são tentadas de novo na próxima execução.
Com "stop":
- Depois de cada requisição, o total é conferido com o uso informado pelo provedor, então uma execução pode terminar um pouco acima de
maxTokens(veja obudgetem A anatomia do RunSummary). Provedores de tradução automática não informam tokens e são orçados pela projeção. - Uma requisição que falhou ou foi truncada é cobrada por inteiro.
- A projeção soma uma margem fixa de prompt de LLM, inclusive para provedores de tradução automática, e cobre um lote inteiro, então um
maxTokensabaixo da projeção de um lote o recusa em toda execução. - Um locale com chaves retidas fica
partial, oufailedse nenhuma chave foi gravada, e ambos terminam com código1. Com"warn", o código de saída nunca muda.
O orçamento limita uma execução de translate, nunca a retradução de uma única entrada; o watch começa um novo a cada execução. Um orçamento exclui --concurrency acima de 1 em uma execução real; uma simulação está isenta.
Dois maxTokens diferentes
O maxTokens de nível superior é este orçamento da execução inteira; o provider.options.maxTokens do Anthropic, sem relação com ele, limita uma única resposta (veja Anthropic).
rates
Lido por translate --estimate e, para cada execução registrada, para precificar o custo do histórico dela.
rates: {
asOf: "2026-01-15",
currency: "USD",
table: {
// placeholders: copy the current rates from each provider's pricing page
"gemini/gemini-2.5-flash": { inputPerMillionTokens: 1, outputPerMillionTokens: 2 },
deepl: { perMillionCharacters: 1 },
},
}Uma chave de table é provider/model, ou o id simples para um provedor sem modelo (deepl, google-translate). Uma entrada é cobrada por tokens (inputPerMillionTokens, outputPerMillionTokens) ou por caracteres (perMillionCharacters), nunca pelos dois, e um preço negativo, um preço acima de 1.000.000.000 por milhão ou a unidade errada é recusado. openai-compatible e libretranslate não enviam fatura, então a quantidade deles é informada sem preço.
extract
Lido apenas por extract, doctor --literals e diff --unused.
extract: {
framework: "i18next",
roots: ["src", "app"],
exclude: ["generated"],
literals: { ignore: ["Acme Inc."] },
unused: { ignore: ["emails.*"] },
}frameworkprecisa nomear um que tenha um extrator (veja O que ele encontra); qualquer outro é rejeitado.rootssão resolvidos a partir da raiz do projeto;excludeacrescenta nomes de diretório (não caminhos), comparados em qualquer ponto sob uma raiz, ao conjunto sempre ignorado (veja Limites da varredura).literals.ignorecorresponde ao texto inteiro de um literal, com espaços em branco colapsados e referências decodificadas (veja Literais não traduzidos).unused.ignorecorresponde à chave decodificada (vejadiff --unused).
Ordem de busca
O verbatra busca para cima a partir do diretório de trabalho e usa a primeira correspondência, parando no diretório mais próximo que contém .git, senão no seu diretório pessoal (ou no diretório de trabalho quando o diretório pessoal não está acima dele), então nunca pega uma configuração acima do seu repositório:
package.json(uma propriedade"verbatra").verbatrarc.verbatrarc.json.verbatrarc.yaml.verbatrarc.yml.verbatrarc.js.verbatrarc.cjs.verbatrarc.tsverbatra.config.jsverbatra.config.cjsverbatra.config.ts
--config <path> carrega, em vez disso, um único arquivo, relativo ao diretório de trabalho; a precedência do SDK está em loadConfig.
Validação no editor
O @verbatra/sdk traz um JSON Schema gerado a partir do seu schema zod, também servido em uma URL estável para qualquer instalação, npx, um monorepo com hoisting ou um agente remoto:
https://verbatra.kreitz-webdev.de/schema/v1/config.jsonOff-line, ou para fixar a versão instalada, use a cópia do pacote, ./node_ (veja Schemas).
.verbatrarc.json e .verbatrarc aceitam uma chave $schema para o VS Code:
{
"$schema": "https://verbatra.kreitz-webdev.de/schema/v1/config.json",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"format": "i18next-json",
"files": { "pattern": "locales/{locale}.json" },
"provider": { "id": "gemini", "options": { "model": "gemini-2.5-flash", "maxOutputTokens": 4096 } }
}O .verbatrarc sem extensão também precisa de uma correspondência de arquivo no workspace:
{
"json.schemas": [
{
"fileMatch": [".verbatrarc", ".verbatrarc.json"],
"url": "https://verbatra.kreitz-webdev.de/schema/v1/config.json"
}
]
}Uma configuração YAML aceita um comentário do YAML Language Server:
# yaml-language-server: $schema=https://verbatra.kreitz-webdev.de/schema/v1/config.json
sourceLocale: en
targetLocales: [de, fr]
format: i18next-json
files:
pattern: "locales/{locale}.json"
provider:
id: gemini
options:
model: gemini-2.5-flash
maxOutputTokens: 4096O package.json não aceita schema; as formas executáveis são tipadas por defineConfig.
O que o documento não consegue verificar
Só o carregamento da configuração verifica estas regras: as regras de targetLocales e os códigos de locale, as chaves de localeMap e do mapa tone e as regras de baseUrl e de apiKeyEnvVar do openai-compatible, os endereços e intervalos válidos de network.allowedHosts, os sensitiveData.patterns dentro das regras de segurança e as regras de termo de um glossário da versão 2 inline.
O diretório de trabalho e o .env
O diretório de trabalho (onde você executa o verbatra, ou --cwd) inicia a busca da configuração e contém os arquivos de ambiente. Os caminhos de locale, o verbatra.lock.json, o cache, o arquivo de procedência e o .verbatra-local/ são resolvidos a partir da raiz do projeto, o diretório da configuração encontrada, então uma execução a partir de um subdiretório usa os mesmos arquivos. Com --config, o diretório de trabalho é a raiz, e uma configuração em outro lugar recebe uma nota no stderr, já que o caminho do glossário dela é resolvido a partir do próprio diretório. Um caminho que você passa, como --out ou check --file, é resolvido a partir do diretório de trabalho.
Quando o carregamento falha
CONFIG_: nenhuma configuração em nenhum lugar buscado, ou o caminho deNOT_ FOUND --confignão existe.CONFIG_: uma configuração foi encontrada, mas é inutilizável. A mensagem lista todos os problemas com o caminho da opção; uma opção desconhecida acrescenta a dica de que as chaves de API vêm do ambiente. Uma falha de análise nomeia o arquivo (com linha e coluna para YAML), mas nunca cita o conteúdo dele, e toda mensagem passa pela ocultação de chaves de API.INVALID
A CLI termina com 2 nos dois casos.