Configurar com um agente de programação

Deixe o Claude Code, o Codex ou o Cursor configurar o Lingo.dev no seu projeto com os guias da CLI para agentes: instruções para copiar, o bloco AGENTS.md, lingo agent setup e lingo agent-guide.

A CLI inclui guias escritos para agentes de programação como o Claude Code, o Codex e o Cursor. Dê ao seu agente uma das instruções abaixo. O agente executa lingo agent-guide, lê o guia da tarefa e faz o trabalho no seu repositório com a CLI. As tarefas relacionadas com a conta, como o glossário do motor ou a ligação à GitHub App, são realizadas através do Lingo.dev MCP server.

Os guias são distribuídos com a CLI, pelo que o agente lê sempre o guia correspondente à versão que está a executar. Antes de traduzir o que quer que seja, apresenta-lhe um plano e uma estimativa e aguarda a sua aprovação.

Instruções #

Na raiz do projeto, cole uma instrução no seu agente.

Configurar o Lingo.dev de raiz #

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 as tiver, adiciona o servidor e pede-lhe que reinicie o agente e volte a colar a instrução.
  2. Identifica as tecnologias utilizadas, encontra todos os ficheiros de origem que a aplicação carrega e segue o guia correspondente (Rails, iOS, Android, Markdoc, e-mails, uma biblioteca de i18n ou um site de documentação).
  3. Pede-lhe que inicie sessão. Execute npx @lingo.dev/cli@latest login no seu próprio terminal quando lhe for pedido; nunca cole uma chave de API na conversa.
  4. Executa lingo init e lingo link. Se o projeto já tiver traduções, verifica se contêm marcadores de posição inválidos, texto por traduzir e inconsistências terminológicas e faz apenas as correções que aceitar.
  5. Apresenta o plano e um lingo push --estimate e só traduz depois da sua aprovação.
  6. Regista os novos idiomas na aplicação e propõe ligar a GitHub App.

Ligar a 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 começa por configurar o projeto, caso ainda não esteja configurado. Verifica se a GitHub App tem acesso ao repositório e, se não tiver, fornece-lhe ligações para resolver a situação. Permite-lhe escolher se a aplicação traduz após a integração ou em pedidos de integração e só abre o pedido de integração com a configuração depois de obter a sua aprovação.

O bloco AGENTS.md #

lingo init e lingo agent setup escrevem um pequeno bloco em AGENTS.md, na raiz do projeto, para que todas as sessões seguintes do agente saibam que devem ler os guias antes de realizar tarefas de 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 se não existir. O texto fora dos marcadores é mantido e uma execução posterior substitui apenas o texto entre eles.
  • Um CLAUDE.md existente também recebe o bloco, a menos que importe um AGENTS.md que já o tenha (@AGENTS.md). CLAUDE.md nunca é criado.
  • O ficheiro é mantido sem alterações e é apresentado um aviso se não puder ser lido, apontar para fora do projeto ou tiver marcadores sem correspondência. Corrija o ficheiro e volte a executar lingo agent setup.
  • Para não adicionar o bloco, execute lingo init --no-agents-md.

Quando um agente executa um comando do Lingo.dev num projeto cujo AGENTS.md ou CLAUDE.md não tem o bloco, a CLI escreve uma linha em stderr a indicar-lhe que execute lingo agent setup -y. Esta linha nunca é apresentada a pessoas nem à 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 é executado) têm o Lingo.dev MCP server e indica o ficheiro de configuração a alterar para cada um que não o tenha. Nunca edita as configurações dos agentes; adicione o servidor seguindo os passos em Configuração do MCP. Dentro de um projeto, também escreve o bloco AGENTS.md, depois de pedir autorização.

OpçãoEfeito
--client <name>Verificar apenas este agente, mesmo que não tenha sido detetado: claude-code, codex ou cursor. A opção pode ser repetida.
--dry-runMostrar o que seria alterado sem escrever nada.
--statusMostrar o que está configurado para os agentes detetados. Ignora --client.
-y, --yesEscrever o bloco sem pedir autorização.

Se não houver nenhum agente para verificar, o comando falha sem escrever 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, apresenta o guia que serve de ponto de partida a todos os agentes (CLI ou MCP, início de sessão, configuração inicial por concluir) e lista os guias. Com um nome, apresenta o guia correspondente. Se o nome for desconhecido, termina a execução com o código 1 e lista os guias disponíveis nesta versão. lingo guide disponibiliza os guias a quem utiliza @lingo.dev/react.

Sessões sem intervenção humana #

Numa sessão na nuvem ou de CI, defina LINGO_API_KEY para que o agente não precise de iniciar sessão. Nestas condições, o agente realiza a parte da tarefa relativa à CLI e não configura o MCP server. A última mensagem lista as tarefas que ainda exigem acesso à conta e que pode concluir na aplicação Web ou com um agente que tenha o MCP server.

Quando uma tradução é recusada por motivos de faturação, a CLI termina com o código 9 se for necessária intervenção humana (créditos esgotados, limite do motor atingido ou funcionalidade indisponível no plano) e com o código 75 se a quota diária de tokens estiver esgotada. Apresenta o motivo e a ligação para a página de faturação. Os guias indicam aos agentes que devem parar ao receber qualquer um destes 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 um passo falha e quando uma tarefa termina, para que possamos melhorar os guias. Cada relatório contém o guia e o passo, um resumo de uma ou duas frases, o nome do agente e a organização e o motor associados. A CLI remove as credenciais e os valores secretos e limita cada texto a 500 carateres. O envio de um relatório nunca faz falhar a tarefa e não é enviado nada quando ninguém tem sessão iniciada ou a telemetria está desativada (LINGO_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 ou OTEL_SDK_DISABLED=true).