Configure com um agente de programação
Deixe o Claude Code, Codex ou Cursor configurar o Lingo.dev no seu projeto com os guias da CLI para agentes: prompts para copiar, o bloco AGENTS.md, lingo agent setup e lingo agent-guide.
A CLI inclui guias escritos para agentes de programação como Claude Code, Codex e Cursor. Passe 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 usando 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 aberto 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.
- Identifica as tecnologias do projeto, encontra todos os arquivos de origem que o aplicativo carrega e executa 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. Quando solicitado, execute
npx @lingo.dev/cli@latest loginno seu próprio terminal; 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 corrige apenas o 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 primeiro configura o projeto, se necessário. Em seguida, verifica se o GitHub App tem acesso ao repositório e fornece links para resolver isso, caso não tenha. Você escolhe se o GitHub App deve traduzir após a 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 pequeno bloco em AGENTS.md, na raiz do projeto, para que, nas próximas sessões, o agente saiba que deve 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 caso não exista. 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, quando não pode ser lido, aponta para fora do projeto ou tem marcadores sem par correspondente. Corrija o arquivo e execute
lingo agent setupnovamente. - Para não gravar 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 mensagem nunca aparece para pessoas nem em CI.
lingo agent setup #
lingo agent setupVerifica se os agentes de programação nesta máquina (Claude Code, Codex e Cursor, além daquele em que o comando está sendo executado) têm o Lingo.dev MCP server e indica o arquivo de configuração a alterar para cada um que não tiver. O comando nunca edita as configurações dos agentes; adicione o servidor seguindo as etapas em Configuração do MCP. Dentro de um projeto, também grava o bloco AGENTS.md após pedir confirmaçã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 seria alterado sem gravar nada. |
--status | Mostra o que está configurado para os agentes detectados. Ignora --client. |
-y, --yes | Grava o bloco sem pedir confirmação. |
Se não houver nenhum agente para verificar, o comando falha sem gravar nada.
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 que todo agente usa para começar (CLI ou MCP, acesso à conta, configuração inicial não concluída) e lista os guias. Com um nome, exibe o guia correspondente. Se o nome não for reconhecido, encerra a execução com o código 1 e lista os guias disponíveis nesta versão. lingo guide disponibiliza os guias para quem usa @lingo.dev/react.
Sessões sem intervenção humana #
Em uma sessão na nuvem ou de CI, defina LINGO_API_KEY para que o agente não precise fazer login. Nesse caso, ele executa a parte da tarefa que usa a CLI e não configura o MCP server. A última mensagem lista o que ainda precisa ser feito na conta. Você pode concluir essas etapas 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 com código 9 se alguém precisar agir (créditos esgotados, limite do engine atingido ou recurso indisponível no plano) e com código 75 se a cota diária de tokens estiver esgotada. Ela exibe o motivo e o 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 aos agentes que enviem ao Lingo.dev um breve relatório com lingo agent report quando uma etapa falha e quando uma tarefa termina, para que possamos melhorar os guias. O relatório contém o guia e a etapa, um resumo de uma ou duas frases, o nome do agente e a organização e o engine vinculados. A CLI remove credenciais e valores secretos e limita cada texto a 500 caracteres. O envio de um relatório nunca faz a tarefa falhar, e nada é enviado quando ninguém está conectado ou quando a telemetria está desativada (LINGO_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 ou OTEL_SDK_DISABLED=true).