Ta première traduction

Cinq étapes te mènent d'un projet vide à un fichier de locale traduit. Il te faut seulement Node.js >=22.14.0 et une clé d'API pour un fournisseur une fois que tu veux traduire pour de vrai. Les trois premières étapes ne coûtent rien et ne demandent aucun compte.

1. Installe

verbatra est une dépendance de développement :

npm install --save-dev @verbatra/cli

pnpm et yarn fonctionnent aussi. Le paquet fournit le binaire verbatra ; lance-le via ton gestionnaire de paquets (npx verbatra ..., pnpm verbatra ... ou yarn verbatra ...). Les blocs de code ci-dessous utilisent le nom nu.

pnpm demande une étape de plus. pnpm add -D @verbatra/cli installe correctement mais sort en 1 avec ERR_PNPM_IGNORED_BUILDS, et laisse un pnpm-workspace.yaml sans réponse qui fait échouer de la même façon toutes les commandes pnpm suivantes du projet. Lance pnpm approve-builds une fois sans approuver aucune des deux entrées, ou consulte le Dépannage pour la solution non interactive.

2. Génère une configuration

verbatra init --provider gemini

Avec un terminal attaché, init demande tout ce que tu n'as pas passé en option, chaque question avec une valeur par défaut :

• le fournisseur : anthropic, openai, gemini ou deepl (option --provider, la seule entrée sans défaut)
• la locale source, par défaut en (--source)
• les locales cibles, séparées par des virgules, par défaut de (--targets)
• le motif des fichiers de locale, par défaut locales/{locale}.json (--path)

Passe --yes pour sauter les questions et prendre les valeurs par défaut. Sans terminal (en CI, par exemple) init ne demande jamais rien ; il utilise les défauts et n'exige que --provider.

init écrit trois choses :

• verbatra.config.ts : la configuration de ton projet, validée contre le vrai schéma avant d'être écrite
• .env.example : nomme la variable de clé du fournisseur, jamais une valeur de clé
• des entrées .gitignore pour .env, .env.local, .verbatra-local/ et verbatra.cache.json, créées ou ajoutées pour qu'une vraie clé, l'état local ou le cache regénérable ne finisse jamais dans un commit

Relancer init saute les fichiers qui existent déjà ; --force les écrase. Il pré-remplit aussi format en regardant tes dépendances : un projet utilisant i18next, vue-i18n, next-intl ou @ngx-translate/core reçoit le format JSON correspondant, tout le reste prend i18next-json par défaut avec un commentaire TODO pour le changer. Pour Gemini, le fichier généré ressemble à ceci :

import { defineConfig } from "@verbatra/cli";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de"],
  format: "i18next-json",
  files: {
    pattern: "locales/{locale}.json",
  },
  provider: {
    id: "gemini",
    options: {
      model: "gemini-2.5-flash",
      maxOutputTokens: 4096,
    },
  },
});

3. Prévisualise sans clé d'API

Si tu n'as pas encore de fichier source, crée-en un au motif configuré, par exemple locales/en.json :

{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}

Prévisualise maintenant l'exécution :

verbatra translate --dry-run

Un dry run ne construit aucun fournisseur, il ne demande donc aucune clé d'API et ne peut rien dépenser. Il lit tes fichiers, les compare et affiche le même résumé par locale qu'une vraie exécution, sans envoyer une seule chaîne ni écrire un seul fichier. Utilise-le pour vérifier le format, le motif de fichiers et les locales avant de t'inscrire où que ce soit.

verbatra check et verbatra diff se passent aussi du fournisseur : check signale les compteurs par locale, diff liste les clés exactes.

4. Définis ta clé d'API

Les clés viennent de l'environnement, jamais du fichier de configuration. Chaque fournisseur hébergé lit exactement une variable ; pour Gemini c'est GEMINI_API_KEY. Copie l'exemple généré et renseigne ta clé :

cp .env.example .env

Puis ouvre .env et colle ta clé après GEMINI_API_KEY=. translate, watch et studio chargent .env.local puis .env depuis le répertoire de travail avant une exécution, et une variable déjà définie dans ton shell gagne toujours. Voir Fournisseurs pour la variable de chaque fournisseur.

5. Traduis

Une fois la clé en place, lance la même commande pour de vrai :

verbatra translate

verbatra lit la locale source, voit que chaque clé manque dans de, les envoie au fournisseur par lots, passe chaque résultat par la barrière d'intégrité, et écrit locales/de.json. L'exécution se termine par un résumé par locale : clés traduites, clés inchangées, clés orphelines, et les éventuels avis. Le code de sortie est 0 quand chaque locale est ressortie complète et 1 quand une a échoué ou est ressortie partielle (écrite, mais avec des clés toujours manquantes) ; ajoute --json pour un résumé lisible par machine.

Ce qui vient de se passer

Trois choses sont maintenant sur le disque :

• locales/de.json : le fichier de la locale cible. Il a les mêmes clés que ta source, dans le même ordre de document, et {{name}} a survécu intact à la traduction ; un résultat qui l'aurait perdu aurait été retenu, pas écrit.

• verbatra.lock.json : le fichier de verrouillage. Pour chaque locale cible, il associe chaque clé traduite au hash de la chaîne source dont cette traduction provient :

  {
    "version": 1,
    "locales": {
      "de": {
        "cart.empty": "<source content hash>",
        "greeting": "<source content hash>"
      }
    }
  }

• .verbatra-local/ : l'état local au processus (l'instantané de statut d'exécution et les verrous d'écriture par locale). init l'a ajouté au .gitignore ; ne le commite jamais.

Le fichier de verrouillage est la référence de chaque exécution future. Relance verbatra translate sans rien modifier et rien n'est envoyé : chaque clé est déjà à jour. Modifie une seule chaîne source et seule cette clé est retraduite.

Ensuite

• Ajouter une langue : ajoute une nouvelle locale cible à cette installation.
• Comment ça marche : le pipeline complet derrière une exécution.
• Fichier de configuration : tout ce que verbatra.config.ts peut contenir.