Receta de CI con GitHub Actions

Ejecuta la traducción en un trabajo de confianza de GitHub Actions, revisa sus artefactos y agrega la entrega mediante una solicitud de cambios cuando el resultado esté listo.

Ejecuta la CLI de Lingo.dev en GitHub Actions cuando necesites que la traducción use los eventos de activación y las verificaciones de tu proceso 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 convierten en una solicitud de cambios.

Esta receta comienza con una ejecución manual y acceso de solo lectura al repositorio. Después de revisar un mensaje modificado, puedes agregar los permisos de escritura necesarios para crear una solicitud de cambios con la traducción. Como alternativa, la GitHub App nativa ofrece procesamiento administrado del repositorio sin necesidad de esta receta para el ejecutor.

Prepara el repositorio #

Completa la guía de inicio rápido de la CLI en tu entorno local con un archivo de origen y un idioma de destino. Confirma en el repositorio .lingo/config.json, el archivo de destino que revisaste y .lingo/lock.json. La configuración define el motor de localización, los idiomas de origen y destino y los patrones de archivos. El Lockfile registra la referencia inicial para los cambios posteriores del contenido de origen.

Para el siguiente ejemplo, configura locales/en.json como origen y español como destino para generar locales/es.json. El primer archivo de destino faltante se crea con lingo push --backfill-missing --wait; las modificaciones posteriores del contenido de origen usan lingo push --wait. La carga inicial selecciona los archivos de destino faltantes, por lo que no sirve para completar claves faltantes dentro de un archivo existente.

Agrega LINGO_API_KEY a los secretos de Actions del repositorio o del entorno. Esta credencial otorga acceso a Lingo.dev, independientemente de los permisos del repositorio de GitHub. Ejecuta el trabajo que usa credenciales solo con código de confianza. En particular, no uses pull_request_target para hacer checkout y ejecutar la revisión más reciente de una solicitud de cambios no confiable usando el secreto.

El ejemplo fija la versión de la CLI. Para administrarla 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 esto como .github/workflows/translate.yml. El ejemplo usa 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

Verifica los ID de la organización y del motor en el archivo .lingo/config.json confirmado en el repositorio. Modifica una entrada del contenido de origen en inglés, confirma el cambio en el repositorio e inicia el flujo de trabajo desde esa rama de confianza. Revisa el resultado de la ejecución y las diferencias en el registro del trabajo; luego descarga el artefacto y busca la entrada en español que corresponda al cambio. Cárgala en la aplicación y revisa su significado y sus variables.

La carga 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 u otros archivos ocultos privados.

Las verificaciones del intérprete de comandos comprueban que los archivos existan y que la sintaxis JSON sea válida. Un archivo de destino antiguo puede pasar ambas verificaciones, por eso es importante revisar la entrada modificada. Si el motor de localización requiere revisión humana, la ejecución puede seguir esperando a una persona después de que termine el comando. Antes de usar esa política en un ejecutor desechable, agrega el procedimiento para conservar el estado de ejecución en CI. Después del envío, exporta el puntero de esa ejecución específica y la ruta raíz absoluta original del proyecto, y carga .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. Usa if: always() en los pasos de exportación y carga para que una falla posterior en una verificación no descarte un estado recuperable; si falta el puntero, debes investigar el envío, no inventar uno.

Después de la revisión, restaura esa revisión exacta del código y ese estado de los archivos en la ruta raíz absoluta registrada, restaura el puntero, autentícate por separado y usa Pull con verificació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 consideres el archivo de destino antiguo del primer artefacto como la traducción terminada.

push --wait espera y descarga los resultados terminados que estén disponibles. Sin --wait, push normalmente termina después del envío. Si el envío y la recuperación se realizan en trabajos separados, ambos necesitan 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 una misma operación terminada, y nunca archives todo ~/.lingo.

Entrega una solicitud de cambios #

Una vez que el artefacto pase la revisión, otorga al trabajo contents: write y pull-requests: write. La política del repositorio también debe permitir que Actions cree solicitudes de cambios. GITHUB_TOKEN autoriza estas operaciones de GitHub; conserva LINGO_API_KEY para la traducción.

Configura una identidad de Git según la política de bots de tu equipo. Luego agrega un paso después de validar el resultado que prepare para la confirmación solo el archivo de destino esperado 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 GH_TOKEN desde secrets.GITHUB_TOKEN a este paso. La secuencia supone una ejecución manual desde una rama de confianza y un nombre de rama nuevo; si vuelves a ejecutarla con una rama existente, debes decidir explícitamente si la reutilizas o la reemplazas. No es un flujo de trabajo que escriba los cambios de vuelta en una bifurcación.

La solicitud de cambios apunta a la rama desde la que iniciaste el trabajo. Si GitHub marca sus flujos de trabajo como pendientes de aprobación, alguien con permisos de escritura en el repositorio debe elegir 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 verificaciones y el resultado en la aplicación antes de fusionar.

Es posible hacer confirmaciones directamente en la rama que activa el flujo de trabajo si la política de ramas lo permite, pero esto elimina el paso independiente de revisión del contenido y requiere medidas para evitar bucles.

Programa el trabajo y gestiona monorepositorios #

Una vez que la primera ejecución dé un resultado útil, agrega ramas de confianza que activen el flujo al recibir cambios y filtros de rutas de origen. Las confirmaciones de traducción generadas no deben activar una y otra vez otro trabajo de traducción. Combina filtros de ramas o rutas adecuados con la salida sin cambios del paso de entrega.

En un monorepositorio, establece como directorio de trabajo del paso de traducción el paquete que contiene .lingo/config.json. Actualiza las rutas de los artefactos y de los archivos en el área de preparación 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, agregando el nombre del paquete a translated-catalog y lingo/translations-${GITHUB_RUN_ID}.

Recupera una ejecución incompleta #

Parte del estado informado: hay que resolver los errores de los destinos que fallaron, tomar decisiones sobre los destinos pendientes de revisión y elegir entre la modificación local y el resultado descargado cuando haya conflictos locales de descarga. Mantén los resultados correctos disponibles para su revisión y deja sin resolver los idiomas incompletos. Un resultado parcial no debe presentarse como una publicación completa de un idioma.

Mantén visibles los códigos de salida distintos de cero. || true, forzar la descarga sobre las modificaciones o forzar todos los destinos puede ocultar la causa y reemplazar trabajo aceptado. La guía de flujos de trabajo de CI explica cómo conservar la revisión del código y la referencia inicial durante la recuperación.

Deshabilita el flujo de trabajo o el evento que lo activa para detener nuevos trabajos del ejecutor. Si un trabajo ya envió una traducción, revisa por separado esa ejecución en el servidor al cancelar Actions. Elimina los secretos sin uso y el acceso de escritura al repositorio cuando retires el flujo de trabajo.