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 #

text
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.

O agente:

  1. 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.
  2. 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).
  3. Pede que você faça login. Quando solicitado, execute npx @lingo.dev/cli@latest login no seu próprio terminal; nunca cole uma chave de API na conversa.
  4. Executa lingo init e lingo 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.
  5. Apresenta o plano e um lingo push --estimate e só traduz após sua aprovação.
  6. Registra os novos idiomas no aplicativo e oferece a opção de conectar o GitHub App.

Conectar o GitHub App #

text
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:

markdown
<!-- 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.md existente também recebe o bloco, a menos que importe um AGENTS.md que já o contenha (@AGENTS.md). CLAUDE.md nunca é 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 setup novamente.
  • 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 #

bash
lingo agent setup

Verifica 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çãoEfeito
--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-runMostra o que seria alterado sem gravar nada.
--statusMostra o que está configurado para os agentes detectados. Ignora --client.
-y, --yesGrava o bloco sem pedir confirmação.

Se não houver nenhum agente para verificar, o comando falha sem gravar nada.

lingo agent-guide #

bash
lingo agent-guide           # the agent guide and the list of guides
lingo agent-guide setup     # one guide

Sem 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).