Configurar com um agente de programação
A CLI traz guias feitos para agentes de programação como Claude Code, Codex e Cursor. Envie um dos prompts abaixo ao seu agente. Ele executa lingo agent-guide, lê o guia da tarefa e faz o trabalho no seu repositório com a CLI. As tarefas relacionadas à conta, como o glossário do engine ou a conexão com o GitHub App, são feitas pelo Lingo.dev MCP server.
Os guias acompanham a CLI, então o agente sempre lê o guia correspondente à versão que está executando. Antes de traduzir qualquer coisa, ele apresenta um plano e uma estimativa e aguarda sua aprovação.
Prompts #
Com o agente na raiz do projeto, cole um dos prompts.
Configurar o Lingo.dev do zero #
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.O agente:
- Verifica se tem as ferramentas MCP do Lingo.dev. Se não tiver, adiciona o servidor e pede que você reinicie o agente e cole o prompt novamente. Um agente na nuvem ou em CI pula essa etapa e o login pelo navegador; veja Sessões sem intervenção humana.
- Identifica as tecnologias do projeto, encontra todos os arquivos-fonte carregados pelo aplicativo e segue o guia correspondente (Rails, iOS, Android, Markdoc, e-mails, uma biblioteca de i18n ou um site de documentação).
- Pede que você faça login. Execute
npx @lingo.dev/cli@latest loginno seu próprio terminal quando solicitado; nunca cole uma chave de API na conversa. - Executa
lingo initelingo link. Se o projeto já tiver traduções, verifica se há placeholders inválidos, texto não traduzido e termos inconsistentes, e só faz as correções que você aprovar. - Apresenta o plano e um
lingo push --estimatee só traduz após sua aprovação. - Registra os novos idiomas no aplicativo e oferece a opção de conectar o GitHub App.
Conectar o GitHub App #
Connect the Lingo.dev GitHub App to this repository. Run npx @lingo.dev/cli@latest agent-guide github and follow it.O agente começa configurando o projeto, caso isso ainda não tenha sido feito, verifica se o GitHub App pode acessar o repositório e fornece links para resolver eventuais problemas. Você escolhe se o App deve traduzir após uma mesclagem ou em solicitações de pull, e o agente só abre a solicitação de pull com a configuração depois da sua aprovação.
O bloco AGENTS.md #
lingo init e lingo agent setup gravam um bloco curto em AGENTS.md, na raiz do projeto, para que todas as sessões seguintes do agente saibam que devem ler os guias antes de trabalhar na localização:
<!-- lingo:begin -->
## Lingo.dev localization
This project is localized with Lingo.dev. The config is `.lingo/config.json` next to this file. Lingo.dev commands and workflows change between versions, so do not rely on what you remember about them.
Before any localization task (translating content, adding a locale, connecting GitHub, changing the glossary or tone of voice), run `npx @lingo.dev/cli agent-guide` from this directory and follow the guide it names. The guides ship with the CLI and describe the version you run.
This block is written by `lingo init` and `lingo agent setup`. Text between the markers is replaced on the next run; keep your own notes outside them.
<!-- lingo:end -->AGENTS.mdé criado se não existir. O texto fora dos marcadores é preservado, e as execuções seguintes substituem apenas o texto entre eles.- Um
CLAUDE.mdexistente também recebe o bloco, a menos que importe umAGENTS.mdque já o contenha (@AGENTS.md).CLAUDE.mdnunca é criado. - O arquivo é mantido sem alterações, com um aviso, se não puder ser lido, apontar para fora do projeto ou tiver marcadores sem par. Corrija o arquivo e execute
lingo agent setupnovamente, adicionando--client <name>se o seu agente não for detectado. - Para pular o bloco, execute
lingo init --no-agents-md.
Quando um agente executa um comando do Lingo.dev em um projeto cujo AGENTS.md ou CLAUDE.md não contém o bloco, a CLI exibe uma linha em stderr orientando o agente a executar lingo agent setup -y. Essa linha nunca é exibida para pessoas ou em CI.
lingo agent setup #
lingo agent setupVerifica se os agentes de programação desta máquina (Claude Code, Codex e Cursor, além do agente em que o comando está sendo executado) têm o Lingo.dev MCP server e indica qual arquivo de configuração alterar em cada agente que não o tenha. O comando nunca edita as configurações dos agentes; adicione o servidor seguindo as etapas em Configuração do MCP. Dentro de um projeto, ele também grava o bloco AGENTS.md, após pedir sua autorização.
| Opção | Efeito |
|---|---|
--client <name> | Verifica apenas este agente, mesmo que não tenha sido detectado: claude-code, codex ou cursor. A opção pode ser repetida. |
--dry-run | Mostra o que mudaria, sem gravar nada. |
--status | Mostra o que está configurado para os agentes detectados. Ignora --client. |
-y, --yes | Grava o bloco sem perguntar. |
Sem --status, o comando falha sem gravar nada se não houver um agente para verificar. Nesse caso, especifique um com --client.
lingo agent-guide #
lingo agent-guide # the agent guide and the list of guides
lingo agent-guide setup # one guideSem um nome, exibe o guia pelo qual todos os agentes começam (CLI ou MCP, login e configuração inicial incompleta) e lista os guias. Com um nome, exibe o guia correspondente. Se o nome for desconhecido, encerra a execução com o código 1 e lista os guias disponíveis nesta versão. Quem usa @lingo.dev/react tem seus próprios guias em lingo guide.
Sessões sem intervenção humana #
Em uma sessão na nuvem ou em CI, defina LINGO_API_KEY para que o agente não precise fazer login. Esse agente cuida da parte da tarefa realizada pela CLI e não configura o MCP server. Na última mensagem, ele lista as tarefas pendentes que exigem acesso à conta; você pode concluí-las no aplicativo web ou com um agente que tenha o MCP server.
Quando uma tradução é recusada por motivos de cobrança, a CLI encerra a execução com o código 9 se uma pessoa precisar agir (créditos esgotados, limite do engine atingido ou recurso não disponível no plano) e com o código 75 se a cota diária de tokens tiver sido esgotada. Ela exibe o motivo e um link para a página de cobrança. Os guias orientam os agentes a parar ao receber qualquer um desses códigos.
Relatórios dos agentes #
Os guias pedem que os agentes enviem ao Lingo.dev um relatório curto com lingo agent report quando uma etapa falha e quando uma tarefa termina, para que possamos melhorar os guias. O relatório inclui o guia e a etapa, um resumo de uma ou duas frases, o que o agente propôs, o nome do agente e a organização e o engine vinculados. A CLI remove credenciais e valores secretos do resumo e da proposta e limita cada um a 500 caracteres; os guias orientam os agentes a não incluir código, conteúdo de arquivos nem segredos em nenhum campo. O envio de um relatório nunca faz a tarefa falhar, e nada é enviado quando ninguém está conectado ou a telemetria está desativada (LINGO_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 ou OTEL_SDK_DISABLED=true).