Guía práctica de CI con GitHub Actions

Ejecuta la traducción en una tarea de confianza de GitHub Actions, revisa sus artefactos y añade la entrega mediante solicitudes de incorporación de cambios cuando el resultado esté listo.

Ejecuta la CLI de Lingo.dev en GitHub Actions cuando necesites que la traducción utilice los desencadenantes y las comprobaciones de tu proceso de CI actual. El ejecutor lee la configuración del repositorio, envía los cambios del contenido de origen y descarga los archivos traducidos. Tú decides si esos archivos se conservan como artefactos o se entregan mediante una solicitud de incorporación de cambios.

Esta guía parte de una ejecución manual y un acceso de solo lectura al repositorio. Cuando hayas revisado un mensaje modificado, puedes añadir los permisos de escritura necesarios para crear una solicitud de incorporación de cambios con la traducción. Como alternativa, la GitHub App nativa ofrece un procesamiento gestionado del repositorio sin tener que configurar el ejecutor como se describe aquí.

Prepara el repositorio #

Completa la guía de inicio rápido de la CLI en local con un archivo de origen y un idioma de destino. Incluye en un commit .lingo/config.json, el archivo de destino que has revisado y .lingo/lock.json. La configuración determina el motor de localización, los idiomas de origen y destino y los patrones de archivos. El Lockfile registra el estado de referencia para los cambios posteriores del contenido de origen.

Para el siguiente ejemplo, configura locales/en.json como origen y el español como destino para generar locales/es.json. El primer archivo de destino que falte se crea con lingo push --backfill-missing --wait; para los cambios posteriores del contenido de origen se utiliza lingo push --wait. La operación de relleno selecciona los archivos de destino que faltan, por lo que no sirve para añadir claves ausentes en un archivo existente.

Añade LINGO_API_KEY a los secretos de Actions del repositorio o del entorno. Este secreto concede acceso a Lingo.dev, independientemente de los permisos del repositorio de GitHub. Ejecuta la tarea con credenciales únicamente sobre código de confianza. En particular, no utilices pull_request_target con ese secreto para extraer y ejecutar la revisión más reciente de una solicitud de incorporación de cambios que no sea de confianza.

El ejemplo fija la versión de la CLI. Para gestionarla mediante las dependencias y el Lockfile de tu proyecto, sigue la guía de configuración de CI.

Obtén un artefacto de traducción #

Guarda este ejemplo como .github/workflows/translate.yml. Utiliza Node.js 22.

yaml
name: Translate catalog
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Translate and download
        # Replace 1.21.0 with the current CLI version.
        run: npx -y @lingo.dev/cli@1.21.0 push --wait
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Inspect expected output
        run: |
          test -s locales/es.json
          node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
          git diff -- locales/es.json .lingo/lock.json
      - uses: actions/upload-artifact@v4
        with:
          name: translated-catalog
          include-hidden-files: true
          path: |
            locales/es.json
            .lingo/lock.json

Comprueba los identificadores de la organización y del motor en el archivo .lingo/config.json incluido en el commit. Haz un cambio en el contenido de origen en inglés, crea un commit y ejecuta manualmente el flujo de trabajo desde esa rama de confianza. Consulta el resultado de la ejecución y las diferencias en el registro de la tarea. Después, descarga el artefacto y busca la entrada en español correspondiente al cambio. Cárgala en la aplicación y revisa su significado y sus variables.

La subida incluye archivos ocultos para conservar .lingo/lock.json. Limita la lista de rutas al archivo de destino previsto y al Lockfile; no la amplíes para incluir credenciales ni otros archivos ocultos privados.

Las comprobaciones del intérprete de comandos verifican que los archivos existen y que la sintaxis JSON es válida. Un archivo de destino antiguo puede superar ambas comprobaciones, por lo que es importante revisar la entrada modificada. Si el motor de localización exige una revisión humana, la ejecución puede seguir esperando esa revisión después de que termine el comando. Antes de utilizar esa política en un ejecutor efímero, añade el procedimiento de conservación del estado de ejecución en CI. Tras el envío, exporta el puntero de esa ejecución concreta y la ruta absoluta original de la raíz del proyecto, y sube .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, el archivo de destino y el Lockfile como artefactos de acceso restringido. Utiliza if: always() en los pasos de exportación y subida para que un fallo en una comprobación posterior no descarte el estado recuperable. Si falta el puntero, investiga el envío en lugar de inventar uno.

