---
title: "Perguntas frequentes"
description: "Respostas curtas às perguntas mais comuns ao usar o verbatra, de quanto custa uma execução ao que você deve incluir no commit."
type: "reference"
---
# Perguntas frequentes

Respostas curtas às perguntas mais comuns ao usar o verbatra, de quanto custa uma execução ao que você deve incluir no commit.

Respostas curtas, cada uma com um link para a página com os detalhes. Para mensagens de erro, veja
[Solução de problemas](https://verbatra.kreitz-webdev.de/pt-BR/docs/troubleshooting.md) e [Códigos de erro](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md).

## Como controlo o custo? [#como-controlo-o-custo]

As execuções são incrementais, então só as chaves ausentes ou alteradas chegam ao provedor, e um projeto
sem alterações não custa nada para executar de novo. `verbatra translate --estimate` dimensiona uma
execução sem chamar um provedor, e `--max-tokens` ou `maxTokens` na configuração a limita. Veja
[Estimar o custo antes de uma execução](https://verbatra.kreitz-webdev.de/pt-BR/docs/estimating-cost.md).

## Quanto custa de fato uma execução? [#quanto-custa-de-fato-uma-execução]

Pouco: 400 chaves em 3 locales no `gemini-2.5-flash` somam cerca de 72.000 tokens, que você precifica
pelo preço atual do seu provedor, e as execuções seguintes pagam só pelas strings que você alterou. Como
dimensionar uma execução, onde cada provedor publica seus preços e como calibrar com o seu próprio projeto
estão em [Estimar o custo antes de uma execução](https://verbatra.kreitz-webdev.de/pt-BR/docs/estimating-cost.md).

## Com qual provedor devo começar? [#com-qual-provedor-devo-começar]

Com o Gemini, porque o nível gratuito da API dele permite traduzir um projeto inteiro sem custo, e trocar
depois significa editar um único `id`. Mantenha strings confidenciais fora do nível gratuito: veja
[Retenção pelo fornecedor e termos de tratamento de dados](https://verbatra.kreitz-webdev.de/pt-BR/docs/data-handling.md#retenção-pelo-fornecedor-e-termos-de-tratamento-de-dados). Todos os
provedores são comparados em [Provedores](https://verbatra.kreitz-webdev.de/pt-BR/docs/providers.md).

## Posso usar um modelo local? [#posso-usar-um-modelo-local]

Sim: o provedor `openai-compatible` aponta o verbatra para qualquer servidor que fale a API de chat da
OpenAI, como LM Studio, Ollama ou vLLM, em geral sem chave de API. Sem nenhum modelo de linguagem,
o `libretranslate` usa um servidor LibreTranslate auto-hospedado. Veja [Provedores](https://verbatra.kreitz-webdev.de/pt-BR/docs/providers.md#libretranslate).

## Quais idiomas o verbatra suporta? [#quais-idiomas-o-verbatra-suporta]

Qualquer idioma que seu provedor suporte, escrito como um código BCP 47 válido, como `pt-BR` ou `zh-Hant`.
O DeepL e o Google Cloud Translation têm listas fixas; os provedores de LLM não têm. Veja
[Idiomas e locales](https://verbatra.kreitz-webdev.de/pt-BR/docs/language-support.md).

## Como as chaves mantêm a ordem? [#como-as-chaves-mantêm-a-ordem]

As chaves existentes mantêm suas posições e as chaves novas são acrescentadas na ordem da origem, então um
arquivo traduzido gera diffs limpos. Veja [Formatos](https://verbatra.kreitz-webdev.de/pt-BR/docs/formats.md).

## Por que uma tradução foi sinalizada para revisão? [#por-que-uma-tradução-foi-sinalizada-para-revisão]

Uma heurística de revisão encontrou algo que merece uma segunda olhada, como uma tradução igual à sua
origem, e a sinalizou sem retê-la. Todo código de motivo está listado em
[Motivos de revisão](https://verbatra.kreitz-webdev.de/pt-BR/docs/error-codes.md#review-reason-codes).

## O verbatra funciona em um monorepo? [#o-verbatra-funciona-em-um-monorepo]

Sim. A busca pela configuração sobe a partir do diretório de trabalho e para no `.git` mais próximo, então
um pacote encontra a própria configuração e a raiz encontra a configuração da raiz; `--cwd` e `--config`
apontam para qualquer outro lugar. Veja [Arquivo de configuração](https://verbatra.kreitz-webdev.de/pt-BR/docs/config-file.md).

## O que devo incluir no commit? [#o-que-devo-incluir-no-commit]

Faça commit dos seus arquivos de locale, do `verbatra.lock.json` e do `verbatra.provenance.json`; nunca de
`.env`, `.env.local`, `.verbatra-local/` ou `verbatra.cache.json`, que o `verbatra init` adiciona ao
`.gitignore`. Veja [O arquivo de lock e a procedência](https://verbatra.kreitz-webdev.de/pt-BR/docs/the-lock-file.md).

## Como retraduzo tudo? [#como-retraduzo-tudo]

Apague o arquivo de locale e execute `verbatra translate --no-cache`: cada chave passa a estar ausente e é
enviada ao provedor de novo. Sem `--no-cache`, os acertos na memória de tradução preenchem de novo o que
eles guardam. Apagar o arquivo de lock não resolve, porque, sem uma linha de base, as traduções existentes
contam como atuais. Para uma única chave, use a ação de retradução do Studio ou `retranslateEntry`.

## Usar a CLI significa instalar o SDK? [#usar-a-cli-significa-instalar-o-sdk]

Nenhum passo extra: `@verbatra/cli` depende de `@verbatra/sdk`, então ele vem junto. Só
`@verbatra/studio` e `@verbatra/mcp` são instalações separadas e opcionais.

## Onde ficam as chaves de API? [#onde-ficam-as-chaves-de-api]

Só em variáveis de ambiente, que a CLI também lê de
[`.env.local` e `.env`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli.md#arquivos-de-ambiente). A configuração rejeita opções desconhecidas, para que
um segredo não vá parar em um arquivo versionado. Veja [Provedores](https://verbatra.kreitz-webdev.de/pt-BR/docs/providers.md).

## O verbatra envia minhas strings para algum lugar? [#o-verbatra-envia-minhas-strings-para-algum-lugar]

Só ao provedor que você configura, e só quando um comando traduz; não há telemetria.
Com `provider: { id: "none" }`, nada sai da máquina. Veja
[Tratamento de dados e privacidade](https://verbatra.kreitz-webdev.de/pt-BR/docs/data-handling.md).

## O que o verbatra doctor verifica de fato? [#o-que-o-verbatra-doctor-verifica-de-fato]

<AvailableFrom version="0.9.0" />

A configuração do projeto, em uma só passada, sem nenhuma chamada de tradução e sem ler o valor de uma chave de API,
a menos que você passe `--live`, que a envia para buscar a lista de idiomas do provedor: a configuração, o
formato, o provedor, a variável da chave de API, a política de rede, o arquivo de origem e o suporte a
locales, além de relatórios informativos sobre plurais, códigos de locale, estado de locale que sobrou e
`verbatra.limits.json`. O [`verbatra doctor`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/doctor.md) tem a tabela completa de verificações.

## Um agente de IA pode configurar ou operar o verbatra por mim? [#um-agente-de-ia-pode-configurar-ou-operar-o-verbatra-por-mim]

Sim, por quatro pontos de entrada: um prompt de configuração para agentes de programação
([Configurar o verbatra com um agente de IA](https://verbatra.kreitz-webdev.de/pt-BR/docs/start-with-ai.md)), a saída `--json` para seus próprios laços
([Automatizar o verbatra com JSON](https://verbatra.kreitz-webdev.de/pt-BR/docs/agent-recipes.md)), ferramentas WebMCP em uma aba aberta do Studio
([Operar o Studio com um agente de navegador](https://verbatra.kreitz-webdev.de/pt-BR/docs/agent-tools-in-studio.md)) e um servidor MCP via stdio
([`verbatra mcp`](https://verbatra.kreitz-webdev.de/pt-BR/docs/cli/mcp.md)). O Studio e o servidor MCP só gastam com um provedor quando liberados pela
flag `--allow-spend`; no laço com `--json`, um `translate` real gasta na hora, então seu script ou
agente precisa obter antes a autorização de uma pessoa.

## Este site publica algo para agentes de IA e rastreadores? [#este-site-publica-algo-para-agentes-de-ia-e-rastreadores]

Sim, três arquivos estáticos, gerados no build e sempre em inglês, seja qual for o locale
em que você está navegando:

- [`/llms.txt`](https://verbatra.kreitz-webdev.de/llms.txt): um índice selecionado do título e da descrição de cada página da documentação,
  agrupado como a barra lateral, em links Markdown.
- [`/llms-full.txt`](https://verbatra.kreitz-webdev.de/llms-full.txt): a documentação inteira em um único arquivo, com o conteúdo renderizado
  de cada página concatenado em ordem, para um agente que ingere o conteúdo diretamente em vez de seguir
  links.
- [`/.well-known/ai.txt`](https://verbatra.kreitz-webdev.de/.well-known/ai.txt): uma política de uso que informa aos rastreadores de IA que este
  projeto tem licença MIT e que rastrear, indexar e citar este conteúdo é bem-vindo.

Os três têm link na coluna “Para agentes de IA” do rodapé.

## O conteúdo deste site é traduzido por IA? [#o-conteúdo-deste-site-é-traduzido-por-ia]

Em sua maior parte, sim, por dois mecanismos diferentes. A interface do site (rótulos de navegação, botões, o rodapé, o texto da
página inicial, as perguntas frequentes da página inicial) fica em `messages/en.json` e em um arquivo irmão para cada outro idioma; esses são traduzidos automaticamente, seja com o próprio verbatra, no formato `next-intl-json`, pelo provedor Gemini, executando `pnpm i18n` depois que a origem em inglês muda, seja por um agente de programação de IA que trabalha no repositório e cuja saída é importada com `verbatra import`. Assim, este
projeto usa a própria ferramenta (dogfooding), e o fluxo de trabalho `docs-i18n-check` reprova um pull request cujos
arquivos de locale divergiram da origem em inglês. A prosa da documentação que você está lendo agora,
todo guia e toda página de referência, inclusive esta, é MDX com sufixo de locale (`page.mdx` e um `page.<locale>.mdx` para cada outro idioma) que também é traduzido por IA, mas fora desse
fluxo automatizado: o `pnpm i18n` só traduz os formatos estruturados de arquivo de locale (veja [Formatos](https://verbatra.kreitz-webdev.de/pt-BR/docs/formats.md)), nunca Markdown,
então nunca toca nestas páginas. Em vez disso, um agente de IA traduz cada página da documentação na mesma alteração que edita a origem em inglês, então todos os idiomas chegam juntos; é por isso que toda página em outro idioma
traz o aviso de tradução automática.

Nem tudo sai desses dois passos sem mudança: alguns textos, inclusive partes das páginas
legais, foram escritos ou corrigidos diretamente nos arquivos de locale. As traduções são verificadas na medida do possível, e nem todo texto traduzido é revisado por uma pessoa antes de ser publicado, então
uma tradução pode conter erros. A [política de privacidade](https://verbatra.kreitz-webdev.de/privacy) descreve o mesmo processo.

Se um texto traduzido soar estranho, abra uma issue em qualquer um dos casos: para o texto da interface, a
correção vai para a origem em inglês e é retraduzida ou reimportada, ou direto para o arquivo de locale afetado; para a
prosa da documentação, edite o arquivo MDX diretamente e envie um pull request.
