Configura el proyecto con un agente de programación

Max PrilutskiyCEO y cofundador5 min de lectura

La CLI incluye guías pensadas para agentes de programación como Claude Code, Codex y Cursor. Dale a tu agente una de las instrucciones que encontrarás a continuación. Ejecutará lingo agent-guide, leerá la guía correspondiente a la tarea y hará el trabajo en tu repositorio con la CLI. Las tareas relacionadas con la cuenta, como el glosario del motor o la conexión de la GitHub App, se realizan a través del MCP server de Lingo.dev.

Las guías vienen con la CLI, así que el agente siempre lee la guía correspondiente a la versión que está ejecutando. Antes de traducir nada, te muestra un plan y una estimación y espera tu aprobación.

Instrucciones #

Desde la raíz del proyecto, pega una instrucción en tu agente.

Configura Lingo.dev desde cero #

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

El agente:

  1. Comprueba que dispone de las herramientas MCP de Lingo.dev. Si no las tiene, añade el servidor y te pide que lo reinicies y vuelvas a pegar la instrucción. Un agente en la nube o de CI omite este paso y el inicio de sesión en el navegador; consulta Sesiones sin intervención humana.
  2. Identifica las tecnologías del proyecto, localiza todos los archivos de origen que carga la aplicación y ejecuta la guía correspondiente (Rails, iOS, Android, Markdoc, correos electrónicos, una biblioteca de i18n o un sitio de documentación).
  3. Te pide que inicies sesión. Ejecuta npx @lingo.dev/cli@latest login en tu propio terminal cuando te lo indique; nunca pegues una clave de API en la conversación.
  4. Ejecuta lingo init y lingo link. Si el proyecto ya tiene traducciones, busca marcadores de posición que no funcionen, texto sin traducir y términos incoherentes, y corrige solo lo que apruebes.
  5. Te muestra el plan y un lingo push --estimate, y traduce una vez que das tu aprobación.
  6. Registra los nuevos idiomas en la aplicación y te ofrece conectar la GitHub App.

Conecta la GitHub App #

text
Connect the Lingo.dev GitHub App to this repository. Run npx @lingo.dev/cli@latest agent-guide github and follow it.

El agente configura primero el proyecto si aún no está configurado, comprueba que la GitHub App pueda acceder al repositorio y te facilita enlaces para resolver cualquier problema. Te permite elegir si la GitHub App traduce después de una fusión o en las solicitudes de incorporación de cambios, y solo abre la solicitud con la configuración cuando das tu aprobación.

El bloque AGENTS.md #

lingo init y lingo agent setup escriben un bloque breve en AGENTS.md, en la raíz del proyecto, para que en todas las sesiones posteriores el agente sepa que debe leer las guías antes de realizar tareas de localización:

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 -->
  • Si AGENTS.md no existe, se crea. El texto que queda fuera de los marcadores se conserva y, en las ejecuciones posteriores, solo se sustituye el texto entre ellos.
  • Si ya existe un CLAUDE.md, también se le añade el bloque, salvo que importe un AGENTS.md que ya lo contenga (@AGENTS.md). Nunca se crea CLAUDE.md.
  • El archivo se deja sin cambios y se muestra una advertencia si no se puede leer, enlaza a una ubicación fuera del proyecto o tiene marcadores sin pareja. Corrige el archivo y vuelve a ejecutar lingo agent setup; añade --client <name> si no detecta tu agente.
  • Para omitir el bloque, ejecuta lingo init --no-agents-md.

Cuando un agente ejecuta un comando de Lingo.dev en un proyecto cuyo AGENTS.md o CLAUDE.md no contiene el bloque, la CLI escribe una línea en stderr que le indica que ejecute lingo agent setup -y. Ni las personas ni la CI ven esa línea.

lingo agent setup #

bash
lingo agent setup

Comprueba si los agentes de programación de este equipo (Claude Code, Codex y Cursor, además del agente en el que se está ejecutando) disponen del MCP server de Lingo.dev e indica qué archivo de configuración hay que modificar para cada uno que no lo tenga. Nunca modifica la configuración de los agentes; añade el servidor siguiendo los pasos de Configuración de MCP. Si se ejecuta dentro de un proyecto, también escribe el bloque AGENTS.md, tras pedirte permiso.

OpciónEfecto
--client <name>Comprueba solo este agente, aunque no se haya detectado: claude-code, codex o cursor. La opción se puede repetir.
--dry-runMuestra qué cambiaría, pero no escribe nada.
--statusMuestra qué está configurado para los agentes detectados. Ignora --client.
-y, --yesEscribe el bloque sin preguntar.

Sin --status, el comando falla sin escribir nada si no hay ningún agente que comprobar, así que especifica uno con --client.

lingo agent-guide #

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

Si no se indica un nombre, muestra la guía con la que empieza cualquier agente (CLI o MCP, inicio de sesión, configuración inicial sin completar) y enumera las guías. Si se indica un nombre, muestra esa guía. Si el nombre no se reconoce, termina con el código 1 y enumera las guías disponibles en esta versión. Quienes usan @lingo.dev/react tienen sus propias guías en lingo guide.

Sesiones sin intervención humana #

En una sesión en la nube o de CI, establece LINGO_API_KEY para que el agente no tenga que iniciar sesión. Este tipo de agente se encarga de la parte de la tarea que corresponde a la CLI y no configura el MCP server. Su último mensaje enumera las tareas pendientes que requieren acceso a la cuenta; puedes completarlas en la aplicación web o con un agente que tenga el MCP server.

Cuando se rechaza una traducción por motivos de facturación, la CLI termina con el código 9 si hace falta que intervenga una persona (no quedan créditos, se ha alcanzado el límite de motores o el plan no ofrece una función necesaria) y con el código 75 si se ha agotado la cuota diaria de tokens. Muestra el motivo y un enlace a la página de facturación. Las guías indican a los agentes que se detengan ante cualquiera de los dos códigos.

Informes de los agentes #

Las guías piden a los agentes que envíen a Lingo.dev un informe breve con lingo agent report cuando falla un paso y cuando termina una tarea, para que podamos mejorar las guías. El informe incluye la guía y el paso, un resumen de una o dos frases, lo que propuso el agente, su nombre y la organización y el motor vinculados. La CLI elimina las credenciales y los valores secretos del resumen y de la propuesta, y limita cada uno a 500 caracteres; las guías indican a los agentes que no incluyan código, contenido de archivos ni secretos en ningún campo. Un informe nunca provoca que la tarea falle y no se envía nada si nadie ha iniciado sesión o si la telemetría está desactivada (LINGO_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 o OTEL_SDK_DISABLED=true).