Configura con un agente de programación
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 que aparecen 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 con 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 cualquier contenido, 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. Un agente en la nube o en CI omite este paso y el inicio de sesión en el navegador; consulta Sesiones sin intervención humana.
- Identifica las tecnologías del proyecto, encuentra todos los archivos de origen que carga la aplicación y ejecuta la guía correspondiente a esas tecnologías (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 solicite; 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 aplica solo las correcciones que aceptes. - Te muestra el plan y una
lingo push --estimate, y traduce solo después de que des 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 está configurado, verifica que la GitHub App pueda acceder al repositorio y te proporciona enlaces para resolver cualquier problema. Te permite elegir si la GitHub App traduce después de una fusión o en solicitudes de cambios, y abre la solicitud de cambios con la configuración solo después de que des 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 todas las sesiones posteriores del agente sepan que deben leer las guías antes de trabajar en la 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. El texto fuera de los marcadores se conserva, y las ejecuciones posteriores reemplazan solo el texto entre ellos. - Si ya existe un
CLAUDE.md, también se le agrega 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, si enlaza a una ubicación fuera del proyecto o si sus marcadores no están emparejados. Corrige el archivo y vuelve a ejecutar
lingo agent setup; agrega--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 tiene el bloque, la CLI imprime una línea en stderr que le indica que ejecute lingo agent setup -y. Esa línea nunca se muestra a las personas ni en CI.
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 está ejecutando el comando) tienen el MCP server de Lingo.dev e indica qué archivo de configuración se debe modificar para cada agente 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, pero no escribe nada. |
--status | Muestra lo que está configurado para los agentes detectados. Ignora --client. |
-y, --yes | Escribe el bloque sin preguntar. |
Sin --status, falla sin escribir nada si no hay ningún agente que verificar; en ese caso, especifica uno con --client.
lingo agent-guide #
lingo agent-guide # the agent guide and the list of guides
lingo agent-guide setup # one guideSin un nombre, imprime la guía con la que comienza cada agente (CLI o MCP, inicio de sesión y configuración inicial pendiente) y enumera las guías. Con un nombre, imprime esa guía. Si el nombre es desconocido, termina con el código 1 y enumera las guías disponibles en esta versión. Las personas que 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 en CI, establece LINGO_API_KEY para que el agente no necesite iniciar sesión. Ese agente se encarga de la parte de la tarea que usa 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 una persona debe intervenir (no quedan 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ó el cupo diario de tokens. Imprime 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 oraciones, lo que propuso el agente, el nombre del agente 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 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).