Integración de Lingo.dev con GitHub

Lingo.dev GitHub Action es una integración CI/CD segura y de código abierto que localiza automáticamente el nuevo contenido y evita que las traducciones incompletas lleguen a producción. Crea solicitudes de extracción o commits directamente a tu rama, dependiendo de los requisitos del flujo de trabajo de tu equipo.

También implementa la resolución automática de conflictos, por lo que tus traducciones permanecen sincronizadas con tu código sin intervención manual.

La acción admite múltiples escenarios de flujo de trabajo:

Commits directos a la rama principal cuando se fusionan cambios de contenido
Commits directos a ramas de solicitudes de extracción cuando se abren o actualizan PRs
Solicitudes de extracción dirigidas a la rama principal para actualizaciones de traducción
Solicitudes de extracción dirigidas a ramas de solicitudes de extracción existentes para actualizaciones de traducción

Al completar esta guía, podrás:

Configurar la localización automatizada activada por envíos de código;
Configurar la autenticación segura utilizando secretos del repositorio;
Elegir entre commits directos o flujos de trabajo de solicitudes de extracción;
Comprender cómo la localización continua se integra en tu proceso existente.

¡Comencemos!

Requisitos previos

Configuración del repositorio

Tu repositorio debe tener Lingo.dev CLI configurado con un archivo i18n.json válido. Si aún no lo has configurado, completa primero la guía rápida de CLI.

Paso 1. Configuración de autenticación

Lingo.dev GitHub Actions necesita acceso a tu motor de traducción y repositorio. La autenticación se realiza a través de secretos del repositorio que mantienen tus credenciales seguras.

Añade tu clave API

Navega a la configuración de tu repositorio Settings → Secrets and variables → Actions, luego añade las credenciales de tu motor de traducción:

Para usuarios de API LLM sin procesar:

Nombre del secreto: OPENAI_API_KEY o ANTHROPIC_API_KEY
Valor del secreto: Tu clave API del proveedor respectivo

Para usuarios de Lingo.dev Engine:

Nombre del secreto: LINGODOTDEV_API_KEY
Valor del secreto: Tu clave API de proyecto de lingo.dev/app

Paso 2. Crear el flujo de trabajo

Crea .github/workflows/i18n.yml en tu repositorio con esta configuración básica:

name: Lingo.dev i18n

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Alternativamente, puedes añadir la acción de GitHub de Lingo.dev como un paso en tu flujo de trabajo existente:

- name: Lingo.dev
  uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Permisos requeridos

Tu flujo de trabajo necesita permisos específicos para funcionar correctamente. GitHub Actions requiere declaraciones explícitas de permisos en el archivo de flujo de trabajo:

permissions:
  contents: write # Requerido: Crear commits con actualizaciones de traducción
  pull-requests: write # Opcional: Solo necesario si se utiliza el modo de solicitud de extracción

El permiso contents: write permite que la acción:

Cree commits con actualizaciones de traducción
Envíe cambios directamente a tu repositorio
Acceda y modifique archivos en tu repositorio

Estos permisos se otorgan al token efímero de GitHub del flujo de trabajo (${{ github.token }}), que es creado automáticamente por GitHub para cada ejecución del flujo de trabajo y tiene exactamente los permisos que especificas en el archivo del flujo de trabajo.

Esta configuración:

Se activa con pushes a las ramas principal y de características
Otorga los permisos necesarios para commits y solicitudes de extracción
Utiliza la última versión de la acción para actualizaciones automáticas
Accede de forma segura a tu clave API a través de los secretos del repositorio

Bonus:

En Lingo.dev, nos gusta añadir un disparador workflow_dispatch a cada flujo de trabajo, para poder ejecutarlo manualmente (o re-ejecutarlo) desde la interfaz de usuario de GitHub Actions. Esto es completamente opcional, pero lo encontramos muy útil.

Paso 3. Elija su modo de flujo de trabajo

Lingo.dev GitHub Actions admite dos modos operativos según los requisitos de revisión de código de su equipo.

Modo de commit directo (predeterminado)

La acción realiza commits de traducciones directamente a su rama:

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Este modo funciona mejor para:

