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 |
Eles se somam. 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 deles pode aprovar uma tradução automática, e isso é de propósito: o porquê está no fim da página.
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.
claude mcp add verbaly -- npx -y @verbaly/mcpO 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 seis ferramentas
Vêm na ordem em que um agente encontra um projeto: descobrir o que falha, envolver o texto que já está lá, e só então rodar o ciclo sobre ele.
| Ferramenta | O que faz | Escreve? |
|---|---|---|
| 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 | Sim |
| verbaly_status | Cobertura por idioma, e quantas traduções automáticas estão esperando uma pessoa | Não |
| verbaly_missing | Tudo o que faria a porta de CI falhar: traduções que faltam, chaves desconhecidas e traduções que existem mas não conseguem renderizar o que o original renderiza | Não |
| verbaly_translate | Preenche as lacunas pelo provedor que você configurou, salvando tudo como rascunho | Sim |
As três 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 apenas 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 ferramenta que falha volta como uma mensagem sobre a qual o agente pode agir, nunca como um servidor caído: um config que falta avisa, e um catálogo que não é JSON válido também.
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.
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.
npx degit AronSoto/verbaly/skills/verbaly .claude/skills/verbalyAs regras que ela carrega são as que se erram facilmente de fora: as chaves são geradas e nunca escritas na mão, "" num catálogo significa sem tradução, placeholders e tags precisam sobreviver à tradução literalmente, e links vão por tag nomeada mais um mapa de links, nunca um <a href> literal dentro de uma mensagem.
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 verbaly_translate produz é rascunho, e rascunho não vai para produção: com verbaly check --drafts no CI, o build continua falhando enquanto sobrar algum. A ferramenta que os aceita, verbaly review --approve, não é exposta aos agentes de propósito.