Tras la revisión, restaura exactamente esa revisión y el estado de los archivos en la ruta absoluta registrada para la raíz del proyecto. Restaura el puntero, autentícate por separado y utiliza Descarga con comprobación de conflictos. Si otro ejecutor no puede recrear la ruta, realiza el envío y la recuperación en un ejecutor persistente autorizado. No des por completada la traducción basándote en el archivo de destino antiguo del primer artefacto.

push --wait espera y descarga los resultados completados que estén disponibles. Sin --wait, el comando push normalmente termina después del envío. Si separas el envío y la recuperación en tareas distintas, necesitarás la misma exportación y restauración del estado de ejecución; copiar solo el Lockfile no basta. Mantén juntos los archivos de destino descargados y el Lockfile de la misma operación completada, y nunca archives todo el contenido de ~/.lingo.

Entrega una solicitud de incorporación de cambios #

Cuando hayas revisado el artefacto y comprobado que es correcto, concede a la tarea contents: write y pull-requests: write. La política del repositorio también debe permitir que Actions cree solicitudes de incorporación de cambios. GITHUB_TOKEN autoriza estas operaciones de GitHub; conserva LINGO_API_KEY para la traducción.

Configura una identidad de Git conforme a la política de bots de tu equipo. Después de validar el resultado, añade un paso que prepare para el commit únicamente el archivo de destino previsto y el Lockfile:

bash
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"

Los ejecutores alojados en GitHub incluyen la CLI de GitHub. Proporciona a este paso GH_TOKEN a partir de secrets.GITHUB_TOKEN. La secuencia presupone una ejecución manual desde una rama de confianza y un nombre de rama nuevo. Si repites la ejecución con una rama existente, debes decidir explícitamente si la reutilizas o la sustituyes. Este flujo de trabajo no escribe los cambios de vuelta en una bifurcación.

La solicitud de incorporación de cambios tiene como destino la rama desde la que ejecutaste manualmente la tarea. Si GitHub marca sus flujos de trabajo como pendientes de aprobación, alguien con permisos de escritura en el repositorio debe seleccionar Aprobar la ejecución de los flujos de trabajo; consulta el comportamiento de GITHUB_TOKEN en GitHub. Revisa las diferencias de la traducción, las comprobaciones y el resultado en la aplicación antes de fusionar los cambios.

Es posible hacer commits directamente en la rama que desencadena la ejecución si la política de ramas lo permite, pero esto elimina el paso independiente de revisión del contenido y exige medidas para evitar bucles.

Programa el trabajo y gestiona monorepositorios #

Cuando la primera ejecución resulte útil, añade desencadenantes de envío de cambios para ramas de confianza y filtros de rutas de origen. Los commits de traducción generados no deben desencadenar continuamente nuevas tareas de traducción. Combina filtros adecuados de ramas o rutas con la salida cuando no haya cambios en el paso de entrega.

En un monorrepositorio, configura el directorio de trabajo del paso de traducción para que apunte al paquete que contiene .lingo/config.json. Actualiza las rutas de los artefactos y de los archivos preparados para incluir ese paquete. Una matriz puede procesar paquetes independientes, pero dos entradas no deben competir por actualizar la misma configuración y el mismo Lockfile. Las entradas de una misma ejecución comparten el ID de ejecución, así que asigna a cada una un nombre de artefacto y una rama de traducción propios, por ejemplo, añadiendo el nombre del paquete a translated-catalog y lingo/translations-${GITHUB_RUN_ID}.

Recupera una ejecución incompleta #

Empieza por el estado indicado: resuelve los errores de los destinos que hayan fallado, toma las decisiones necesarias para los que estén pendientes de revisión y, si hay conflictos locales al descargar, elige entre la modificación local y el resultado descargado. Mantén los resultados correctos disponibles para su revisión y deja sin resolver los idiomas incompletos. Un resultado parcial no debe darse por válido como una entrega completa de un idioma.

Mantén visibles los códigos de salida distintos de cero. || true, forzar la descarga sobrescribiendo modificaciones o forzar todos los destinos puede ocultar la causa y sustituir trabajo ya aceptado. La guía de flujos de trabajo de CI explica cómo conservar la revisión y el estado de referencia durante la recuperación.

Desactiva el flujo de trabajo o su desencadenante para impedir nuevas tareas del ejecutor. Si una tarea ya ha enviado una traducción, revisa por separado esa ejecución en el servidor al cancelar Actions. Cuando retires el flujo de trabajo, elimina los secretos que ya no se utilicen y el acceso de escritura al repositorio.