Exécuter verbatra en CI

Utilise ce guide quand une pipeline doit repérer les fichiers de locale qui ont dérivé de la source, ou les traduire pour toi lors d'un push. Chaque étape exécute la même CLI qu'en local, donc cela fonctionne dans n'importe quel système de CI ; les exemples utilisent GitHub Actions.

Avant de commencer, il te faut :

• @verbatra/cli en dépendance de développement, avec ton lockfile commité. La CLI demande Node ^22.22.0 || >=24.
• Une configuration, des fichiers de locale et un verbatra.lock.json commités.
• Pour traduire uniquement : la clé d'API de ton fournisseur dans le coffre à secrets de la CI.

Si tu utilises GitHub Actions et veux des annotations et un résumé de job sans écrire le job toi-même, prends plutôt la GitHub Action.

Ajouter un contrôle de dériveCopier le lien vers cette section

verbatra check compare la source, les fichiers cibles et le fichier de verrouillage, et sort avec 1 quand une locale a des clés manquantes ou obsolètes. Il n'appelle aucun fournisseur, donc le job n'a besoin d'aucune clé et tourne aussi sur les pull requests venant de forks :

name: i18n
on: pull_request

permissions:
  contents: read

jobs:
  check-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
      - uses: pnpm/action-setup@<commit-sha>
      - uses: actions/setup-node@<commit-sha>
        with:
          node-version: 22
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec verbatra check

Remplace check par verbatra diff quand tu veux les noms des clés derrière la dérive, par exemple pour les publier dans un commentaire de pull request. Il sort avec 1 dans la même condition ; les clés orphelines apparaissent dans sa sortie, mais ne le font jamais échouer à elles seules.

Pour ne contrôler que certaines locales, passe --locales de,fr. Une valeur de --locales qui nomme une locale non configurée sort avec 2, même à côté de locales valides, donc une faute de frappe ne rend jamais le contrôle vert.

Bloquer sur la qualité des traductionsCopier le lien vers cette section

La dérive n'est pas la seule erreur à attraper. Ajoute --qa pour passer aussi le contrôle d'intégrité et les signalements de relecture sur chaque traduction commitée, afin qu'une valeur modifiée à la main avec un placeholder cassé, un balisage cassé ou des branches de pluriel ICU inadaptées fasse échouer le job :

verbatra check --qa

• Ajoute --strict pour échouer aussi sur les avertissements de relecture et les catégories de pluriel manquantes.
• Dans un hook d'édition, verbatra check --file <path> contrôle un seul fichier de locale.

Consulte le contrôle qualité et Un seul fichier. La GitHub Action exécute le même contrôle avec qa: "true".

Bloquer sur les décisions de relectureCopier le lien vers cette section

Ajoute --require-reviewed pour échouer tant qu'une traduction écrite par une machine n'est pas approuvée dans le verbatra.provenance.json commité, le fichier où écrivent la file de relecture de Studio et les outils de relecture MCP :

verbatra check --require-reviewed

Il n'a pas besoin de clé non plus. Les codes qu'il signale sont dans Exiger des traductions relues.

Traduire lors d'un pushCopier le lien vers cette section

Lance verbatra translate et fais passer la clé du fournisseur depuis ton coffre à secrets dans l'environnement de l'étape. La CLI ne prend aucune clé en argument et n'en lit aucune dans la configuration ; Fournisseurs liste la variable que lit chaque fournisseur.

      - run: pnpm exec verbatra translate --json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

• L'étape écrit les fichiers de locale dans le checkout et s'arrête là. Ajoute ta propre étape qui les commite ou ouvre une pull request, et n'accorde contents: write ou pull-requests: write qu'à ce job.
• Pour prévisualiser d'abord, lance verbatra translate --dry-run ou --estimate : aucun des deux n'appelle un fournisseur ni ne demande de clé. Consulte Estimer le coût.
• Face à un fournisseur limité en débit, traduis une locale par étape avec --locales.

Vérifier d'abord avec doctorCopier le lien vers cette section

Place verbatra doctor avant l'un ou l'autre job pour échouer tôt sur une installation cassée. Il vérifie la configuration, le format, le fournisseur, la variable de clé, la politique réseau, le fichier source et la prise en charge des locales, sans jamais appeler de fournisseur ni lire la valeur d'une clé. Il signale toutefois une variable de clé non définie comme un contrôle en échec, donc fais passer la clé dans tout job où ce contrôle doit réussir.

Codes de sortieCopier le lien vers cette section

Branche-toi sur le code de sortie, jamais sur le texte. Ce que signifie chaque code, avec ses cas limites, est dans Codes de sortie et sortie JSON ; un code d'erreur dans la sortie est expliqué dans Codes d'erreur.

Sortie JSONCopier le lien vers cette section

Passe --json pour obtenir une enveloppe par enregistrement sur stdout. Ses champs sont dans Codes de sortie et sortie JSON, et le result de chaque commande sur sa page. Scripter verbatra avec JSON propose des recettes qui la lisent.

Clés et installationsCopier le lien vers cette section

• Installe avec pnpm install --frozen-lockfile ou npm ci, pour que le job exécute exactement la version de @verbatra/cli que ton lockfile enregistre.
• Garde les secrets hors des jobs qui n'appellent jamais de fournisseur : check, diff, report, export, import, extract, pseudo, types et tmx.
• En CI, repose-toi sur env:. Les commandes qui chargent aussi .env.local et .env sont listées dans Fichiers d'environnement.

Voir aussiCopier le lien vers cette section

• Utiliser la GitHub Action : les mêmes contrôles avec des annotations et un résumé de job.
• verbatra check et verbatra diff : toutes les options des deux contrôles.
• Codes de sortie et sortie JSON : le contrat que lit une étape de CI.
• Codes d'erreur : ce que signifie chaque code et l'étape suivante.