Ajouter une langue

Ajouter une langue, c'est un changement de configuration d'une ligne plus une exécution. verbatra voit la nouvelle locale comme manquant de tout et la remplit complètement ; tes locales existantes ne coûtent rien, parce que le fichier de verrouillage les a toujours enregistrées comme à jour.

Ajoute la locale à ta configuration

Ajoute-la à targetLocales dans verbatra.config.ts :

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

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

Deux règles, toutes deux imposées au chargement de la configuration : une locale cible ne doit pas être la sourceLocale, et deux entrées ne doivent pas entrer en collision sans tenir compte de la casse (pas de de et DE dans la même liste).

Prévisualise le travail

Avant de dépenser un token, regarde ce qu'une exécution ferait. diff est en lecture seule et liste les clés en attente par locale :

verbatra diff

La nouvelle locale n'a pas encore de fichier cible, donc verbatra la traite comme vide et chaque clé source apparaît comme manquante ; tes locales existantes ne listent rien, en supposant que leurs chaînes source n'ont pas changé. diff sort avec 1 tant que des changements sont en attente, 0 dès qu'il n'y en a plus. verbatra translate --dry-run te donne la même prévisualisation sous la forme d'un résumé d'exécution, sans appel fournisseur ni écriture.

Traduis

verbatra translate

L'exécution traduit chaque clé source dans la nouvelle locale et écrit le fichier à ton files.pattern (ici locales/fr.json). Une grosse source est découpée en sous-lots d'au plus 50 clés par requête fournisseur (configurable avec maxBatchSize), pour qu'une requête trop grosse ne puisse pas couler toute la locale.

C'est le comportement incrémental à l'œuvre : seule la nouvelle locale déclenche des appels fournisseur. Pour chaque locale existante, verbatra compare la source avec la référence de cette locale dans verbatra.lock.json, ne trouve aucune clé manquante ou modifiée, et n'envoie rien. Ensuite, verbatra check sort avec 0 : chaque locale, y compris la nouvelle, est synchronisée.

Langues avec plus de catégories de pluriel

Certaines langues ont besoin de plus de catégories de pluriel CLDR que ta source n'en a. L'anglais en a deux (one et other) ; le polonais, l'arabe et le russe en ont plus. Par défaut, verbatra traduit les formes plurielles qu'il trouve dans la source et n'invente pas les formes supplémentaires : l'exécution réussit quand même et émet un avis par locale (code PLURAL_CATEGORIES_INCOMPLETE) nommant les catégories manquantes.

Pour que verbatra synthétise les formes manquantes à la place, définis generatePlurals: true dans ta configuration :

export default defineConfig({
  // ...
  generatePlurals: true,
});

La génération n'est prise en charge que pour les projets i18next-JSON traduits par un fournisseur LLM ; DeepL, les autres formats et les langues cibles inconnues retombent sur l'avis et ne font jamais échouer l'exécution. Les formes générées passent les mêmes contrôles d'intégrité que toute traduction et sont rapportées séparément des clés traduites dans le résumé d'exécution.

Maintenir la locale source

Tu ne maintiens jamais à la main que la locale source. Pour ajouter des chaînes, mets-les dans le fichier source et relance translate : verbatra les remplit dans chaque cible, y compris celle que tu viens d'ajouter.

Ensuite

• Le fichier de verrouillage : pourquoi relancer ne coûte rien et quoi commiter.
• Fichier de configuration : le schéma complet de configuration, y compris glossary et tone.
• Fournisseurs : les options des fournisseurs et où obtenir une clé.