--- title: "Utiliser la GitHub Action" description: "Exécute verbatra dans GitHub Actions avec l'action composite : traduis lors d'un push ou contrôle une pull request, avec des annotations et un résumé de job." type: "how-to" --- # Utiliser la GitHub Action Exécute verbatra dans GitHub Actions avec l'action composite : traduis lors d'un push ou contrôle une pull request, avec des annotations et un résumé de job. Utilise l'action quand un job GitHub Actions doit exécuter verbatra et te montrer ce qui s'est passé. Elle exécute `translate`, `check` ou `diff` avec `--json` ; pour toute autre commande ou option, comme `--prune`, lance [la CLI directement](https://verbatra.kreitz-webdev.de/fr/docs/ci-and-exit-codes.md). Avant de commencer, il te faut : - Une configuration verbatra directement dans le répertoire où l'action s'exécute (consulte [Découverte de la configuration](#découverte-de-la-configuration)). - Une version exacte de `@verbatra/cli` à épingler, `0.9.3` ou plus récente. - Pour `translate` uniquement : la clé d'API de ton fournisseur en secret du dépôt. - Actions Runner v2.327.1 ou plus récent, et `verbatra/action` `v1.3.0` ou plus récent, que cette page décrit et dont `qa`, `require-reviewed`, `sensitive`, `locales` et `needs-human` ont besoin. ## Ajouter l'action à un workflow [#ajouter-laction-à-un-workflow] L'action se trouve dans [verbatra/action](https://github.com/verbatra/action) et sur le [GitHub Marketplace](https://github.com/marketplace/actions/verbatra) ; il n'y a pas de paquet npm. Épingle-la sur un SHA de commit, comme ci-dessous, ou utilise le tag mobile `verbatra/action@v1`. L'ancien chemin `mariokreitz/verbatra/packages/github-action` ne se résout plus. ```yaml title=".github/workflows/translate.yml" name: translate on: push: branches: [main] permissions: contents: read jobs: verbatra: runs-on: ubuntu-latest steps: - uses: actions/checkout@ - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 # an exact @verbatra/cli release, 0.9.3 or newer env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ``` L'action installe `@verbatra/cli` et `@verbatra/sdk` exactement dans cette version dans un répertoire temporaire et laisse tes propres dépendances intactes, donc le job n'a pas besoin d'étape d'installation. ### Passer la clé du fournisseur [#passer-la-clé-du-fournisseur] Fais passer la clé depuis les secrets du dépôt sous la variable que lit ton fournisseur ; [Fournisseurs](https://verbatra.kreitz-webdev.de/fr/docs/providers.md#les-clés-viennent-de-lenvironnement) les liste. L'action n'a pas d'entrée pour la clé, donc une clé ne circule jamais comme entrée ni comme argument de la CLI. ## Contrôler une pull request [#contrôler-une-pull-request] Mets `command: check` pour faire échouer une pull request dont les fichiers de locale ont dérivé, ou `command: diff` pour lister en plus les clés en attente. Les deux sont en lecture seule et n'appellent aucun fournisseur : ils n'ont besoin d'aucune clé et tournent sur les pull requests venant de forks : ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check ``` ## Vérifier la qualité des traductions [#vérifier-la-qualité-des-traductions] Ajoute `qa: "true"` à `command: check` pour lancer [`verbatra check --qa`](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#contrôle-qualité) sur chaque traduction commitée, y compris les valeurs saisies à la main. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check qa: "true" ``` - Chaque constat devient une annotation intitulée `verbatra qa: ` : une erreur pour une valeur que le contrôle d'intégrité refuserait, un avertissement pour un motif de relecture. - L'étape échoue sur tout constat d'erreur. Ajoute `qa-strict: "true"` pour échouer aussi sur les avertissements et les pluriels incomplets, ou `qa-severity: error` pour ne signaler que les erreurs. La CLI refuse les deux ensemble. ## Exiger des traductions relues [#exiger-des-traductions-relues] Ajoute `require-reviewed: "true"` à `command: check` pour lancer [`verbatra check --require-reviewed`](https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md#exiger-des-traductions-relues). L'étape échoue tant qu'une traduction écrite par une machine n'est pas approuvée dans le `verbatra.provenance.json` commité, où [Studio](https://verbatra.kreitz-webdev.de/fr/docs/review-in-studio.md) enregistre les décisions de relecture. Cela reste en lecture seule et sans clé, et se combine avec `qa`. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check require-reviewed: "true" ``` - Chaque locale avec des clés non approuvées reçoit une annotation d'erreur [`REVIEW_REQUIRED`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#review_required) qui les nomme, et le résumé de job ajoute une colonne `unreviewed`. - Un `verbatra.provenance.json` corrompu ou écrit par un verbatra plus récent fait échouer le contrôle avec une seule annotation `REVIEW_STATE_UNREADABLE`. ## Choisir les locales et analyser les sources [#choisir-les-locales-et-analyser-les-sources] Mets dans `locales` une liste séparée par des virgules, comme `de,fr`, pour limiter n'importe quelle commande à ces locales cibles. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check locales: "de,fr" ``` ### Contenu sensible [#contenu-sensible] Ajoute `sensitive: "true"` à `command: check` pour exécuter `verbatra check --sensitive`. L'étape échoue quand le fichier source ou le glossaire contient du contenu que reconnaît un détecteur ou un motif de `sensitiveData`, comme des e-mails, des clés ou des numéros de carte, et annote chaque clé source concernée sans afficher la correspondance. Une `version` plus ancienne, ou une préversion `0.12.0-next.*`, fait échouer l'étape avant toute installation. ## Mode humain uniquement [#mode-humain-uniquement] Avec `provider: { id: "none" }` (consulte [Flux 100 % humain](https://verbatra.kreitz-webdev.de/fr/docs/human-only-workflow.md)), `translate` sort avec `3` quand il laisse des clés à une personne. L'action le traite comme du travail à transmettre, pas comme un échec : l'étape réussit, chaque locale concernée reçoit un avertissement `NEEDS_HUMAN`, le résumé de job liste les clés et la sortie `needs-human` vaut `"true"`. Branche-toi dessus : ```yaml - uses: verbatra/action@ # a commit on the v1 line id: verbatra with: version: 0.12.0 - if: steps.verbatra.outputs.needs-human == 'true' run: echo "Some keys need a human translation; see the job summary." ``` Seul `translate` reçoit ce traitement. `check` et `diff` ne se terminent jamais par `3`, donc un échec de leur part fait toujours échouer l'étape. ## Découverte de la configuration [#découverte-de-la-configuration] Quand `config-path` est vide, l'action exige un fichier de configuration reconnu directement dans `working-directory` (par défaut la racine du dépôt). Elle ne cherche jamais dans un répertoire parent, donc dans un monorepo, pointe `working-directory` vers l'app et garde sa configuration là : ```yaml with: version: 0.12.0 working-directory: apps/docs ``` Si aucune configuration n'est trouvée, l'étape échoue avant d'installer la CLI et nomme le répertoire contrôlé. Pour charger une configuration d'ailleurs, définis `config-path` : un chemin relatif se résout par rapport à `working-directory`. ## Conserver les traductions [#conserver-les-traductions] `translate` écrit les fichiers de locale mis à jour dans le checkout du runner ; l'action ne commite jamais. Ajoute ta propre étape qui commite et pousse, ou ouvre une pull request, et n'accorde `contents: write` ou `pull-requests: write` qu'à ce job. ## Entrées [#entrées] | Entrée | Défaut | Effet | | --- | --- | --- | | `version` | obligatoire | version exacte de `@verbatra/cli`, `0.9.3` ou plus récente ; un dist-tag, une plage ou un préfixe `^`/`~` fait échouer l'étape | | `command` | `translate` | `translate`, `check` ou `diff` ; toute autre valeur fait échouer l'étape | | `config-path` | `""` | fichier de configuration à charger (`--config`) ; relatif à `working-directory` | | `working-directory` | `""` | répertoire où la CLI s'exécute (`--cwd`) ; vide, c'est la racine du dépôt | | `dry-run` | `"false"` | `"true"` prévisualise sans appeler de fournisseur ni écrire (`--dry-run`) ; `translate` uniquement | | `qa` | `"false"` | `"true"` ajoute le contrôle qualité (`--qa`) ; `check` uniquement | | `qa-severity` | `""` | gravité minimale signalée, `error` ou `warning` (`--severity`) ; exige `qa` | | `qa-strict` | `"false"` | `"true"` échoue aussi sur les avertissements (`--strict`) ; exige `qa` | | `require-reviewed` | `"false"` | `"true"` échoue aussi sur les traductions machine non approuvées (`--require-reviewed`) ; uniquement `check` | | `sensitive` | `"false"` | `"true"` ajoute l'analyse du contenu sensible (`--sensitive`) ; uniquement `check` | | `locales` | `""` | locales cibles séparées par des virgules auxquelles limiter l'exécution (`--locales`) | | `node-version` | `"24"` | version de Node.js que l'action installe. CLI 0.13.0+ : `22.22.0`+ sur la 22, 24+ (action v1.4.0 : versions majeures paires uniquement) ; CLI 0.12.x : `^22.18.0 || >=24` ; plus ancienne : `>=22.14.0` | Les entrées booléennes n'acceptent que `"true"` ou `"false"`. Un booléen invalide, ou une entrée sans la commande ou `qa` qu'elle exige, fait échouer l'étape avec la sortie `1` avant l'installation de la CLI. La CLI refuse un `qa-severity` inconnu, et `qa-severity: error` avec `qa-strict`, avec la sortie `2` après. ## Sorties [#sorties] | Sortie | Valeur | | --- | --- | | `needs-human` | `"true"` quand `translate` est sorti avec `3` et a laissé des clés à une personne, sinon `"false"` | ## Ce qu'une exécution te montre [#ce-quune-exécution-te-montre] - **Annotations.** Avec `translate` et la sortie `1`, chaque locale en échec ou partielle devient une annotation d'erreur intitulée `verbatra: `. Avec `check` ou `diff`, chaque locale qui a dérivé en reçoit une intitulée `verbatra check: ` ou `verbatra diff: `. Toutes se rattachent au fichier de leur locale quand l'action le trouve. L'annotation `LOCALE_PARTIAL` d'une locale partielle nomme les clés retenues, regroupées par cause. Chaque `check` ajoute un avertissement `PLURAL_CATEGORIES_INCOMPLETE` par locale dont les pluriels n'ont pas une catégorie CLDR que la langue utilise. Avec `sensitive`, chaque clé signalée reçoit une annotation d'erreur `SENSITIVE_CONTENT` et une ligne dans le résumé. Une exécution qui échoue dans son ensemble reçoit une seule annotation `verbatra` avec le code d'erreur, sa cause sous la forme `(cause: X)` et une piste `Next step:` quand la CLI les fournit. GitHub affiche au plus 10 annotations par gravité, donc l'action les ordonne par dérive, relecture, erreurs de qualité puis avertissements, et ajoute une notice qui compte le reste. - **Résumé de job.** Une ligne par locale avec les compteurs de la commande exécutée, une ligne agrégée et les locales partielles et en échec. Avec `qa`, il ajoute un tableau de constats jusqu'à 1000 constats ; les pluriels incomplets ont leur propre section. - **Statut de sortie.** L'action émet d'abord les annotations et le résumé, puis sort avec le [code de sortie](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#codes-de-sortie) de la CLI elle-même, sauf qu'un `3` de `translate` passe et qu'un échec avant le lancement de la CLI (pas de répertoire de travail, pas de config, une installation échouée) sort avec `1` ; une entrée refusée reçoit un seul `::error::`, sans résumé. ## Sécurité [#sécurité] Épingle les deux références : `uses:` sur un SHA de commit et `version` sur une version exacte ([la dernière sur npm](https://www.npmjs.com/package/@verbatra/cli)) ; l'action refuse tout ce qui pourrait se résoudre en `latest`. Les entrées atteignent la CLI sous forme de tableau d'arguments entre guillemets, jamais insérées dans du texte shell. ## Voir aussi [#voir-aussi] - [Exécuter verbatra en CI](https://verbatra.kreitz-webdev.de/fr/docs/ci-and-exit-codes.md) : les mêmes contrôles dans n'importe quel système de CI. - [verbatra/action](https://github.com/verbatra/action) : les notes de version et la référence des entrées générée à partir de `action.yml`.