Referência / CLI
Página traduzida automaticamente
verbatra init
Cria a configuração do verbatra e um .env de exemplo, detectados a partir dos seus arquivos de locale, de forma interativa ou totalmente não interativa.
Gera a configuração inicial de um projeto: o init grava um verbatra.config.ts, um .env.example com o nome da variável da chave de API do seu provedor (nunca o valor de uma chave de API) e as entradas do .gitignore para .env, .env.local, .verbatra-local/ e verbatra.cache.json. Para i18next-json, a configuração também ganha um bloco extract comentado, para você descomentar. Ele lê primeiro os arquivos de locale que já estão no projeto, então em geral o provedor é tudo o que você precisa informar.
Sinopse
verbatra init [flags]Exemplos
# prompt for anything not passed or detected
verbatra init --provider gemini
# fully unattended, one JSON document on stdout
verbatra init --provider gemini --yes --json
# choose the format and pattern yourself
verbatra init --provider deepl --format yaml --path "config/locales/{locale}.yml" --yes
# a local server that needs no key
verbatra init --provider openai-compatible --base-url http://localhost:11434/v1 --model llama3.1 --yes
# a self-hosted LibreTranslate server, no language model
verbatra init --provider libretranslate --base-url http://localhost:5000 --yes
# human-only: no provider, no API key
verbatra init --provider none --yes
# also set the project up for coding agents
verbatra init --provider gemini --yes --agent
# wire Cursor and VS Code, and only show what would change
verbatra init --agent --client cursor,vscode --dry-runFlags
| Flag | Argumento | Padrão | Efeito |
|---|---|---|---|
--provider | <id> | nenhum (obrigatório, a menos que perguntado) | provedor para o qual gerar a configuração: anthropic, openai, gemini, deepl, google-translate, opencode, openai-compatible, libretranslate ou none |
--format | <id> | detectado, senão i18next-json | o formato do arquivo de locale, um dos ids em Formatos |
--source | <locale> | detectado, senão en | o locale de origem em que as suas strings estão escritas |
--targets | <locales> | detectado, senão de | locales de destino, separados por vírgulas, para os quais traduzir |
--path | <pattern> | detectado, senão o layout usual do formato (Detecção) | padrão de caminho dos arquivos de locale; precisa conter o placeholder {locale} |
--model | <name> | o padrão gerado | o modelo; obrigatório para openai-compatible, opcional para anthropic, openai, gemini e opencode |
--base-url | <url> | nenhum | a URL do servidor; só para openai-compatible e libretranslate, e obrigatória nesses dois |
--api-key-env-var | <name> | OPENAI_ | a variável de onde o openai-compatible lê a sua chave de API |
--yes | nenhum | desativado | nunca pergunta; usa o padrão para tudo o que não foi passado nem detectado |
--force | nenhum | desativado | sobrescreve um verbatra.config.ts existente cujo conteúdo difere |
--agent | nenhum | desativado | grava também a seção para agentes de programação em AGENTS.md ou CLAUDE.md e o servidor MCP do verbatra na configuração de projeto de cada cliente detectado (Configurar agentes de programação) |
--client | <ids> | detectado | clientes, separados por vírgulas, que o --agent conecta no lugar dos detectados: claude, cursor, vscode, codex, gemini ou all; exige --agent |
--dry-run | nenhum | desativado | relata todo arquivo que o init gravaria ou alteraria e não grava nada (Simulação) |
Aceita também as Flags globais --cwd e --json, mas não --config. Aqui, --cwd é o diretório a varrer e onde gravar, e ele precisa já existir. O --json nunca pergunta.
Comportamento
Perguntas interativas
Uma flag sempre prevalece. Tudo o que você omite é detectado a partir do projeto, depois perguntado quando o stdin é um terminal e nem --yes nem --json foram passados; caso contrário, só assume o padrão sob --yes. Pressionar Enter aceita o valor sugerido. Uma flag com valor vazio, como --targets '', é um erro de uso (INVALID_), nunca um pedido pelo padrão. Se o stdin termina em uma pergunta (Ctrl-D), o init termina com 2 e MISSING_.
Cada resposta é verificada assim que você a dá. Uma resposta inválida é explicada no stderr e perguntada de novo, até três vezes, mantendo as suas respostas anteriores; uma terceira resposta inválida interrompe o init com o código de erro dessa resposta (como INVALID_), nomeia a flag a passar no lugar e não grava nada.
Detecção
O init varre o diretório em busca de arquivos que um adaptador de formato assume, ignorando diretórios ocultos, node_ e a saída de build, e encontra a parte de cada caminho que representa um locale, como de.json, messages_, de.lproj/ ou o values-de/ do Android. O padrão de caminho que cobre mais locales prevalece, e ele preenche:
format: o único formato cujo adaptador lê todos os arquivos encontrados. Todo adaptador JSON lê.json, então, para arquivos JSON, decide uma única dependência correspondente nopackage.json(i18next,vue-i18n,next-intlou@ngx-translate/core).files.patternefiles.localeStyle:posixquando os nomes dos arquivos usampt_,BR androidpara diretóriosvalues-*eliteralnos demais casos.sourceLocale: o idioma de origem de um catálogo.xcstrings; senãoenou o único localeen-*encontrado; senão o único locale encontrado.targetLocales: todos os outros locales encontrados.
Um arquivo ao lado dos arquivos de locale que contém strings sem nenhum nome de locale, como messages.properties, Strings.resx ou um app.pot do gettext, é relatado como unqualifiedSourceFile. O verbatra não consegue ler a origem de um arquivo assim, então o init não adivinha o locale de origem: passe --source, mesmo com --yes, e os próximos passos nomeiam o arquivo a renomear ou para o qual copiar o arquivo base.
Sem nenhum arquivo de locale, só as dependências decidem o formato, e o padrão de caminho segue o layout usual do formato, o que está listado por formato em Escolher sua stack.
Um catálogo apple-xcstrings é um único arquivo compartilhado por todos os locales, e o verbatra nunca o cria: crie-o antes no Xcode. --format, --path e --source restringem a detecção em vez de serem sobrescritos por ela, então --format yaml só olha arquivos YAML.
O init nunca escolhe entre opções equivalentes. Vários formatos que leem os arquivos (JSON simples, sem dependência de i18n) terminam com 2 e FORMAT_, e vários padrões de caminho empatados (um arquivo por namespace) terminam com 2 e LAYOUT_. Os dois listam os candidatos; passe --format ou --path para escolher. Em um terminal, ele pergunta.
Execuções não interativas
Sem terminal, ou com --json, o init nunca pergunta. Um valor que não foi passado, detectado nem assumido como padrão por --yes é um erro: o init termina com 2 e MISSING_ e nomeia toda flag que falta. Uma ambiguidade ou uma flag inválida também lista as flags que ainda faltam, então uma execução diz a um agente tudo o que ele precisa passar. --provider não tem padrão, e --base-url e --model também não, para o openai-compatible, nem --base-url para o libretranslate. Este é o comando que um agente executa:
npx @verbatra/cli init --provider gemini --yes --jsonSaída JSON
Schema: o init-envelope.json valida o envelope inteiro (o objeto JSON da resposta); Schemas lista os demais.
Com --json, o stdout traz exatamente um envelope (veja Saída JSON). O seu result:
interface InitResult {
configPath: string; // absolute path of verbatra.config.ts, or of the config --agent kept
files: { path: string; action: "created" | "overwritten" | "updated" | "unchanged" }[];
dryRun: boolean; // true under --dry-run: files holds the planned actions
config: { // the config that was validated and written
sourceLocale: string;
targetLocales: string[];
format: string;
files: { pattern: string; localeStyle?: "posix" | "android" };
provider: { id: string; options?: Record<string, unknown> };
sensitiveData?: { mode: "warn" };
} | null;
sources: { // where each value came from
provider: "flag" | "prompt";
format: "flag" | "prompt" | "files" | "dependencies" | "default";
pattern: "flag" | "prompt" | "detected" | "default";
sourceLocale: "flag" | "prompt" | "detected" | "default";
targetLocales: "flag" | "prompt" | "detected" | "default";
} | null;
apiKeyEnvVar: string | null; // the variable to set; null for provider none
detection: {
format: { id: string; from: "input" | "files" | "dependencies" } | null;
layout: {
pattern: string;
localeStyle: "literal" | "posix" | "android";
locales: string[];
sourceLocale: string | null;
unqualifiedSourceFile: string | null;
files: string[];
} | null;
ambiguities: { subject: "format" | "layout"; candidates: string[] }[];
confidence: "high" | "medium" | "low" | "none";
reasons: string[]; // one sentence per decision or doubt
} | null;
agent: { // null without --agent
instructionsFile: "AGENTS.md" | "CLAUDE.md";
mcpServer: "added" | "present" | "differs" | "skipped" | null; // Claude Code; null when not wired
configKept: boolean; // true when --agent kept an existing config
clients: {
id: "claude" | "cursor" | "vscode" | "codex" | "gemini";
file: string; // the client's config file, such as .mcp.json
server: "added" | "present" | "differs" | "skipped";
reason: "plugin" | "symlink" | null; // why the client was skipped
selectedBy: "flag" | "markers" | "default";
markers: string[]; // the client's marker files found in the project
}[];
} | null;
nextSteps: { description: string; command: string | null }[];
}confidence é high quando só os arquivos decidiram tudo, medium quando uma convenção ou uma dependência preencheu uma lacuna (como assumir en como origem) ou uma lacuna ficou aberta, low quando nenhum arquivo de locale sustentou o formato e none quando nada foi detectado. Um default em sources é o valor a conferir de novo. nextSteps termina com os comandos exatos a executar em seguida.
Um envelope de erro para FORMAT_, LAYOUT_, INVALID_ ou INVALID_ traz também candidates, os valores entre os quais escolher. Todo erro de uso que deixa flags sem resposta traz missing, que as nomeia, como "--source <locale>".
Provedores
--provider nonegera uma configuração somente humano (veja Trabalhar sem tradução automática) semoptionse não grava.env.example, já que nenhuma chave de API é lida.--provider openai-compatiblegera um servidor local ou auto-hospedado a partir de--base-urle--model, commaxOutputTokens: 4096. A chave de API dele é opcional: um servidor que não precisa de uma deixaOPENAI_sem definir, eCOMPATIBLE_ API_ KEY --api-key-env-varnomeia outra variável, em maiúsculas, comoLLM_. Um valor rejeitado nunca é repetido na saída, para o caso de ele ser a própria chave de API.API_ KEY --provider libretranslategera um servidor LibreTranslate auto-hospedado só a partir de--base-url, comohttp://localhost:5000, e recusa--modele--api-key-env-var. O.env.examplenomeiaLIBRETRANSLATE_para um servidor iniciado comAPI_ KEY --api-keys.
O init grava o nome de uma variável na configuração e no .env.example, nunca um valor, e recusa uma URL base com credenciais, query string ou fragmento (https://user:key@host, https://host/v1?api-key=...), onde uma chave de API poderia ir parar na configuração versionada.
Arquivos existentes
Executar o init de novo com as mesmas respostas não muda nada e termina com sucesso. Um verbatra.config.ts com conteúdo diferente é recusado com CONFIG_, a menos que você passe --force, e essa recusa vem antes de qualquer pergunta ou outro erro. Outra configuração do verbatra no diretório (um .verbatrarc.json ou uma propriedade verbatra no package.json) é recusada mesmo com --force, porque seria lida primeiro. Nada é gravado quando o init recusa. A configuração de um diretório pai que cobre este gera um alerta no stderr (na simulação também): o novo verbatra.config.ts a substitui aqui.
Um diretório em que o init não consegue gravar é recusado com INIT_, nomeando o arquivo e qualquer arquivo já gravado. Um verbatra.config.ts, .env.example ou .gitignore que é um link simbólico levando para fora do projeto, ou para lugar nenhum, é recusado com INIT_ antes de qualquer gravação. Um .env.example existente é mantido; quando ele ainda não nomeia a variável da chave de API, só essa linha é acrescentada, e sob --force uma linha de cabeçalho que o próprio init gravou é reescrita para o novo provedor. O .gitignore recebe só as entradas que lhe faltam.
Simulação
--dry-run executa toda verificação e recusa de uma execução real, exceto uma gravação com falha, como um diretório somente leitura, imprime would create, would update, would overwrite ou unchanged para cada arquivo e não grava nada.
Configurar agentes de programação
O --agent prepara também o projeto para agentes de programação. Ele não grava nenhum valor de chave de API, nunca grava por um link que sai do projeto e adiciona:
- O arquivo de instruções. Uma seção do verbatra entre os marcadores
<!-- verbatra:start -->e<!-- verbatra:end -->, palavra por palavra o trecho de Apresentar o verbatra ao seu agente. Ela vai para oAGENTS.md, ou para oCLAUDE.mdquando esse é o único arquivo de instruções; quando os dois existem, oAGENTS.mdprevalece. Em um arquivo que já contém a seção, o texto entre os marcadores é substituído pelo atual e relatado comoupdated, ouunchangedquando já corresponde. - A configuração MCP de cada cliente. A entrada do servidor
verbatrade Conectar um cliente MCP,npx -y @verbatra/mcpsem--allow-spendnemVERBATRA_, para que as ferramentas pagas fiquem ocultas. OMCP_ ALLOW_ SPEND @verbatra/cliexporta essas entradas comoAGENT_.CLIENT_ CONFIGS
| Cliente | --client | Arquivo | Detectado por |
|---|---|---|---|
| Claude Code | claude | .mcp.json | CLAUDE.md, .claude/, .mcp.json |
| Cursor | cursor | .cursor/mcp.json | .cursor/, .cursorrules |
| VS Code | vscode | .vscode/mcp.json, sob servers | .vscode/mcp.json |
| Codex | codex | .codex/config.toml, como [mcp_ | .codex/ |
| Gemini CLI | gemini | .gemini/settings.json | .gemini/, GEMINI.md |
O init conecta todo cliente que detecta e, quando não encontra nenhum marcador, só o Claude Code. O AGENTS.md escolhe o arquivo de instruções, não um cliente. Uma pasta .vscode sem mcp.json não é conectada: um próximo passo nomeia o comando que a conecta. O Gemini CLI lê o GEMINI.md: a menos que as configurações dele ou o GEMINI.md carreguem o arquivo de instruções, um próximo passo diz como. Um cliente detectado cujo caminho de configuração passa por um link simbólico é ignorado, com o motivo symlink e um próximo passo. O --client substitui a detecção; um id desconhecido, uma lista vazia ou --client sem --agent termina com 2 e INVALID_ com os candidatos.
Nada fora dos marcadores é tocado, e os outros servidores e chaves mantêm seus bytes, sua indentação e suas quebras de linha quando o arquivo tem uma entrada por linha; caso contrário, ele é reescrito com o mesmo conteúdo. A tabela do Codex é acrescentada ao fim. Um servidor verbatra existente nunca é tocado: o arquivo é relatado como unchanged, e o server do cliente é present quando a entrada corresponde ao que foi gerado, ou differs quando não corresponde, o que também adiciona uma observação em nextSteps.
Quando o .claude/settings.json ou o .claude/settings.local.json habilita o plugin do verbatra para o Claude Code, o init ignora o .mcp.json: o Claude Code é relatado como skipped com o motivo plugin e um próximo passo, e uma entrada existente nunca é apagada. Um arquivo de configurações por trás de um link simbólico é ignorado.
Com uma configuração existente, o init --agent a mantém, grava só os arquivos de agente, imprime kept verbatra.config.ts, nunca pergunta e não detecta nada. O resultado JSON lista a configuração como unchanged, define agent.configKept como true e traz null em config, sources, apiKeyEnvVar e detection. Uma flag de configuração ou --force traz a configuração de volta para a execução, como sem --agent.
O init recusa antes de gravar qualquer coisa, com AGENT_, quando um arquivo de cliente não é JSON simples (ele nunca reescreve comentários nem vírgulas finais), não é um objeto, repete uma chave ou tem um valor de servidores que não é um objeto; quando o .codex/config.toml define mcp_ ou o servidor verbatra em linha, com chaves com pontos ou como um array de tabelas, repete essa tabela ou uma chave dela, ou tem uma string, um array ou um cabeçalho sem fechamento; quando um cliente que o --client nomeia tem um link simbólico no caminho da sua configuração, ou um arquivo de instruções leva para fora do projeto; ou quando o arquivo de instruções tem um marcador sem par, fora de ordem ou repetido. A mensagem nunca cita o arquivo.
Códigos de saída
| Código | Significado |
|---|---|
0 | arquivos gravados, ou já em dia |
2 | um erro de uso: MISSING_, INVALID_, INVALID_, INVALID_, INVALID_, INVALID_, FORMAT_, LAYOUT_, CONFIG_, INIT_, AGENT_ ou CONFIG_ quando as respostas não formariam uma configuração válida |
Veja como cada comando usa esses códigos em Códigos de saída.
Veja também
- Configurar o verbatra com um agente de IA é o prompt de agente construído sobre este comando.
- Início rápido percorre o caminho do init até a primeira execução.
- A página Arquivo de configuração documenta todas as opções que a configuração gerada define.
- Provedores cobre as opções dos provedores e as variáveis das chaves de API.