Aller au contenu
Aller au contenu

Docs / Démarrer

Page traduite automatiquement

Cette page a été traduite automatiquement, elle peut donc contenir des erreurs ou se lire un peu bizarrement. La version anglaise fait foi. Lire l’original en anglais.

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

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

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 associe à chaque stack son id de format et sa structure ; Formats 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

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

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 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'erreurFais ceci
0Compare 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_AMBIGUOUSChoisis 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_OPTIONSLe message nomme chaque option encore nécessaire.
2, CONFIG_EXISTSDis à 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 documente chaque option.

4. Laisser la clé d'API à l'humain

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

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

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

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

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.

Ensuite

Modifier sur GitHub

Sur cette page