Configurer Lingo.dev avec un agent de programmation
La CLI fournit des guides conçus pour les agents de programmation comme Claude Code, Codex et Cursor. Donnez à votre agent l’un des prompts ci-dessous. Il exécute lingo agent-guide, lit le guide correspondant à la tâche et réalise le travail dans votre dépôt à l’aide de la CLI. Les opérations liées au compte, comme le glossaire du moteur ou la connexion à la GitHub App, passent par le MCP server de Lingo.dev.
Les guides sont fournis avec la CLI : l’agent lit donc toujours le guide correspondant à la version qu’il utilise. Avant de traduire quoi que ce soit, il vous présente un plan et une estimation, puis attend votre accord.
Prompts #
Depuis la racine du projet, collez un prompt dans votre agent.
Configurer Lingo.dev en partant de zéro #
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.L’agent :
- Vérifie qu’il dispose des outils MCP de Lingo.dev. Sinon, il ajoute le serveur et vous demande de le redémarrer, puis de coller à nouveau le prompt. Un agent dans le cloud ou en CI saute cette étape ainsi que la connexion via le navigateur ; consultez Sessions sans intervention humaine.
- Identifie les technologies du projet, trouve tous les fichiers sources chargés par l’application et suit le guide adapté (Rails, iOS, Android, Markdoc, e-mails, bibliothèque i18n ou site de documentation).
- Vous demande de vous connecter. Exécutez
npx @lingo.dev/cli@latest logindans votre propre terminal lorsqu’il vous le demande ; ne collez jamais de clé API dans la conversation. - Exécute
lingo initetlingo link. Si le projet contient déjà des traductions, il y recherche les variables de substitution incorrectes, le texte non traduit et les incohérences terminologiques, puis ne corrige que ce que vous acceptez. - Vous présente le plan et un
lingo push --estimate, puis traduit après votre accord. - Enregistre les nouvelles langues dans l’application et propose de connecter la GitHub App.
Connecter la GitHub App #
Connect the Lingo.dev GitHub App to this repository. Run npx @lingo.dev/cli@latest agent-guide github and follow it.L’agent configure d’abord le projet si ce n’est pas déjà fait, vérifie que la GitHub App peut accéder au dépôt et vous fournit des liens pour résoudre les éventuels problèmes. Il vous laisse choisir si la GitHub App traduit après une fusion ou dans les pull requests, et n’ouvre la pull request contenant la configuration qu’après votre accord.
Le bloc AGENTS.md #
lingo init et lingo agent setup écrivent un court bloc dans AGENTS.md à la racine du projet, pour que l’agent sache, à chaque session suivante, qu’il doit lire les guides avant tout travail de localisation :
<!-- 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.mdest créé s’il n’existe pas. Le texte en dehors des marqueurs est conservé ; les exécutions suivantes ne remplacent que le texte situé entre eux.- Un fichier
CLAUDE.mdexistant reçoit lui aussi le bloc, sauf s’il importe un fichierAGENTS.mdqui le contient (@AGENTS.md).CLAUDE.mdn’est jamais créé. - Le fichier reste inchangé et un avertissement s’affiche s’il est illisible, s’il pointe en dehors du projet ou si ses marqueurs ne sont pas appariés. Corrigez le fichier et exécutez à nouveau
lingo agent setup, en ajoutant--client <name>si votre agent n’est pas détecté. - Pour ne pas ajouter le bloc, exécutez
lingo init --no-agents-md.
Lorsqu’un agent exécute une commande Lingo.dev dans un projet dont le fichier AGENTS.md ou CLAUDE.md ne contient pas de bloc, la CLI affiche une ligne sur stderr lui indiquant d’exécuter lingo agent setup -y. Cette ligne ne s’affiche jamais pour les personnes ni en CI.
lingo agent setup #
lingo agent setupVérifie si les agents de programmation présents sur cette machine (Claude Code, Codex et Cursor, ainsi que l’agent dans lequel la commande s’exécute) disposent du MCP server de Lingo.dev. Pour chacun de ceux qui n’en disposent pas, la commande indique le fichier de configuration à modifier. Elle ne modifie jamais la configuration des agents ; ajoutez le serveur en suivant les étapes de Configuration MCP. Dans un projet, elle écrit aussi le bloc AGENTS.md, après vous avoir demandé votre accord.
| Option | Effet |
|---|---|
--client <name> | Vérifie uniquement cet agent, même s’il n’a pas été détecté : claude-code, codex ou cursor. L’option peut être répétée. |
--dry-run | Affiche les modifications prévues, sans rien écrire. |
--status | Affiche ce qui est configuré pour les agents détectés. Ignore --client. |
-y, --yes | Écrit le bloc sans demander de confirmation. |
Sans --status, la commande échoue sans rien écrire si aucun agent n’est à vérifier ; indiquez-en un avec --client.
lingo agent-guide #
lingo agent-guide # the agent guide and the list of guides
lingo agent-guide setup # one guideSans nom, la commande affiche le guide par lequel chaque agent commence (CLI ou MCP, connexion, configuration initiale inachevée), puis la liste des guides. Avec un nom, elle affiche le guide correspondant. Si le nom est inconnu, elle se termine avec le code 1 et affiche la liste des guides disponibles dans cette version. Les personnes qui utilisent @lingo.dev/react disposent de leurs propres guides sous lingo guide.
Sessions sans intervention humaine #
Pour une session dans le cloud ou en CI, définissez LINGO_API_KEY afin que l’agent n’ait pas besoin de se connecter. Il prend en charge la partie de la tâche qui utilise la CLI et ne configure pas le MCP server. Son dernier message liste les opérations restantes qui nécessitent l’accès au compte ; vous pouvez les terminer dans l’application web ou avec un agent qui dispose du MCP server.
Lorsqu’une traduction est refusée pour des raisons de facturation, la CLI se termine avec le code 9 si une personne doit intervenir (crédits épuisés, limite du moteur atteinte ou fonctionnalité non disponible dans le forfait), et avec le code 75 si le quota quotidien de tokens est épuisé. Elle affiche la raison et un lien vers la page de facturation. Les guides demandent aux agents de s’arrêter dans les deux cas.
Rapports des agents #
Les guides demandent aux agents d’envoyer à Lingo.dev un court rapport avec lingo agent report lorsqu’une étape échoue et lorsqu’une tâche se termine, pour nous aider à améliorer les guides. Le rapport comprend le guide et l’étape, un résumé d’une ou deux phrases, la proposition de l’agent, son nom, ainsi que l’organisation et le moteur associés. La CLI retire les identifiants et les valeurs secrètes du résumé et de la proposition, puis limite chacun à 500 caractères ; les guides demandent aux agents de n’inclure ni code, ni contenu de fichiers, ni secrets dans aucun champ. Un rapport ne fait jamais échouer la tâche, et rien n’est envoyé si personne n’est connecté ou si la télémétrie est désactivée (LINGO_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 ou OTEL_SDK_DISABLED=true).