Utiliser la GitHub Action

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.

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).
• 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 workflowCopier le lien vers cette section

L'action se trouve dans verbatra/action et sur le GitHub Marketplace ; 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.

name: translate
on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verbatra:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
      - uses: verbatra/action@<commit-sha> # 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 fournisseurCopier le lien vers cette section

Fais passer la clé depuis les secrets du dépôt sous la variable que lit ton fournisseur ; Fournisseurs 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 requestCopier le lien vers cette section

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 :

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.12.0
          command: check

Vérifier la qualité des traductionsCopier le lien vers cette section

Ajoute qa: "true" à command: check pour lancer verbatra check --qa sur chaque traduction commitée, y compris les valeurs saisies à la main.

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.12.0
          command: check
          qa: "true"

• Chaque constat devient une annotation intitulée verbatra qa: <locale> : 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 reluesCopier le lien vers cette section

Ajoute require-reviewed: "true" à command: check pour lancer verbatra check --require-reviewed. L'étape échoue tant qu'une traduction écrite par une machine n'est pas approuvée dans le verbatra.provenance.json commité, où Studio enregistre les décisions de relecture. Cela reste en lecture seule et sans clé, et se combine avec qa.

      - uses: verbatra/action@<commit-sha> # 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 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 sourcesCopier le lien vers cette section

Mets dans locales une liste séparée par des virgules, comme de,fr, pour limiter n'importe quelle commande à ces locales cibles.

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.12.0
          command: check
          locales: "de,fr"

Contenu sensibleCopier le lien vers cette section

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 uniquementCopier le lien vers cette section

Avec provider: { id: "none" } (consulte Flux 100 % humain), 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 :

      - uses: verbatra/action@<commit-sha> # 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 configurationCopier le lien vers cette section

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à :

      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 traductionsCopier le lien vers cette section

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éesCopier le lien vers cette section

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.

SortiesCopier le lien vers cette section

Ce qu'une exécution te montreCopier le lien vers cette section

• Annotations. Avec translate et la sortie 1, chaque locale en échec ou partielle devient une annotation d'erreur intitulée verbatra: <locale>. Avec check ou diff, chaque locale qui a dérivé en reçoit une intitulée verbatra check: <locale> ou verbatra diff: <locale>. 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 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éCopier le lien vers cette section

Épingle les deux références : uses: sur un SHA de commit et version sur une version exacte (la dernière sur npm) ; 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 aussiCopier le lien vers cette section

• Exécuter verbatra en CI : les mêmes contrôles dans n'importe quel système de CI.
• verbatra/action : les notes de version et la référence des entrées générée à partir de action.yml.