Configura el proyecto con un agente de programación
Deja que Claude Code, Codex o Cursor configuren Lingo.dev en tu proyecto con las guías para agentes de la CLI: instrucciones para copiar, el bloque AGENTS.md, lingo agent setup y lingo agent-guide.
La CLI incluye guías 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. El agente ejecuta lingo agent-guide, lee la guía de la tarea y realiza 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 ejecuta. Antes de traducir nada, te muestra un plan y una estimación y espera tu aprobación.
Instrucciones #
Pega una instrucción en tu agente desde la raíz del proyecto.
Configura Lingo.dev desde cero #
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.El agente:
- 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.
- 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 i18n o un sitio de documentación).
- Te pide que inicies sesión. Ejecuta
npx @lingo.dev/cli@latest loginen tu terminal cuando te lo pida; nunca pegues una clave de API en la conversación. - Ejecuta
lingo initylingo link. Si el proyecto ya tiene traducciones, las revisa en busca de marcadores de posición dañados, texto sin traducir y términos incoherentes, y corrige solo lo que apruebes. - Muestra el plan y un
lingo push --estimate, y traduce cuando das tu aprobación. - Registra los nuevos idiomas en la aplicación y te ofrece conectar la GitHub App.
Conecta la GitHub App #
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 lo está, comprueba que la GitHub App tenga acceso al repositorio y, si no lo tiene, te da enlaces para solucionarlo. Te permite elegir si la aplicación traduce después de fusionar los cambios o en las solicitudes de cambios, y solo abre la solicitud de cambios 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:
<!-- 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.mdse crea si no existe. El texto fuera de los marcadores se conserva, y las ejecuciones posteriores sustituyen solo el texto que hay entre ellos.- Si ya existe un
CLAUDE.md, también se le añade el bloque, salvo que importe unAGENTS.mdque ya lo contenga (@AGENTS.md). Nunca se creaCLAUDE.md. - El archivo se deja sin cambios y se muestra una advertencia si no se puede leer, apunta fuera del proyecto o contiene marcadores sin pareja. Corrige el archivo y vuelve a ejecutar
lingo agent setup. - 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 indicándole que ejecute lingo agent setup -y. Esta línea nunca se muestra a las personas ni a los sistemas de CI.
lingo agent setup #
lingo agent setupComprueba si los agentes de programación de este equipo (Claude Code, Codex y Cursor, además de aquel en el que se ejecuta) tienen el MCP server de Lingo.dev e indica qué archivo de configuración hay que modificar para cada agente que no lo tenga. Nunca modifica la configuración de los agentes; añade el servidor siguiendo los pasos de Configuración de MCP. Dentro de un proyecto, también escribe el bloque AGENTS.md tras pedir confirmación.
| Opción | Efecto |
|---|---|
--client <name> | Comprueba solo este agente, aunque no se haya detectado: claude-code, codex o cursor. Se puede repetir. |
--dry-run | Muestra qué cambiaría sin escribir nada. |
--status | Muestra qué está configurado para los agentes detectados. Ignora --client. |
-y, --yes | Escribe el bloque sin preguntar. |
Si no hay ningún agente que comprobar, falla sin escribir nada.
lingo agent-guide #
lingo agent-guide # the agent guide and the list of guides
lingo agent-guide setup # one guideSi no se indica un nombre, muestra la guía con la que empieza cada agente (CLI o MCP, inicio de sesión, configuración inicial pendiente) y enumera las guías. Si se indica un nombre, muestra la guía correspondiente. Si el nombre no se reconoce, finaliza con el código 1 y enumera las guías disponibles en esta versión. lingo guide ofrece las guías a quienes usan @lingo.dev/react.
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. Ese agente realiza 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 usar 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 finaliza con el código 9 si alguien debe intervenir (no quedan créditos, se ha alcanzado el límite del motor o falta una función del plan) y con el código 75 si se ha agotado la cuota diaria de tokens. Muestra el motivo y el 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, el nombre del agente y la organización y el motor vinculados. La CLI elimina las credenciales y los valores secretos y limita cada texto a 500 caracteres. 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).