Aperçu
La commande verbatra : ses dix sous-commandes, les options partagées, la lecture de l'environnement et le contrat des codes de sortie.
Page traduite automatiquement
@verbatra/cli fournit le binaire verbatra, une surcouche légère de @verbatra/sdk. Dix commandes font le travail :
| Commande | Rôle |
|---|---|
init | crée une config verbatra et un .env.example pour ce projet |
translate | traduit chaque locale cible une fois, puis termine |
watch | retraduit à chaque changement de la source jusqu'à interruption |
check | signale les clés manquantes ou obsolètes par locale, en lecture seule |
diff | liste les clés exactes qui seraient ajoutées, retraduites ou orphelines par locale, en lecture seule |
doctor | valide la configuration du projet et signale tous les problèmes d'un coup, sans appeler de fournisseur |
export | exporte les chaînes non traduites pour un traducteur humain, en classeur Excel ou en un fichier CSV ou TSV par locale |
import | réimporte un classeur rempli ou un fichier délimité dans les fichiers de locale |
studio | démarre Verbatra Studio, le tableau de bord local de traduction |
mcp | démarre un serveur MCP en stdio qui expose les outils de verbatra à un client MCP |
Installation et invocation
Installe @verbatra/cli comme dépendance de développement, puis lance le binaire via ton gestionnaire de paquets :
| Gestionnaire de paquets | Installation | Lancement |
|---|---|---|
| npm | npm install --save-dev @verbatra/cli | npx verbatra <command> |
| pnpm | pnpm add -D @verbatra/cli | pnpm verbatra <command> (ou pnpm exec verbatra <command>) |
| yarn | yarn add -D @verbatra/cli | yarn verbatra <command> |
| bun | bun add -d @verbatra/cli | bun run verbatra <command> |
Il te faut Node.js >=22.14.0.
Tu veux essayer une commande avant d'installer ? npx @verbatra/cli <command> (npm) ou pnpm dlx @verbatra/cli <command> (pnpm) fonctionnent tous les deux sans installation locale préalable.
Conventions partagées
--cwd <path>résout la config et les fichiers de locale depuis ce répertoire au lieu du répertoire courant. Toutes les commandes l'acceptent.--config <path>charge ce fichier de config au lieu d'en chercher un. Toutes les commandes saufinitl'acceptent ; l'ordre de recherche est décrit dans Le fichier de configuration.--jsonaffiche une enveloppe lisible par machine sur stdout, une ligne par enregistrement, et garde stdout propre pour le piping.- Branche-toi sur son champ
ok: un succès porte les données de la commande sousresult, et une exécution échouée porte le même code d'erreur stable que nomme la ligne stderr. La ligne d'erreur lisible par un humain va sur stderr dans les deux cas. translate,watch,check,diff,doctor,exportetimportle prennent en charge ;init,studioetmcpnon.mcpn'écrit jamais rien sur stdout, puisque stdout est le canal du protocole MCP ; voirverbatra mcp.
- Branche-toi sur son champ
--helpet--versionaffichent leur sortie et terminent avec0. Une commande ou une option inconnue termine avec2.
Fichiers d'environnement
translate, watch, doctor, studio et mcp chargent .env.local puis .env depuis le répertoire de travail avant de s'exécuter. Une variable déjà définie dans ton environnement réel l'emporte toujours. Les clés d'API sont lues uniquement depuis l'environnement, jamais depuis le fichier de config ni une option : voir Fournisseurs. Les commandes en lecture seule (check, diff) et les commandes de passation (export, import) n'appellent jamais de fournisseur et ne chargent aucun fichier .env.
Codes de sortie
Le code de sortie est le contrat sur lequel une étape CI ou un script se branche :
| Code | Signification |
|---|---|
0 | succès (aussi --help et --version) |
1 | translate ou import a terminé mais certaines locales ont échoué ou sont ressorties partielles, check a trouvé une locale désynchronisée, diff a trouvé des changements en attente, ou doctor a trouvé un problème de configuration |
2 | impossible de s'exécuter : une erreur globale (config, source, fournisseur, verrou) ou une erreur d'utilisation |
130 | watch, studio ou mcp a été arrêté de force par une seconde interruption |
Chaque page de commande détaille comment ces codes s'y appliquent. Voir CI et codes de sortie pour les brancher dans un pipeline.
Edit on GitHub