---
title: "Configure verbatra avec un agent IA"
description: "Un prompt court pour qu'un agent IA de code ajoute verbatra à un projet qui a déjà une configuration i18n, avec une confirmation humaine avant toute dépense."
type: "tutorial"
---
# Configure verbatra avec un agent IA

Un prompt court pour qu'un agent IA de code ajoute verbatra à un projet qui a déjà une configuration i18n, avec une confirmation humaine avant toute dépense.

Cette page s'adresse à un projet qui a déjà des fichiers de locale commités. Colle le **Prompt pour agents IA** ci-dessus dans Claude Code, Codex, Gemini CLI, Cursor ou tout agent qui exécute des commandes shell. Il suit les étapes ci-dessous et te demande trois choses :

- **Quel fournisseur** utiliser, sauf si le projet le rend évident.
- **La clé d'API** : l'agent laisse sa variable vide dans `.env` pour que tu la remplisses et ne demande jamais la clé.
- **Le feu vert** avant le premier vrai `translate`, qui dépense aussitôt.

## Les étapes que suit l'agent [#les-étapes-que-suit-lagent]

Agent : suis ces étapes dans l'ordre et ne saute jamais l'arrêt de l'étape 6.

### 1. Examiner la configuration existante [#1-examiner-la-configuration-existante]

Avant de modifier quoi que ce soit, trouve la bibliothèque i18n dans `package.json` (comme `i18next`, `vue-i18n` ou `next-intl`) et les fichiers de locale. Note la locale source, chaque locale cible déjà présente et le motif de chemin avec un jeton `{locale}`, comme `locales/{locale}.json`. [Choisis ta stack](https://verbatra.kreitz-webdev.de/fr/docs/pick-your-stack.md) associe à chaque stack son id de format et sa structure ; [Formats](https://verbatra.kreitz-webdev.de/fr/docs/formats.md) indique quels fichiers doivent déjà exister. Du JSON sans bibliothèque i18n : des marqueurs `{{name}}` signifient `i18next-json`, une accolade simple `{name}` signifie `vue-i18n-json`.

### 2. Installer la CLI [#2-installer-la-cli]

```bash
npm install --save-dev @verbatra/cli
```

pnpm, yarn et bun fonctionnent aussi. N'approuve aucun script d'installation, ni dans `pnpm approve-builds` ni dans `allowScripts` de npm : verbatra n'en a besoin d'aucun.

### 3. Créer la config et les fichiers de l'agent [#3-créer-la-config-et-les-fichiers-de-lagent]

```bash
npx @verbatra/cli init --provider <provider> --yes --json --agent
```

Demande à l'humain quel fournisseur utiliser, sauf si le projet le rend évident. Ne choisis jamais un fournisseur qui dépense sur un service que l'humain n'a pas accepté, et ne passe jamais une valeur de clé à `init`. [Fournisseurs](https://verbatra.kreitz-webdev.de/fr/docs/providers.md) liste les ids ; `none` désactive la traduction automatique. `init` détecte le format, le motif de chemin et les locales, affiche une enveloppe JSON et ne pose jamais de question. `--agent` écrit en plus une section verbatra dans `AGENTS.md` (ou dans `CLAUDE.md` quand c'est le seul fichier d'instructions ou qu'il contient déjà la section verbatra) et le serveur MCP verbatra, dépenses désactivées, dans la config de chaque client détecté, le `.mcp.json` de Claude Code quand il trouve Claude Code ou aucun client ; `result.agent.clients` liste les fichiers.

| Code de sortie et code d'erreur | Fais ceci |
| --- | --- |
| `0` | Compare `result.config` avec l'étape 1, en commençant par chaque entrée de `result.sources` qui indique `default` ; `result.config.files.localeStyle` n'apparaît que si les fichiers n'écrivent pas les locales telles quelles. Si quelque chose ne va pas, relance-la avec le bon `--format`, `--path`, `--source` ou `--targets`, plus `--force`. |
| `2`, `FORMAT_AMBIGUOUS` ou `LAYOUT_AMBIGUOUS` | Choisis parmi les `candidates` et relance-la avec `--format` ou `--path`. Des fichiers de namespace côte à côte : arrête-toi et demande à l'humain, car une config couvre un seul motif de fichier. |
| `2`, `MISSING_OPTIONS` | Le message nomme chaque option encore nécessaire. |
| `2`, `CONFIG_EXISTS` | Dis à l'humain quel fournisseur la config existante utilise et attends sa confirmation. Lance ensuite `npx @verbatra/cli init --agent --json`, qui garde la config et n'ajoute que les fichiers de l'agent. Demande avant de passer `--force`. |

