Configuración 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 listas para copiar, el bloque AGENTS.md, lingo agent setup y lingo agent-guide.
La CLI incluye guías escritas para agentes de programación como Claude Code, Codex y Cursor. Dale a tu agente una de las instrucciones de abajo. 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, 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 #
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.El agente:
- Verifica que tenga las herramientas MCP de Lingo.dev. Si no las tiene, agrega el servidor y te pide que lo reinicies y vuelvas a pegar la instrucción.
- Identifica las tecnologías del proyecto, encuentra 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).
- Te pide que inicies sesión. Ejecuta
npx @lingo.dev/cli@latest loginen tu propia 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 para detectar marcadores de posición dañados, texto sin traducir y términos inconsistentes, y corrige solo lo que apruebes. - Muestra el plan y un
lingo push --estimate, y traduce solo después de que lo apruebes. - 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 primero configura el proyecto si aún no lo está. Verifica que la GitHub App tenga acceso al repositorio y, si no lo tiene, te da enlaces para resolverlo. Te permite elegir si la aplicación traduce después de fusionar los cambios o en las solicitudes de cambios, y abre la solicitud de cambios con la configuración solo 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 cada sesión posterior del 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 -->- Se crea
AGENTS.mdsi no existe. Se conserva el texto fuera de los marcadores, y las ejecuciones posteriores reemplazan solo el texto entre ellos. - Si
CLAUDE.mdya existe, también recibe el bloque, a menos que importe unAGENTS.mdque ya lo tenga (@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 tiene marcadores que no forman pares. 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 tiene el bloque, la CLI imprime una línea en stderr que le indica que ejecute lingo agent setup -y. Las personas y los sistemas de CI nunca la ven.
lingo agent setup #
lingo agent setupVerifica si los agentes de programación de esta máquina (Claude Code, Codex y Cursor, además del agente en el que se ejecuta) tienen el 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; agrega el servidor siguiendo los pasos de Configuración de MCP. Dentro de un proyecto, también escribe el bloque AGENTS.md después de pedir confirmación.
| Opción | Efecto |
|---|---|
--client <name> | Verifica solo este agente, aunque no se haya detectado: claude-code, codex o cursor. Se puede repetir. |
--dry-run | Muestra lo que cambiaría sin escribir nada. |
--status | Muestra lo que está configurado para los agentes detectados. Ignora --client. |
-y, --yes | Escribe el bloque sin pedir confirmación. |
Si no hay ningún agente que verificar, 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 especifica un nombre, muestra la guía con la que comienza cada agente (CLI o MCP, inicio de sesión, configuración inicial pendiente) y la lista de guías. Si se especifica un nombre, muestra esa guía. Si el nombre no se reconoce, finaliza con el código 1 y muestra 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 termina con el código 9 si una persona debe intervenir (se agotaron los créditos, se alcanzó el límite del motor o falta una función del plan) y con el código 75 si se agotó la cuota diaria de tokens. Imprime 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 contiene la guía y el paso, un resumen de una o dos oraciones, 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 hace 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).