Configurar com um agente de programação

Max PrilutskiyCEO e cofundador5 min de leitura

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 ao nível da conta, como gerir o glossário do motor ou a ligação à GitHub App, são tratadas através do MCP server do Lingo.dev.

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

Instruções #

A partir da 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 tiver, adiciona o servidor e pede-lhe que o reinicie e volte a colar a instrução. Um agente na nuvem ou em CI ignora este passo e o início de sessão no navegador; consulte Sessões sem intervenção humana.
  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 existem marcadores de posição inválidos, texto por traduzir e termos inconsistentes, e só faz as correções que aprovar.
  5. Apresenta o plano e um lingo push --estimate e só traduz após a 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 consegue aceder ao repositório e fornece ligações para resolver eventuais problemas. Permite-lhe escolher se a GitHub App traduz após uma 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, nas sessões seguintes, os agentes saibam que devem 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 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 contenha (@AGENTS.md). CLAUDE.md nunca é criado.
  • O ficheiro fica inalterado 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, adicionando --client <name> se o seu agente não for detetado.
  • 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 que deve executar lingo agent setup -y. Esta mensagem nunca é apresentada a 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 do agente em que o comando está a ser executado) têm o MCP server do Lingo.dev e, para cada um que não o tenha, indica o ficheiro de configuração a alterar. 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. Ignorar --client.
-y, --yesEscrever o bloco sem pedir autorização.

Sem --status, o comando falha sem escrever nada se não houver nenhum agente para verificar. Nesse caso, especifique um com --client.

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 inicial de 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 com o código 1 e lista os guias disponíveis nesta versão. Quem utiliza @lingo.dev/react tem guias próprios em lingo guide.

Sessões sem intervenção humana #

Numa sessão na nuvem ou em CI, defina LINGO_API_KEY para que o agente não precise de iniciar sessão. Esse agente trata da parte da tarefa que usa a CLI e não configura o MCP server. Na última mensagem, lista as tarefas pendentes que requerem acesso à conta; pode concluí-las 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 não disponível no plano) e com o código 75 se a quota diária de tokens tiver sido esgotada. Apresenta o motivo e uma ligação para a página de faturação. Os guias indicam aos agentes que parem perante qualquer um destes códigos.

Relatórios dos agentes #

Os guias pedem aos agentes que enviem ao Lingo.dev um breve relatório através de lingo agent report quando um passo falha e quando uma tarefa termina, para podermos melhorar os guias. O relatório inclui o guia e o passo, um resumo de uma ou duas frases, o que o agente propôs, o nome do agente e a organização e o motor associados. A CLI remove as credenciais e os valores secretos do resumo e da proposta e limita cada um a 500 carateres; os guias indicam aos agentes que não incluam código, conteúdo de ficheiros nem segredos em nenhum campo. Um relatório nunca faz com que a tarefa falhe e nada é enviado quando ninguém tem sessão iniciada ou quando a telemetria está desativada (LINGO_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 ou OTEL_SDK_DISABLED=true).