Usa la GitHub Action

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.

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).
• 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 workflowCopiar enlace a esta sección

La acción vive en verbatra/action y en el GitHub Marketplace; 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.

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> # 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 proveedorCopiar enlace a esta sección

Pasa la clave desde los secretos del repositorio con la variable que lee tu proveedor; Proveedores 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 requestCopiar enlace a esta sección

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:

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.12.0
          command: check

Comprobar la calidad de la traducciónCopiar enlace a esta sección

Añade qa: "true" a command: check para ejecutar verbatra check --qa sobre cada traducción confirmada, incluidos los valores escritos a mano.

      - uses: verbatra/action@<commit-sha> # 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: <locale>: 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 revisadasCopiar enlace a esta sección

Añade require-reviewed: "true" a command: check para ejecutar verbatra check --require-reviewed. El paso falla mientras una traducción escrita por máquina no esté aprobada en el verbatra.provenance.json confirmado, donde Studio guarda las decisiones de revisión. Sigue siendo de solo lectura y sin clave, y se combina con qa.

      - uses: verbatra/action@<commit-sha> # 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 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 fuentesCopiar enlace a esta sección

Pon en locales una lista separada por comas, como de,fr, para limitar cualquier comando a esos locales de destino.

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.12.0
          command: check
          locales: "de,fr"

Contenido sensibleCopiar enlace a esta sección

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 humanoCopiar enlace a esta sección

Con provider: { id: "none" } (consulta Flujo solo humano), 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:

      - uses: verbatra/action@<commit-sha> # 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ónCopiar enlace a esta secció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í:

      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 traduccionesCopiar enlace a esta sección

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.

EntradasCopiar enlace a esta sección

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.

SalidasCopiar enlace a esta sección

Qué te muestra una ejecuciónCopiar enlace a esta sección

• Anotaciones. Con translate y salida 1, cada locale fallido o parcial se convierte en una anotación de error titulada verbatra: <locale>. Con check o diff, cada locale desviado recibe una titulada verbatra check: <locale> o verbatra diff: <locale>. 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 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.

SeguridadCopiar enlace a esta sección

Fija las dos referencias: uses: a un SHA de commit y version a una versión exacta (la actual en npm); 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.

RelacionadoCopiar enlace a esta sección

• Ejecuta verbatra en CI: las mismas puertas en cualquier sistema de CI.
• verbatra/action: las notas de versión y la referencia de entradas generada a partir de action.yml.