Desarrolladores individuales o equipos pequeños
Ramas de características que serán revisadas antes de fusionarse
Proyectos donde las actualizaciones de traducción no requieren revisión separada

Modo de pull request

La acción crea pull requests para actualizaciones de traducción:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    pull-request-title: "feat: update translations"

Permisos requeridos para el modo de pull request

El modo de pull request requiere permisos adicionales y configuraciones de repositorio:

permissions:
  contents: write # Requerido: Acceso al contenido del repositorio y creación de commits
  pull-requests: write # Requerido: Crear y actualizar pull requests

Configuración del token de GitHub: La variable de entorno GH_TOKEN debe establecerse como ${{ github.token }}, que es un token efímero generado por el sistema que GitHub crea automáticamente para cada ejecución del flujo de trabajo. Este token tiene exactamente los permisos especificados en la sección permissions de su archivo de flujo de trabajo.

Configuración del repositorio: Debe habilitar GitHub Actions para crear pull requests en la configuración de su repositorio:

Vaya a Settings → Actions → General
Desplácese hasta la parte inferior de la página
En "Workflow permissions", asegúrese de que "Allow GitHub Actions to create and approve pull requests" esté habilitado

Si no ve esta opción en la configuración de su repositorio, verifique la configuración de su organización:

Vaya a Settings → Actions → General de su organización
Busque la misma configuración "Allow GitHub Actions to create and approve pull requests"

Este modo funciona mejor para:

Equipos con requisitos estrictos de revisión de código
Proyectos donde los cambios de traducción necesitan aprobación separada
Flujos de trabajo que requieren revisión explícita de todos los cambios

Paso 4. Escenarios de flujo de trabajo

Lingo.dev GitHub Action se adapta automáticamente a diferentes flujos de trabajo de desarrollo. Comprender estos escenarios te ayuda a elegir la configuración correcta para tu equipo.

Escenario 1: Actualizaciones en la rama principal (Commits directos)

Disparador: Push a la rama principal (por ejemplo, al fusionar pull requests) Acción: Realiza commits de actualizaciones de traducción directamente a la rama principal

on:
  push:
    branches: [main]

# La Action realiza commits directamente a la rama principal

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Flujo: Cambios de contenido enviados a main → La Action realiza commits de traducciones a main

Este escenario asegura que tu rama principal siempre tenga traducciones actualizadas inmediatamente después de que se fusionen los cambios de contenido.

Consejo: Este es el modo que recomendamos implementar. Requiere un motor de localización de IA bien configurado para garantizar una localización perfecta. La ventaja es que conduce a cero intervención manual, ya que las traducciones faltantes se verifican y completan automáticamente antes de cada despliegue a producción.

Escenario 2: Actualizaciones de Pull Request (Commits directos)

Disparador: Pull request abierto o actualizado con cambios de contenido Acción: Realiza commits de actualizaciones de traducción directamente a la rama del pull request

on:
  pull_request:
    types: [opened, synchronize]

# La Action realiza commits directamente a la rama del PR

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Flujo: Cambios de contenido en la rama del PR → La Action realiza commits de traducciones a la misma rama del PR

Esto mantiene las actualizaciones de traducción dentro de la rama de características, asegurando que las traducciones se revisen junto con los cambios originales.

Escenario 3: Pull Requests a la rama principal (Modo Pull Request)

Disparador: Push a la rama principal (por ejemplo, al fusionar pull requests) Acción: Crea un pull request con actualizaciones de traducción

on:
  push:
    branches: [main]

# La acción crea PR: main/lingo.dev → main

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

Flujo: Cambios de contenido enviados a main → La acción crea la rama main/lingo.dev → Abre PR desde main/lingo.dev → main

Escenario 4: Pull Requests a ramas de características (Modo Pull Request)

Disparador: Pull request abierto o actualizado con cambios de contenido Acción: Crea un pull request con actualizaciones de traducción dirigido a la rama de características

on:
  pull_request:
    types: [opened, synchronize]

# La acción crea PR: feat/new-feature/lingo.dev → feat/new-feature

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

