Ejecuta verbatra en 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 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.

Añade una puerta de derivaCopiar enlace a esta sección

verbatra check 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:

name: i18n
on: pull_request

permissions:
  contents: read

jobs:
  check-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
      - uses: pnpm/action-setup@<commit-sha>
      - uses: actions/setup-node@<commit-sha>
        with:
          node-version: 22
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec verbatra check

Cambia check por verbatra diff 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ónCopiar enlace a esta secció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:

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 <path> comprueba un solo archivo de locale.

Consulta el control de calidad y Un solo archivo. La GitHub Action ejecuta la misma puerta con qa: "true".

Frenar por las decisiones de revisiónCopiar enlace a esta secció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 y las herramientas de revisión MCP:

verbatra check --require-reviewed

Tampoco necesita clave. Los códigos que informa están en Exigir traducciones revisadas.

Traduce en un pushCopiar enlace a esta sección

Ejecuta verbatra translate 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 indica qué variable lee cada proveedor.

      - 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.
• Con un proveedor con límite de peticiones, traduce un locale por paso con --locales.

Comprueba antes con doctorCopiar enlace a esta sección

Pon verbatra doctor 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 salidaCopiar enlace a esta sección

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; un código de error en la salida se explica en Códigos de error.

Salida JSONCopiar enlace a esta sección

Pasa --json para obtener un envoltorio por registro en stdout. Sus campos están en Códigos de salida y salida JSON, y el result de cada comando en su página. Programa verbatra con JSON tiene recetas que lo leen.

Claves e instalacionesCopiar enlace a esta sección

• 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.

RelacionadoCopiar enlace a esta sección

• Usa la GitHub Action: las mismas puertas con anotaciones y un resumen del job.
• verbatra check y verbatra diff: todos los flags de las dos puertas.
• Códigos de salida y salida JSON: el contrato que lee un paso de CI.
• Códigos de error: qué significa cada código y cuál es el siguiente paso.