Guias
Agentes de código
Um agente que escreve seu app também escreve o texto que ele carrega. Existem três formas de entregar o ciclo a ele, e elas respondem perguntas diferentes: rodar os comandos, aprender as regras ou ler a documentação.
Três canais, três perguntas
| Canal | O que resolve | O que precisa |
|---|---|---|
| Servidor MCP | Rodar o ciclo: diagnosticar, envolver o texto que você já escreveu, extrair, traduzir | Uma linha no seu cliente MCP |
| Agent Skill | Escrever o código certo de primeira: as regras que mantêm o ciclo seguro | Um arquivo copiado para o seu projeto |
| llms.txt | Achar a página certa: um índice desta documentação em markdown | Nada, já é servido |
Empilham-se. A skill ensina as regras, o servidor faz o trabalho e o índice é o que um agente lê quando precisa de mais do que qualquer um dos dois. Nenhum pode aprovar uma tradução de máquina, e o fim desta página diz por quê.
O servidor MCP
@verbaly/mcp expõe o ciclo como ferramentas sobre o Model Context Protocol, então um agente roda tudo sem tocar num terminal. Funciona com qualquer cliente MCP, Claude Code e Cursor incluídos.
O servidor lê seu verbaly.config a partir do diretório em que inicia. Passe --root quando esse não for o seu projeto, e cada ferramenta também aceita um root próprio para um monorepo com mais de um app.
As ferramentas
Vêm na ordem em que um agente encontra um projeto: montar, descobrir o que falha, envolver o texto que já está lá, e só então rodar o ciclo sobre ele. Essa é a ordem em que o servidor as entrega, não só a ordem desta página.
| Ferramenta | O que faz | Escreve? |
|---|---|---|
| verbaly_init | Cria seu arquivo de configuração e seus arquivos de idioma, e descobre qual bundler ou framework você usa para poder dizer a única linha que você ainda precisa adicionar. Um idioma passado como pt_BR é escrito pt-BR, e ele avisa | Sim |
| verbaly_doctor | Verifica toda a montagem de uma vez: configuração, catálogos, o plugin do seu framework, os tipos gerados, os arquivos que não conseguiu ler e cada tradução que o gate rejeitaria | Não |
| verbaly_wrap | Encontra o texto escrito direto no seu JSX e o envolve para que o compilador possa pegá-lo. Por padrão apenas informa, e o texto que não consegue tratar com segurança é listado em vez de reescrito | Sim |
| verbaly_extract | Varre seu código, adiciona as mensagens novas aos catálogos e regenera os tipos. Uma chave que ele poda leva o seu rascunho junto, e a resposta aponta, com arquivo e linha, qualquer arquivo que não conseguiu ler, qualquer chave escrita com dois textos, qualquer t que não consegue ler porque tem outro nome, qualquer texto fonte que o seu código substituiu e qualquer valor que um tradutor veria sem nome. Quando cria o verbaly.lock, move para ele um arquivo de estado antigo ou o reescreve inteiro depois de um conflito de merge, a resposta avisa, e o agente pode pedir que você o commite | Sim |
| verbaly_status | Cobertura por idioma, e quantas traduções automáticas estão esperando uma pessoa e quantas traduções foram escritas para um texto anterior. Um arquivo de estado que ele não consegue ler é reportado na resposta, nunca como uma falha | Não |
| verbaly_missing | Tudo o que faria a porta de CI falhar: traduções que faltam, chaves desconhecidas, chaves escritas com dois textos e traduções que existem mas não conseguem renderizar o que o original renderiza. Também lista o que nunca a faz falhar: chaves que só uma tradução tem, um catálogo que diz algo que o seu código não diz e traduções escritas para um texto anterior. Todos os caminhos nela são relativos ao seu projeto | Não |
| verbaly_translate | Preenche as lacunas pelo provedor que você configurou, salvando tudo como rascunho. Uma mensagem que alguém escreveu enquanto ele trabalhava fica como estava, e a resposta a nomeia | Sim |
| verbaly_write_drafts | Salva as traduções que o agente escreveu por conta própria. Cada uma é verificada como uma tradução automática contra o texto que o seu código publica, escrita só para chaves que o seu idioma fonte tem e marcada como rascunho para você revisar, com nota do texto para o qual foi escrita. Mantém o que já está traduzido a menos que peçam para reescrever | Sim |
| verbaly_drafts | Cada tradução de máquina que ainda espera por você, ao lado da frase de onde saiu, para que você leia as duas antes de decidir | Não |
As que só leem avisam o cliente, então um agente pode olhar o estado do seu projeto sem permissão para mudar nada. As que escrevem avisam antes: extract e translate aceitam um dryRun que conta o que aconteceria, e wrap informa a menos que você peça para aplicar.
Cada ferramenta responde duas vezes: uma frase para quem lê a conversa, e a mesma resposta como dados. Um agente que pergunta pela cobertura recebe os números em si, não uma linha para decifrar, então continua funcionando mesmo que mudemos como dizemos.
Uma tool que falha volta como uma mensagem sobre a qual o agente pode agir, nunca como um servidor em baixo. Um arquivo de config em falta di-lo, e um catálogo que não é JSON válido também. Um arquivo de estado que um merge deixou quebrado só acrescenta uma linha às respostas que o leem, e as tools que escreveriam rascunhos param antes de escrever qualquer coisa.
Traduzir é o único passo que pode ser interrompido pela metade, porque sai pela rede. Quando uma parte não volta, o resto fica salvo mesmo assim e a resposta nomeia exatamente quais mensagens faltam, então pedir de novo custa só o que falta.
O que ele pode ler
Todas as ferramentas acima trabalham com chaves e contagens, o que basta para dizer que faltam catorze traduções e não basta para te mostrar nenhuma. Dois recursos fecham isso: um agente os lê por endereço, então olhar seu projeto não gasta uma das ações dele.
| Endereço | O que contém |
|---|---|
| verbaly://config | Em qual idioma você escreve, para quais traduz, onde ficam seus arquivos de idioma e se o idioma aparece nos seus endereços |
| verbaly://catalog/{locale} | Todas as mensagens de um idioma, exatamente como seu app as publica: um texto que é do seu código aparece como o seu código o tem. Um valor vazio significa que ninguém traduziu ainda |
Isso é o que torna possível revisar uma tradução de máquina através de um agente. Antes te davam uma chave e pediam para aprovar, o que não é revisar. Agora você vê a frase de onde saiu ao lado do que a máquina escreveu, e a decisão continua sendo sua.
A Agent Skill
Um servidor diz a um agente o que ele pode rodar. Uma skill diz o que ele deve escrever. A Agent Skill do Verbaly vive no repositório e carrega o ciclo mais as regras que o mantêm seguro, então o agente para de inventar chaves de catálogo na mão.
As regras que leva são as que é fácil errar de fora.
- As chaves são geradas, ou vêm do catálogo que o projeto já tem. O agente nunca inventa uma.
""num catálogo quer dizer por traduzir, não vazio de propósito.- Os espaços e as etiquetas têm de sobreviver a uma tradução palavra a palavra.
- Um link vai por uma etiqueta com nome mais um mapa de links, nunca um
<a href>literal dentro de uma mensagem. - Uma tradução que ele mesmo escreve é salva com
verbaly_write_drafts, nunca digitada num catálogo.
llms.txt
Este site serve /llms.txt, um índice em markdown de cada página da documentação com uma linha sobre o que cada uma cobre. Ele é gerado do mesmo menu lateral que você está vendo, então não tem como se desencontrar da documentação real.
É para o agente que lê antes de escrever. Aponte o seu para lá quando ele precisar do mapa inteiro, e para uma página só quando precisar de uma resposta.
Por que um agente não pode aprovar a própria tradução
Tudo o que o verbaly_translate produz é um rascunho, e também tudo o que um agente salva com verbaly_write_drafts, e os rascunhos não saem: com verbaly check --drafts no CI, o build continua falhando enquanto restar algum. Aceitar um é verbaly review --approve ou o servidor de revisão local, e nenhum dos dois está exposto a agentes: um agente aprovando a sua própria tradução é a salvaguarda se aprovando a si mesma.