--- title: "Ejecuta verbatra en CI" description: "Haz fallar un pull request por deriva de traducciones o salida automática sin revisar, y traduce en cada push, con la CLI en cualquier sistema de CI." type: "how-to" --- # Ejecuta verbatra en CI Haz fallar un pull request por deriva de traducciones o salida automática sin revisar, y traduce en cada push, con la CLI en cualquier sistema de CI. Usa esta guía cuando una pipeline deba detectar archivos de locale que se han desviado del origen, o traducirlos por ti en un push. Cada paso ejecuta la misma CLI que usas en local, así que funciona en cualquier sistema de CI; los ejemplos usan GitHub Actions. Antes de empezar, necesitas: - `@verbatra/cli` como dependencia de desarrollo, con tu lockfile confirmado en el repositorio. La CLI necesita Node `^22.22.0 || >=24`. - Una configuración, archivos de locale y [`verbatra.lock.json`](https://verbatra.kreitz-webdev.de/es/docs/the-lock-file.md) confirmados en el repositorio. - Solo para traducir: la clave de API de tu proveedor en el almacén de secretos de la CI. Si usas GitHub Actions y quieres anotaciones y un resumen del job sin escribir el job tú, usa la [GitHub Action](https://verbatra.kreitz-webdev.de/es/docs/github-action.md). ## Añade una puerta de deriva [#añade-una-puerta-de-deriva] [`verbatra check`](https://verbatra.kreitz-webdev.de/es/docs/cli/check.md) compara el origen, los archivos de destino y el archivo de bloqueo, y sale con `1` cuando a un locale le faltan claves o tiene claves obsoletas. No llama a ningún proveedor, así que el job no necesita clave y se ejecuta en pull requests desde forks: ```yaml title=".github/workflows/i18n.yml" name: i18n on: pull_request permissions: contents: read jobs: check-translations: runs-on: ubuntu-latest steps: - uses: actions/checkout@ - uses: pnpm/action-setup@ - uses: actions/setup-node@ with: node-version: 22 - run: pnpm install --frozen-lockfile - run: pnpm exec verbatra check ``` Cambia `check` por [`verbatra diff`](https://verbatra.kreitz-webdev.de/es/docs/cli/diff.md) cuando quieras los nombres de las claves detrás de la deriva, por ejemplo para publicarlos en un comentario del pull request. Sale con `1` en la misma condición; las claves huérfanas aparecen en su salida, pero nunca lo hacen fallar por sí solas. Para comprobar solo algunos locales, pasa `--locales de,fr`. Un valor de `--locales` que nombre un locale no configurado sale con `2`, aunque haya locales válidos a su lado, así que una errata nunca pone la puerta en verde. ### Frenar por la calidad de la traducción [#frenar-por-la-calidad-de-la-traducción] La deriva no es el único fallo que conviene detectar. Añade `--qa` para pasar también la puerta de integridad y los avisos de revisión sobre cada traducción confirmada, de modo que un valor editado a mano con un marcador roto, marcado roto o ramas de plural ICU que no encajan haga fallar el job: ```bash verbatra check --qa ``` - Añade `--strict` para fallar también con avisos de revisión y categorías de plural que faltan. - En un hook de edición, `verbatra check --file ` comprueba un solo archivo de locale. Consulta [el control de calidad](https://verbatra.kreitz-webdev.de/es/docs/cli/check.md#control-de-calidad) y [Un solo archivo](https://verbatra.kreitz-webdev.de/es/docs/cli/check.md#un-solo-archivo). La [GitHub Action](https://verbatra.kreitz-webdev.de/es/docs/github-action.md#comprobar-la-calidad-de-la-traducción) ejecuta la misma puerta con `qa: "true"`. ### Frenar por las decisiones de revisión [#frenar-por-las-decisiones-de-revisión] Añade `--require-reviewed` para fallar mientras alguna traducción escrita por máquina no esté aprobada en el `verbatra.provenance.json` confirmado, el archivo en el que escriben [la cola de revisión de Studio](https://verbatra.kreitz-webdev.de/es/docs/review-in-studio.md) y las herramientas de revisión MCP: ```bash verbatra check --require-reviewed ``` Tampoco necesita clave. Los códigos que informa están en [Exigir traducciones revisadas](https://verbatra.kreitz-webdev.de/es/docs/cli/check.md#exigir-traducciones-revisadas). ## Traduce en un push [#traduce-en-un-push] Ejecuta [`verbatra translate`](https://verbatra.kreitz-webdev.de/es/docs/cli/translate.md) y pasa la clave del proveedor desde tu almacén de secretos al entorno del paso. La CLI no acepta la clave como argumento ni la lee de la configuración; [Proveedores](https://verbatra.kreitz-webdev.de/es/docs/providers.md#las-claves-vienen-del-entorno) indica qué variable lee cada proveedor. ```yaml - run: pnpm exec verbatra translate --json env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ``` - El paso escribe los archivos de locale en el checkout y se detiene ahí. Añade tu propio paso que los confirme o abra un pull request, y concede `contents: write` o `pull-requests: write` solo a ese job. - Para previsualizar antes, ejecuta `verbatra translate --dry-run` o `--estimate`: ninguno llama a un proveedor ni necesita clave. Consulta [Estimar el coste](https://verbatra.kreitz-webdev.de/es/docs/estimating-cost.md). - Con un proveedor con límite de peticiones, traduce un locale por paso con `--locales`. ## Comprueba antes con doctor [#comprueba-antes-con-doctor] Pon [`verbatra doctor`](https://verbatra.kreitz-webdev.de/es/docs/cli/doctor.md) antes de cualquiera de los dos jobs para fallar pronto ante una configuración rota. Comprueba la configuración, el formato, el proveedor, la variable de la clave, la política de red, el archivo de origen y el soporte de locales, y nunca llama a un proveedor ni lee el valor de una clave. Eso sí, informa de una variable de clave sin definir como una comprobación fallida, así que pasa la clave a cualquier job en el que esa comprobación deba pasar. ## Códigos de salida [#códigos-de-salida] Ramifica sobre el código de salida, nunca sobre el texto. Qué significa cada código, con sus casos límite, está en [Códigos de salida y salida JSON](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#códigos-de-salida); un código de error en la salida se explica en [Códigos de error](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md). ## Salida JSON [#salida-json] Pasa `--json` para obtener un envoltorio por registro en stdout. Sus campos están en [Códigos de salida y salida JSON](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#salida-json), y el `result` de cada comando en su página. [Programa verbatra con JSON](https://verbatra.kreitz-webdev.de/es/docs/agent-recipes.md) tiene recetas que lo leen. ## Claves e instalaciones [#claves-e-instalaciones] - Instala con `pnpm install --frozen-lockfile` o `npm ci`, para que el job ejecute exactamente la versión de `@verbatra/cli` que registra tu lockfile. - Mantén los secretos fuera de los jobs que nunca llaman a un proveedor: `check`, `diff`, `report`, `export`, `import`, `extract`, `pseudo`, `types` y `tmx`. - En CI, confía en `env:`. Qué comandos cargan además `.env.local` y `.env` está en [Archivos de entorno](https://verbatra.kreitz-webdev.de/es/docs/cli.md#archivos-de-entorno). ## Relacionado [#relacionado] - [Usa la GitHub Action](https://verbatra.kreitz-webdev.de/es/docs/github-action.md): las mismas puertas con anotaciones y un resumen del job. - [`verbatra check`](https://verbatra.kreitz-webdev.de/es/docs/cli/check.md) y [`verbatra diff`](https://verbatra.kreitz-webdev.de/es/docs/cli/diff.md): todos los flags de las dos puertas. - [Códigos de salida y salida JSON](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md): el contrato que lee un paso de CI. - [Códigos de error](https://verbatra.kreitz-webdev.de/es/docs/error-codes.md): qué significa cada código y cuál es el siguiente paso.