Flujo: Cambios de contenido en feat/new-feature → La acción crea la rama feat/new-feature/lingo.dev → Abre PR desde feat/new-feature/lingo.dev → feat/new-feature

Esto mantiene revisiones de traducción separadas para cada rama de características.

Convención de nomenclatura de ramas

Cuando se utiliza el modo pull request, la Acción de GitHub de Lingo.dev sigue un patrón de nomenclatura consistente:

Formato: <rama-base>/lingo.dev

Ejemplos:

Actualizaciones de rama principal: main/lingo.dev → main
Actualizaciones de rama de características: feat/user-auth/lingo.dev → feat/user-auth
Actualizaciones de rama de lanzamiento: release/v2.0/lingo.dev → release/v2.0

Esta convención de nomenclatura asegura que las ramas de traducción sean claramente identificables y automáticamente vinculadas a sus ramas de origen.

Gestionar contribuciones externas

Cuando se trabaja con forks externos, implemente checkout selectivo para mantener la seguridad del repositorio:

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find locales/** -name "*.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Permisos requeridos para contribuciones externas

El manejo de forks externos requiere permisos elevados para procesar contribuciones de forma segura:

permissions:
  actions: write # Requerido: Acceso a información de flujos de trabajo y artefactos
  contents: write # Requerido: Crear commits y acceder al contenido del repositorio
  pull-requests: write # Requerido: Actualizar pull requests de forks externos

El permiso actions: write es específicamente necesario para:

Acceder a metadatos de pull requests de forks externos
Leer el contexto del flujo de trabajo para validación de seguridad
Manejar artefactos y estado del flujo de trabajo de forma segura

Estos permisos elevados aseguran que la acción pueda procesar traducciones de colaboradores externos de manera segura mientras mantiene la seguridad del repositorio mediante checkout selectivo de archivos.

Este enfoque:

Solo hace checkout de archivos de traducción del fork
Previene la exposición de código sensible del repositorio
Mantiene los permisos de escritura necesarios para la acción

Configuración avanzada

Personaliza el comportamiento de la acción utilizando parámetros adicionales:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    commit-message: "feat: actualizar traducciones vía lingo.dev"
    working-directory: "apps/web"
    version: "latest"
    process-own-commits: false
    parallel: true

Opciones de configuración:

commit-message — Mensaje personalizado para commits de traducción
working-directory — Ejecutar la acción en un subdirectorio
version — Fijar a una versión específica de CLI (no recomendado)
process-own-commits — Procesar commits realizados por esta acción
parallel — Habilitar procesamiento paralelo de tareas de localización (predeterminado: false)

Procesamiento paralelo

La GitHub Action soporta procesamiento paralelo de tareas de localización para acelerar significativamente los flujos de trabajo de traducción para proyectos grandes. Habilita esta función configurando parallel: true:

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    parallel: true

Cuando está habilitado, la acción:

Distribuye tareas de localización entre múltiples trabajadores concurrentes
Utiliza algoritmos inteligentes de distribución de tareas para maximizar el rendimiento
Previene la corrupción de archivos y condiciones de carrera mediante una cuidadosa gestión de concurrencia
Reduce drásticamente el tiempo de procesamiento para proyectos con muchos archivos de traducción

Esta función es particularmente beneficiosa para:

Proyectos grandes con extensos requisitos de traducción
Flujos de trabajo que procesan múltiples locales simultáneamente
Equipos que requieren una ejecución más rápida del pipeline CI/CD

Nota: El procesamiento paralelo puede aumentar el uso de API. Monitoriza tu uso si tienes límites estrictos de tasa.

Modo de verificación

Usando el flag --frozen, puedes verificar que todas las traducciones estén actualizadas antes de cada despliegue a producción.

Aquí hay un ejemplo de cómo usar el flag --frozen en tu pipeline de despliegue:

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx lingo.dev@latest i18n --frozen
      - run: npm run build
      - run: npm run deploy

El flag --frozen:

Verifica que todas las traducciones estén actualizadas
No realiza cambios en los archivos
Hace fallar la compilación si faltan traducciones o están desactualizadas