--- title: "Exécuter verbatra en CI" description: "Fais échouer une pull request en cas de dérive des traductions ou de sortie machine non relue, et traduis à chaque push, avec la CLI dans tout système de CI." type: "how-to" --- # Exécuter verbatra en CI Fais échouer une pull request en cas de dérive des traductions ou de sortie machine non relue, et traduis à chaque push, avec la CLI dans tout système de 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`](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md) 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](https://verbatra.kreitz-webdev.de/fr/docs/github-action.md). ## Ajouter un contrôle de dérive [#ajouter-un-contrôle-de-dérive] [`verbatra check`](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md) 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 : ```yaml title=".github/workflows/i18n.yml" name: i18n on: pull_request permissions: contents: read jobs: check-translations: runs-on: ubuntu-latest steps: - uses: actions/checkout@ - uses: pnpm/action-setup@ - uses: actions/setup-node@ with: node-version: 22 - run: pnpm install --frozen-lockfile - run: pnpm exec verbatra check ``` Remplace `check` par [`verbatra diff`](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md) 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 traductions [#bloquer-sur-la-qualité-des-traductions] 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 : ```bash 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 ` contrôle un seul fichier de locale. Consulte [le contrôle qualité](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#contrôle-qualité) et [Un seul fichier](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#un-seul-fichier). La [GitHub Action](https://verbatra.kreitz-webdev.de/fr/docs/github-action.md#vérifier-la-qualité-des-traductions) exécute le même contrôle avec `qa: "true"`. ### Bloquer sur les décisions de relecture [#bloquer-sur-les-décisions-de-relecture] 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](https://verbatra.kreitz-webdev.de/fr/docs/review-in-studio.md) et les outils de relecture MCP : ```bash verbatra check --require-reviewed ``` Il n'a pas besoin de clé non plus. Les codes qu'il signale sont dans [Exiger des traductions relues](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#exiger-des-traductions-relues). ## Traduire lors d'un push [#traduire-lors-dun-push] Lance [`verbatra translate`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md) 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](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#les-clés-viennent-de-lenvironnement) liste la variable que lit chaque fournisseur. ```yaml - 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](https://verbatra.kreitz-webdev.de/fr/docs/estimating-cost.md). - Face à un fournisseur limité en débit, traduis une locale par étape avec `--locales`. ## Vérifier d'abord avec doctor [#vérifier-dabord-avec-doctor] Place [`verbatra doctor`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md) 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 sortie [#codes-de-sortie] 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](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#codes-de-sortie) ; un code d'erreur dans la sortie est expliqué dans [Codes d'erreur](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md). ## Sortie JSON [#sortie-json] Passe `--json` pour obtenir une enveloppe par enregistrement sur stdout. Ses champs sont dans [Codes de sortie et sortie JSON](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-json), et le `result` de chaque commande sur sa page. [Scripter verbatra avec JSON](https://verbatra.kreitz-webdev.de/fr/docs/agent-recipes.md) propose des recettes qui la lisent. ## Clés et installations [#clés-et-installations] - 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](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#fichiers-denvironnement). ## Voir aussi [#voir-aussi] - [Utiliser la GitHub Action](https://verbatra.kreitz-webdev.de/fr/docs/github-action.md) : les mêmes contrôles avec des annotations et un résumé de job. - [`verbatra check`](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md) et [`verbatra diff`](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md) : toutes les options des deux contrôles. - [Codes de sortie et sortie JSON](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md) : le contrat que lit une étape de CI. - [Codes d'erreur](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md) : ce que signifie chaque code et l'étape suivante.