--- title: "Usa la GitHub Action" description: "Ejecuta verbatra en GitHub Actions con la acción compuesta: traduce en un push o protege un pull request, con anotaciones y un resumen del job." type: "how-to" --- # Usa la GitHub Action Ejecuta verbatra en GitHub Actions con la acción compuesta: traduce en un push o protege un pull request, con anotaciones y un resumen del job. Usa la acción cuando un job de GitHub Actions deba ejecutar verbatra y mostrarte qué pasó. Ejecuta `translate`, `check` o `diff` con `--json`; para cualquier otro comando o flag, como `--prune`, ejecuta [la CLI directamente](https://verbatra.kreitz-webdev.de/es/docs/ci-and-exit-codes.md). Antes de empezar, necesitas: - Una configuración de verbatra directamente dentro del directorio en el que se ejecuta la acción (consulta [Descubrimiento de la configuración](#descubrimiento-de-la-configuración)). - Una versión exacta de `@verbatra/cli` que fijar, `0.9.3` o posterior. - Solo para `translate`: la clave de API de tu proveedor como secreto del repositorio. - Actions Runner v2.327.1 o posterior, y `verbatra/action` `v1.3.0` o posterior, que esta página describe y que `qa`, `require-reviewed`, `sensitive`, `locales` y `needs-human` necesitan. ## Añade la acción a un workflow [#añade-la-acción-a-un-workflow] La acción vive en [verbatra/action](https://github.com/verbatra/action) y en el [GitHub Marketplace](https://github.com/marketplace/actions/verbatra); no hay paquete npm. Fíjala a un SHA de commit, como abajo, o usa la etiqueta móvil `verbatra/action@v1`. La antigua ruta `mariokreitz/verbatra/packages/github-action` ya no se resuelve. ```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 }} ``` La acción instala `@verbatra/cli` y `@verbatra/sdk` exactamente en esa versión en un directorio temporal y deja intactas tus propias dependencias, así que el job no necesita un paso de instalación. ### Pasa la clave del proveedor [#pasa-la-clave-del-proveedor] Pasa la clave desde los secretos del repositorio con la variable que lee tu proveedor; [Proveedores](https://verbatra.kreitz-webdev.de/es/docs/providers.md#las-claves-vienen-del-entorno) las enumera. La acción no tiene una entrada para la clave, así que una clave nunca viaja como entrada ni como argumento de la CLI. ## Protege un pull request [#protege-un-pull-request] Pon `command: check` para que falle un pull request cuyos archivos de locale se hayan desviado, o `command: diff` para listar además las claves pendientes. Ambos son de solo lectura y no llaman a ningún proveedor, así que no necesitan clave y se ejecutan en pull requests desde forks: ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check ``` ## Comprobar la calidad de la traducción [#comprobar-la-calidad-de-la-traducción] Añade `qa: "true"` a `command: check` para ejecutar [`verbatra check --qa`](https://verbatra.kreitz-webdev.de/es/docs/cli/check.md#control-de-calidad) sobre cada traducción confirmada, incluidos los valores escritos a mano. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check qa: "true" ``` - Cada hallazgo se convierte en una anotación titulada `verbatra qa: `: un error para un valor que la puerta de integridad rechazaría, un aviso para un motivo de revisión. - El paso falla con cualquier hallazgo de error. Añade `qa-strict: "true"` para fallar también con avisos y plurales incompletos, o `qa-severity: error` para informar solo de errores. La CLI rechaza ambos a la vez. ## Exigir traducciones revisadas [#exigir-traducciones-revisadas] Añade `require-reviewed: "true"` a `command: check` para ejecutar [`verbatra check --require-reviewed`](https://verbatra.kreitz-webdev.de/es/docs/cli/check.md#exigir-traducciones-revisadas). El paso falla mientras una traducción escrita por máquina no esté aprobada en el `verbatra.provenance.json` confirmado, donde [Studio](https://verbatra.kreitz-webdev.de/es/docs/review-in-studio.md) guarda las decisiones de revisión. Sigue siendo de solo lectura y sin clave, y se combina con `qa`. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check require-reviewed: "true" ``` - Cada locale con claves sin aprobar recibe una anotación de error [`REVIEW_REQUIRED`](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md#review_required) que las nombra, y el resumen del job añade una columna `unreviewed`. - Un `verbatra.provenance.json` dañado o escrito por un verbatra más reciente hace fallar la puerta con una sola anotación `REVIEW_STATE_UNREADABLE`. ## Elegir locales y analizar las fuentes [#elegir-locales-y-analizar-las-fuentes] Pon en `locales` una lista separada por comas, como `de,fr`, para limitar cualquier comando a esos locales de destino. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check locales: "de,fr" ``` ### Contenido sensible [#contenido-sensible] Añade `sensitive: "true"` a `command: check` para ejecutar `verbatra check --sensitive`. El paso falla cuando el archivo fuente o el glosario contienen contenido que coincide con un detector o patrón de `sensitiveData`, como correos electrónicos, claves o números de tarjeta, y anota cada clave fuente afectada sin imprimir la coincidencia. Una `version` anterior, o una prerelease `0.12.0-next.*`, hace fallar el paso antes de instalar nada. ## Modo solo humano [#modo-solo-humano] Con `provider: { id: "none" }` (consulta [Flujo solo humano](https://verbatra.kreitz-webdev.de/es/docs/human-only-workflow.md)), `translate` sale con `3` cuando deja claves para una persona. La acción lo trata como trabajo que entregar, no como un fallo: el paso pasa, cada locale afectado recibe un aviso `NEEDS_HUMAN`, el resumen del job lista las claves y la salida `needs-human` vale `"true"`. Ramifica sobre ella: ```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." ``` Solo `translate` recibe este trato. `check` y `diff` nunca terminan con `3`, así que un fallo de ellos sigue haciendo fallar el paso. ## Descubrimiento de la configuración [#descubrimiento-de-la-configuración] Con `config-path` vacío, la acción exige un archivo de configuración reconocido directamente dentro de `working-directory` (por defecto, la raíz del repositorio). Nunca busca en un directorio padre, así que en un monorepo apunta `working-directory` a la app y deja su configuración ahí: ```yaml with: version: 0.12.0 working-directory: apps/docs ``` Si no encuentra configuración, el paso falla antes de instalar la CLI y nombra el directorio que comprobó. Para cargar una configuración de otro sitio, define `config-path`: una ruta relativa se resuelve contra `working-directory`. ## Conserva las traducciones [#conserva-las-traducciones] `translate` escribe los archivos de locale actualizados en el checkout del runner; la acción nunca hace commit. Añade tu propio paso que haga commit y push, o que abra un pull request, y concede `contents: write` o `pull-requests: write` solo a ese job. ## Entradas [#entradas] | Entrada | Por defecto | Efecto | | --- | --- | --- | | `version` | obligatoria | versión exacta de `@verbatra/cli`, `0.9.3` o posterior; una dist-tag, un rango o un prefijo `^`/`~` hace fallar el paso | | `command` | `translate` | `translate`, `check` o `diff`; cualquier otro valor hace fallar el paso | | `config-path` | `""` | archivo de configuración que cargar (`--config`); relativo a `working-directory` | | `working-directory` | `""` | directorio en el que se ejecuta la CLI (`--cwd`); vacío, es la raíz del repositorio | | `dry-run` | `"false"` | `"true"` previsualiza sin llamar a un proveedor ni escribir (`--dry-run`); solo `translate` | | `qa` | `"false"` | `"true"` añade el control de calidad (`--qa`); solo `check` | | `qa-severity` | `""` | severidad mínima que informar, `error` o `warning` (`--severity`); requiere `qa` | | `qa-strict` | `"false"` | `"true"` falla también con avisos (`--strict`); requiere `qa` | | `require-reviewed` | `"false"` | `"true"` falla también con traducciones de máquina sin aprobar (`--require-reviewed`); solo `check` | | `sensitive` | `"false"` | `"true"` añade el análisis de contenido sensible (`--sensitive`); solo `check` | | `locales` | `""` | locales de destino separados por comas para los que se ejecuta (`--locales`) | | `node-version` | `"24"` | versión de Node.js que prepara la acción. CLI 0.13.0+: `22.22.0`+ en la 22, 24+ (acción v1.4.0: solo versiones mayores pares); CLI 0.12.x: `^22.18.0 || >=24`; anterior: `>=22.14.0` | Las entradas booleanas solo aceptan `"true"` o `"false"`. Un booleano no válido, o una entrada sin el comando o `qa` que necesita, hace fallar el paso con salida `1` antes de instalar la CLI. La CLI rechaza un `qa-severity` desconocido, y `qa-severity: error` con `qa-strict`, con salida `2` después. ## Salidas [#salidas] | Salida | Valor | | --- | --- | | `needs-human` | `"true"` cuando `translate` salió con `3` y dejó claves para una persona; si no, `"false"` | ## Qué te muestra una ejecución [#qué-te-muestra-una-ejecución] - **Anotaciones.** Con `translate` y salida `1`, cada locale fallido o parcial se convierte en una anotación de error titulada `verbatra: `. Con `check` o `diff`, cada locale desviado recibe una titulada `verbatra check: ` o `verbatra diff: `. Todas se asocian al archivo de su locale cuando la acción lo encuentra. La anotación `LOCALE_PARTIAL` de un locale parcial nombra las claves retenidas, agrupadas por causa. Cada `check` añade un aviso `PLURAL_CATEGORIES_INCOMPLETE` por locale cuyos plurales carecen de una categoría CLDR que usa el idioma. Con `sensitive`, cada clave marcada recibe una anotación de error `SENSITIVE_CONTENT` y una línea en el resumen. Una ejecución que falla por completo recibe una sola anotación `verbatra` con el código de error, su causa como `(cause: X)` y una pista `Next step:` cuando la CLI las da. GitHub muestra como mucho 10 anotaciones por severidad, así que la acción las ordena por desviación, revisión, errores de calidad y avisos, y añade un aviso que cuenta el resto. - **Resumen del job.** Una fila por locale con los recuentos del comando ejecutado, una línea agregada y los locales parciales y fallidos. Con `qa` añade una tabla de hallazgos de hasta 1000 hallazgos; los plurales incompletos tienen su propia sección. - **Estado de salida.** La acción emite primero las anotaciones y el resumen y luego sale con el [código de salida](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#códigos-de-salida) de la propia CLI, salvo que un `3` de `translate` pasa y un fallo antes de arrancar la CLI (sin directorio de trabajo, sin config, una instalación fallida) sale con `1`; una entrada rechazada recibe un único `::error::`, sin resumen. ## Seguridad [#seguridad] Fija las dos referencias: `uses:` a un SHA de commit y `version` a una versión exacta ([la actual en npm](https://www.npmjs.com/package/@verbatra/cli)); la acción rechaza todo lo que pudiera resolverse a `latest`. Las entradas llegan a la CLI como un array de argumentos entre comillas, nunca insertadas en texto de shell. ## Relacionado [#relacionado] - [Ejecuta verbatra en CI](https://verbatra.kreitz-webdev.de/es/docs/ci-and-exit-codes.md): las mismas puertas en cualquier sistema de CI. - [verbatra/action](https://github.com/verbatra/action): las notas de versión y la referencia de entradas generada a partir de `action.yml`.