GitHub Action

verbatra incluye una GitHub Action compuesta que ejecuta verbatra translate --json en CI, convierte los fallos en anotaciones sobre la ejecución, escribe una tabla de resumen del job y sale con el código de salida de la CLI. Esta página cubre cómo conectarla y qué te muestra.

Cuándo usarla en lugar de un paso de CLI directo

La acción es el paso de translate con los informes ya integrados: anotaciones de error por locale, una tabla de resumen en la página de la ejecución y una propagación del código de salida que nunca se traga un fallo. Prefiérela cuando tu job sea "traduce en cada push y muéstrame qué pasó".

Ejecuta la CLI directamente cuando quieras cualquier otra cosa: una puerta de solo lectura con check o diff, flags personalizados como --prune, o tu propio manejo de la salida JSON. La acción siempre ejecuta translate --json y nada más; nunca ejecuta init, watch ni check.

Disponibilidad

La acción vive en el repositorio de verbatra y se referencia por ruta, fijada a un SHA de commit:

uses: mariokreitz/verbatra/packages/github-action@<commit-sha>

No hay paquete npm, ni publicación en el Marketplace, ni etiqueta de acción con versión. La referencia por ruta fijada a un SHA es la única forma admitida de consumirla.

Uso

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

permissions:
  contents: read

jobs:
  verbatra:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
      - uses: mariokreitz/verbatra/packages/github-action@<commit-sha>
        with:
          version: 0.5.0 # pin @verbatra/cli to an exact version
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

La acción descarga y ejecuta @verbatra/cli exactamente en la versión que fijas, así que el flujo de trabajo no necesita ningún paso de instalación para verbatra.

Cableado de secretos

La acción ejecuta la CLI, y la CLI lee la clave API del proveedor solo desde el entorno. Pasa la clave desde los secretos de tu repositorio bajo la variable que tu proveedor espera (consulta Proveedores): ANTHROPIC_API_KEY arriba, OPENAI_API_KEY, GEMINI_API_KEY o DEEPL_API_KEY. No existe una entrada de clave; una clave nunca viaja como entrada de la acción ni como argumento de la CLI.

Entradas

La acción no define salidas. Sus resultados son las anotaciones, el resumen del job y el código de salida.

Qué te muestra una ejecución

Anotaciones. Cuando la CLI sale con 1 (algunos locales fallaron), cada locale fallido se convierte en una anotación de error titulada verbatra: <locale>, con el [CODE] message estructurado de ese locale. Cuando toda la ejecución falla antes de producir un resumen (salida 2), una única anotación verbatra lleva en su lugar la línea de error de la CLI.

Resumen del job. Cada ejecución añade un resumen en Markdown a la página del job: una tabla con una fila por locale (estado, traducidas, sin cambios, huérfanas, ICU inválido, retenidas por integridad, fallos del proveedor, avisos), una línea agregada y una lista de los locales fallidos con sus códigos de error. Una ejecución en seco se etiqueta como tal. Un fallo de toda la ejecución recibe un breve resumen de fallo con el código de salida y el detalle del error.

Comportamiento de salida. La acción captura el stdout y el código de salida de la CLI sin abandonar antes de tiempo, emite las anotaciones y el resumen, y solo entonces sale con el código propio de la CLI. Así que el paso falla con 1 o 2, pero nunca antes de que puedas ver por qué. La página de códigos de salida detalla qué significa cada código. Si el cableado interno del código de salida se rompiera alguna vez, la acción falla con 2 en lugar de informar de un falso éxito.

Conservar las traducciones

Sin dry-run, translate escribe los archivos de locale actualizados en el checkout del runner, y la acción se detiene ahí: no confirma nada. Para conservar los cambios, añade tu propio paso que confirme y haga push, o que abra un pull request. Cuando solo quieras que CI señale traducciones faltantes u obsoletas sin escribir nada, pon dry-run: "true" (o bloquea con verbatra check y omite la acción por completo).

Seguridad

Fija ambas referencias con exactitud: la línea uses: a un SHA de commit y la entrada version a una versión exacta de @verbatra/cli. La acción impone la segunda por sí misma rechazando cualquier cosa que no sea una versión semver exacta, así que una ejecución nunca puede resolver latest en silencio. Dale al flujo de trabajo solo el privilegio que necesita: contents: read para un informe, más contents: write o pull-requests: write solo cuando un paso posterior confirme o abra un pull request. Las entradas llegan a la CLI a través del entorno como datos y se expanden en un array de argumentos entre comillas, nunca se empalman en texto de shell, así que un valor de entrada malicioso sigue siendo un argumento y nunca se convierte en código ejecutable.