GitHub Action

verbatra fournit une GitHub Action composite qui lance la CLI verbatra avec --json en CI, transforme les échecs en annotations sur l'exécution, écrit un tableau de résumé de job et sort avec le code de sortie de la CLI. Elle lance translate par défaut ; définis l'entrée command pour lancer à la place un contrôle check ou diff en lecture seule. Cette page couvre son câblage et ce qu'elle te montre.

Quand l'utiliser plutôt qu'une étape CLI brute

L'action est une étape translate, check ou diff avec le reporting déjà intégré : des annotations d'erreur par locale, un tableau de résumé sur la page d'exécution et une propagation du code de sortie qui n'avale jamais un échec. Préfère-la quand ton job est "lancer verbatra et me montrer ce qui s'est passé", y compris un contrôle check ou diff en lecture seule sur une pull request.

Lance plutôt la CLI directement quand tu veux autre chose : des options personnalisées comme --prune, ton propre traitement de la sortie JSON, ou une commande que l'action ne prend pas en charge. L'entrée command n'accepte que translate (la valeur par défaut), check ou diff ; l'action ne lance jamais init ni watch.

Disponibilité

L'action vit dans son propre dépôt, verbatra/action, séparé du monorepo verbatra, et elle est publiée sur GitHub Actions Marketplace. Il n'y a pas de paquet npm ; l'action se consomme uniquement via uses:.

Référence-la par dépôt, épinglée à un SHA de commit :

uses: verbatra/action@<commit-sha>

verbatra/action@v1 est la forme pratique et le choix par défaut recommandé : le tag v1 est la ligne activement maintenue et mise à jour en continu, elle avance avec chaque version, les correctifs et fonctionnalités t'arrivent donc sans toucher au workflow. Épingler un SHA reste de toute façon le choix soucieux de la sécurité, et c'est ce que font les exemples de cette page.

Elle était auparavant livrée depuis le monorepo verbatra et référencée par chemin. Cette forme ancienne ne résout plus, pointe donc tes workflows existants vers le dépôt ci-dessus.

Utilisation

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> # épingle la ligne v1 activement maintenue
        with:
          version: 0.9.3 # pin @verbatra/cli to an exact version, 0.9.3 or newer
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

L'action récupère et lance @verbatra/cli exactement à la version que tu épingles, donc le workflow n'a besoin d'aucune étape d'installation pour verbatra lui-même. L'épinglage ci-dessus n'est qu'un exemple : consulte le paquet @verbatra/cli sur npm pour connaître la version actuelle et relève l'épinglage délibérément, plutôt que de suivre un tag mouvant.

Câblage des secrets

L'action lance la CLI, et la CLI lit la clé d'API du fournisseur uniquement depuis l'environnement. Cela s'applique à la commande par défaut translate : passe la clé depuis les secrets de ton dépôt sous la variable que ton fournisseur attend (voir Fournisseurs) : ANTHROPIC_API_KEY ci-dessus, OPENAI_API_KEY, GEMINI_API_KEY, DEEPL_API_KEY ou GOOGLE_TRANSLATE_API_KEY. Les commandes en lecture seule check et diff n'appellent aucun fournisseur, elles n'ont donc besoin d'aucune clé, ce qui est justement ce qui leur permet de fonctionner comme contrôle sur une pull request venant d'un fork, où les secrets ne sont pas disponibles. Il n'y a pas d'entrée de clé ; une clé ne voyage jamais comme entrée d'action ni comme argument CLI.

Entrées

L'action ne définit aucune sortie. Ses résultats sont les annotations, le résumé de job et le code de sortie.

Découverte de la configuration

Quand config-path est laissé vide, l'action exige qu'un fichier de config verbatra reconnu existe directement dans le working-directory résolu. Si aucun n'y est trouvé, l'étape échoue avant d'installer la CLI, en nommant le répertoire exact qu'elle a vérifié.