[init](https://verbatra.kreitz-webdev.de/fr/docs/cli/init.md#fournisseurs) documente chaque option.

### 4. Laisser la clé d'API à l'humain [#4-laisser-la-clé-dapi-à-lhumain]

Saute cette étape avec le fournisseur `none`. La variable de clé est dans `result.apiKeyEnvVar` ; après `CONFIG_EXISTS` elle vaut `null`, alors prends le nom dans la vérification `api-key` en échec de `npx @verbatra/cli doctor --json`. Copie `.env.example` vers `.env`, ou crée `.env` si `init` n'a écrit aucun exemple, nommes-y la variable avec une valeur vide et dis à l'humain de la remplir. N'écris, n'invente ni ne demande jamais une valeur de clé. Continue sans attendre.

### 5. Vérifier la configuration sans dépenser [#5-vérifier-la-configuration-sans-dépenser]

```bash
npx @verbatra/cli doctor --json
npx @verbatra/cli check --json
npx @verbatra/cli diff --json
npx @verbatra/cli translate --dry-run --json
```

Aucune de ces commandes n'appelle de fournisseur, ne demande de clé ni n'écrit de fichier. Corrige chaque vérification de `doctor` en échec que tu peux corriger dans `verbatra.config.ts` ; la vérification `api-key` ne passe qu'une fois que l'humain a défini la clé, alors ne boucle pas dessus. Pour `check` ou `diff`, la sortie `1` (non synchronisé) est attendue avant une première exécution ; seule la sortie `2` signale un problème de configuration. Avec le fournisseur `none`, `translate --dry-run` sort avec `3` quand des clés restent pour un traducteur humain. Seules les clés absentes de la cible sont traduites, et une chaîne vide compte comme présente, alors demande avant de supprimer des clés de remplissage `""`.

### 6. S'arrêter et demander [#6-sarrêter-et-demander]

Résume combien de clés sont en attente par locale et ce que `translate --dry-run` a indiqué, puis arrête-toi. Une vraie exécution dépense tout de suite et n'a pas de confirmation propre, alors attends le feu vert explicite de l'humain. N'utilise jamais `--prune` sauf si l'humain l'a demandé.

### 7. Traduire après le feu vert [#7-traduire-après-le-feu-vert]

```bash
npx @verbatra/cli translate --json
```

Rapporte les listes `succeeded`, `partial` et `failed` du résumé. Une locale `partial` ou `failed` garde ce qui a réussi.

### 8. Commiter et connecter [#8-commiter-et-connecter]

Commite `verbatra.config.ts`, `.env.example` s'il existe, le fichier d'instructions et les configs client de l'étape 3, `verbatra.lock.json`, `verbatra.provenance.json` une fois qu'une exécution l'a écrit, et les fichiers de locale traduits. Ne commite jamais `.env`, `.env.local`, `.verbatra-local/` ni `verbatra.cache.json` ; vérifie que le `.gitignore` les couvre.

Dis ensuite à l'humain de redémarrer son client et d'approuver le serveur `verbatra` du projet. Dans Claude Code, n'installe pas en plus le plugin verbatra, qui l'enregistre une deuxième fois ; `claude mcp list` montre la connexion. Un client que `init` n'a pas détecté prend son unique entrée dans [Connecter un client MCP](https://verbatra.kreitz-webdev.de/fr/docs/connect-an-mcp-client.md).

## Ensuite [#ensuite]

<Cards>
  <Card title="Connecter un client MCP" href="https://verbatra.kreitz-webdev.de/fr/docs/connect-an-mcp-client.md" description="L'unique entrée dont a besoin chaque client autre que Claude Code, et comment laisser l'agent dépenser." />
  <Card title="Recettes pour agents et scripts" href="https://verbatra.kreitz-webdev.de/fr/docs/agent-recipes.md" description="L'enveloppe --json et les codes de sortie sur lesquels s'appuient les commandes de ce prompt, pour construire tes propres boucles d'agent par-dessus." />
  <Card title="Piloter Studio avec un agent de navigateur" href="https://verbatra.kreitz-webdev.de/fr/docs/agent-tools-in-studio.md" description="Une surface différente, pour piloter un projet déjà configuré depuis un onglet de navigateur plutôt que depuis un shell." />
  <Card title="Démarrage rapide" href="https://verbatra.kreitz-webdev.de/fr/docs/quickstart.md" description="Le même parcours de configuration, écrit pour une personne plutôt que pour un agent." />
  <Card title="Le fichier de verrouillage" href="https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md" description="Tout le détail derrière le comportement de sécurité d'adoption sur lequel s'appuie ce prompt." />
</Cards>
