Ta première traduction

Quatre é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.

1. Installe

verbatra est une dépendance de développement :

pnpm add -D @verbatra/cli

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

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 et .verbatra-local/, créées ou ajoutées pour qu'une vraie clé ou l'état local 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. 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=. verbatra charge .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.

4. Traduis

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."
  }
}

Puis lance :

verbatra translate

verbatra lit la locale source, voit que chaque clé manque dans de, les envoie au fournisseur par lots, vérifie l'intégrité des placeholders et l'intégrité ICU de chaque résultat, 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 a réussi et 1 quand une a échoué ; 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. Pour prévisualiser n'importe quelle exécution sans appel fournisseur ni la moindre écriture, utilise verbatra translate --dry-run.

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.