La recherche est stricte : elle ne remonte jamais vers un répertoire parent ni vers la racine du dépôt, même quand un ancêtre contient une config valide. Prends un monorepo où l'app à traduire vit dans apps/docs :

      with:
        version: 0.9.3
        working-directory: apps/docs

Ici, apps/docs est la racine dans laquelle une config doit exister ; un fichier de config reconnu directement dans apps/docs est requis. Une config à la racine du dépôt extérieur ne satisfait pas le contrôle, même si elle est un ancêtre de apps/docs.

Définis config-path pour pointer vers un fichier de config en dehors de cette convention. Un config-path relatif continue de se résoudre par rapport à working-directory ; un config-path absolu est utilisé tel quel. Une fois la config confirmée, l'action la transmet toujours explicitement à la CLI avec --config <chemin-résolu>.

Ce qu'une exécution te montre

Annotations. Sous la commande par défaut translate, quand la CLI sort avec 1 (certaines locales ont échoué ou sont ressorties partielles), chaque locale échouée devient une annotation d'erreur intitulée verbatra: <locale>, portant le [CODE] message structuré de cette locale. Sous check, une locale en dérive est annotée verbatra check: <locale> à la place ; sous diff, une locale avec des changements en attente est annotée verbatra diff: <locale>. Quand toute l'exécution échoue avant de produire un résumé (sortie 2), une seule annotation verbatra porte à la place la ligne d'erreur de la CLI, quelle que soit la commande.

Résumé de job. Chaque exécution ajoute un résumé Markdown à la page du job, dont la forme dépend de la commande lancée. Sous translate, c'est un tableau avec une ligne par locale (statut, traduites, inchangées, orphelines, ICU invalide, retenues pour intégrité, échecs fournisseur, avis), une ligne d'agrégat et une liste des locales échouées avec leurs codes d'erreur ; un dry run est étiqueté comme tel. Sous check, il rapporte le nombre de clés manquantes et obsolètes par locale. Sous diff, il rapporte les clés manquantes et modifiées par locale, avec les clés orphelines listées à part, puisqu'elles ne font jamais à elles seules échouer l'étape. Un échec global reçoit un court résumé d'échec avec le code de sortie et le détail de l'erreur, quelle que soit la commande.

Comportement de sortie. L'action capture le stdout et le code de sortie de la CLI sans s'interrompre prématurément, émet les annotations et le résumé, et sort seulement ensuite avec le code de la CLI. L'étape échoue donc sur 1 ou 2, mais jamais avant que tu puisses voir pourquoi. La page CI et codes de sortie détaille la signification de chaque code. Si le câblage interne du code de sortie casse un jour, l'action échoue avec 2 plutôt que de rapporter un faux succès.

Persister les traductions

Sans dry-run, la commande par défaut translate écrit les fichiers de locale mis à jour dans le checkout du runner, et l'action s'arrête là : elle ne commit pas. Pour garder les changements, ajoute ta propre étape qui commit et pousse ou ouvre une pull request. Quand tu veux seulement que la CI signale les traductions manquantes ou obsolètes sans rien écrire, mets dry-run: "true" sous translate, ou mets command: check (ou command: diff) pour lancer à la place un contrôle en lecture seule.

Sécurité

Épingle les deux références exactement : la ligne uses: à un SHA de commit et l'entrée version à une version exacte de @verbatra/cli. L'action applique elle-même la seconde en rejetant tout ce qui n'est pas une version semver exacte, donc une exécution ne peut jamais résoudre latest en silence. Ne donne au workflow que le privilège dont il a besoin : contents: read pour un rapport, plus contents: write ou pull-requests: write seulement quand une étape ultérieure commit ou ouvre une pull request. Les entrées atteignent la CLI via l'environnement, comme données, et sont développées dans un tableau d'arguments protégé par des guillemets, jamais insérées dans du texte shell : une valeur d'entrée forgée reste un argument et ne devient jamais du code exécutable.