Configurer avec un agent de programmation

Laissez Claude Code, Codex ou Cursor configurer Lingo.dev dans votre projet grâce aux guides de la CLI destinés aux agents : instructions à copier, bloc AGENTS.md, lingo agent setup et lingo agent-guide.

La CLI fournit des guides conçus pour les agents de programmation comme Claude Code, Codex et Cursor. Donnez à votre agent l'une des instructions ci-dessous. Il exécute lingo agent-guide, lit le guide correspondant à la tâche et effectue 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 toute traduction, il vous présente un plan et une estimation, puis attend votre accord.

Instructions #

Depuis la racine du projet, collez une instruction dans votre agent.

Configurer Lingo.dev en partant de zéro #

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

L'agent :

  1. 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 l'instruction.
  2. Identifie les technologies utilisées, repère tous les fichiers sources chargés par l'application et exécute le guide correspondant (Rails, iOS, Android, Markdoc, e-mails, bibliothèque i18n ou site de documentation).
  3. Vous demande de vous connecter. Exécutez npx @lingo.dev/cli@latest login dans votre propre terminal lorsqu'il vous le demande ; ne collez jamais de clé API dans la conversation.
  4. Exécute lingo init et lingo link. Si le projet contient déjà des traductions, il recherche les variables de substitution incorrectes, les textes non traduits et les incohérences terminologiques, puis n'applique que les corrections que vous acceptez.
  5. Vous présente le plan et un lingo push --estimate, puis traduit après votre accord.
  6. Enregistre les nouvelles langues dans l'application et vous propose de connecter la GitHub App.

Connecter 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.

L'agent configure d'abord le projet si ce n'est pas déjà fait. Il vérifie que la GitHub App a accès au dépôt et, si ce n'est pas le cas, vous fournit les liens nécessaires pour y remédier. Il vous laisse choisir si la GitHub App traduit après la fusion ou dans les pull requests, puis 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. Ainsi, lors de chaque session ultérieure, l'agent sait qu'il doit lire les guides avant tout travail de localisation :

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 -->
  • AGENTS.md est créé s'il n'existe pas. Le texte en dehors des marqueurs est conservé ; toute exécution ultérieure remplace uniquement le texte situé entre eux.
  • Un fichier CLAUDE.md existant reçoit lui aussi le bloc, sauf s'il importe un AGENTS.md qui le contient déjà (@AGENTS.md). CLAUDE.md n'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 correctement appariés. Corrigez le fichier, puis exécutez à nouveau lingo agent setup.
  • 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 le bloc, la CLI écrit une ligne sur stderr pour lui demander d'exécuter lingo agent setup -y. Cette ligne ne s'affiche jamais pour les personnes ni pour la CI.

lingo agent setup #

bash
lingo agent setup

La commande vérifie si les agents de programmation présents sur cette machine (Claude Code, Codex et Cursor, ainsi que celui dans lequel elle s'exécute) disposent du MCP server de Lingo.dev. Pour chaque agent qui n'en dispose pas, elle indique le fichier de configuration à modifier. Elle ne modifie jamais les configurations 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.

OptionEffet
--client <name>Vérifie uniquement cet agent, même s'il n'a pas été détecté : claude-code, codex ou cursor. Option utilisable plusieurs fois.
--dry-runAffiche ce qui changerait, sans rien écrire.
--statusAffiche ce qui est configuré pour les agents détectés. Ignore --client.
-y, --yesÉcrit le bloc sans demander d'accord.

S'il n'y a aucun agent à vérifier, la commande échoue sans rien écrire.

lingo agent-guide #

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

Sans nom, affiche le guide par lequel chaque agent commence (CLI ou MCP, connexion, configuration initiale inachevée), ainsi que la liste des guides. Avec un nom, affiche le guide correspondant. Si le nom est inconnu, quitte avec le code 1 et affiche les guides disponibles dans cette version. lingo guide fournit les guides aux personnes qui utilisent @lingo.dev/react.

Sessions sans intervention humaine #

Dans une session cloud ou CI, définissez LINGO_API_KEY pour que l'agent n'ait pas besoin de se connecter. Cet agent effectue la partie CLI de la tâche et ne configure pas le MCP server. Son dernier message liste les opérations restantes qui nécessitent l'utilisation du compte. Vous pouvez les terminer dans l'application web ou avec un agent disposant du MCP server.

Lorsqu'une traduction est refusée pour des raisons de facturation, la CLI se termine avec le code 9 si une intervention humaine est nécessaire (crédits épuisés, limite du moteur atteinte ou fonctionnalité non disponible dans l'offre), et avec le code 75 si le quota quotidien de jetons est épuisé. Elle affiche la raison et le 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 un court rapport à Lingo.dev avec lingo agent report lorsqu'une étape échoue et lorsqu'une tâche se termine, afin de nous aider à améliorer les guides. Ce rapport contient le guide et l'étape concernés, un résumé d'une ou deux phrases, le nom de l'agent, ainsi que l'organisation et le moteur associés. La CLI supprime les identifiants et les valeurs secrètes, et limite chaque texte à 500 caractères. L'envoi d'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).