Integración de Lingo.dev con GitLab

La Integración de CI/CD de Lingo.dev con GitLab es una integración de 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 fusión o commits directamente en tu rama, dependiendo de los requisitos de flujo de trabajo de tu equipo.

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

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

1. Commits directos a ramas cuando se envían cambios de contenido
2. Solicitudes de fusión dirigidas a ramas para actualizaciones de traducción

Al completar esta guía, podrás:

1. Configurar la localización automatizada activada por envíos de código;
2. Configurar la autenticación segura utilizando variables de repositorio;
3. Elegir entre flujos de trabajo de commits directos o solicitudes de fusión;
4. Entender 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

La Integración de Lingo.dev con GitLab necesita acceso a tu motor de traducción y repositorio. La autenticación se realiza a través de variables de repositorio que mantienen tus credenciales seguras.

Añade tu clave API

Navega a Ajustes de tu repositorio → CI/CD → Variables, luego añade las credenciales de tu motor de traducción:

Para usuarios de API LLM sin procesar:

• Nombre de variable: OPENAI_API_KEY o ANTHROPIC_API_KEY
• Valor de variable: Tu clave API del proveedor respectivo

Para usuarios de Lingo.dev Engine:

• Nombre de variable: LINGODOTDEV_API_KEY
• Valor de variable: Tu clave API de proyecto de lingo.dev/app

Añade el token de acceso de GitLab

Crea un token de acceso personalizado para operaciones de repositorio:

1. Ve a Ajustes → Tokens de acceso → Añadir nuevo token
2. Otorga estos ámbitos:
   • api
   • read_repository
   • write_repository
3. Añade el token como una variable de repositorio:
   • Nombre de variable: GL_TOKEN
   • Valor de variable: Tu token de acceso de GitLab

Importante: El token de trabajo CI predeterminado no es suficiente. Debes crear un token de acceso personalizado ya que el token predeterminado carece de los permisos necesarios para operaciones git.

Nota: Para ramas protegidas, asegúrate de que tus variables también estén marcadas como protegidas. Las variables no protegidas no serán accesibles en los pipelines de ramas protegidas.

Paso 2. Crear el flujo de trabajo

Crea o actualiza tu archivo .gitlab-ci.yml con esta configuración básica:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

Esta configuración utiliza la imagen Docker más reciente y ejecuta el motor de traducción automáticamente.

Permisos requeridos

GitLab CI/CD requiere acceso a las variables del repositorio y operaciones git:

Variables del repositorio:

• LINGODOTDEV_API_KEY — Requerida para usuarios del motor Lingo.dev
• OPENAI_API_KEY o ANTHROPIC_API_KEY — Requeridas para usuarios de API LLM sin procesar
• GL_TOKEN — Requerido para operaciones de git push y creación de solicitudes de fusión

Ámbitos del token de acceso:

• api — Crear y gestionar solicitudes de fusión
• read_repository — Acceder al contenido del repositorio
• write_repository — Enviar commits y crear ramas

Estos permisos permiten a la integración leer tu contenido, generar traducciones y actualizar tu repositorio con el contenido localizado.

Paso 3. Elegir el modo de flujo de trabajo

La integración de Lingo.dev con GitLab admite dos modos operativos según los requisitos de revisión de código de tu equipo.

Modo de commit directo (predeterminado)

La integración realiza commits de traducciones directamente a tu rama:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

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 solicitud de fusión

La integración crea solicitudes de fusión para actualizaciones de traducción:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_PULL_REQUEST: "true"
  script:
    - echo "Done"

Configuración requerida para el modo de solicitud de fusión

Variables del repositorio: Tanto LINGODOTDEV_API_KEY como GL_TOKEN deben configurarse como variables del repositorio.

Requisitos del token de acceso: Tu GL_TOKEN debe incluir el ámbito api para crear y gestionar solicitudes de fusión.

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

La integración de Lingo.dev con GitLab se adapta a diferentes flujos de trabajo de desarrollo. Comprender estos escenarios te ayuda a elegir la configuración adecuada para tu equipo.

Escenario 1: Actualizaciones de ramas de características (commits directos)

Disparador: Push a ramas de características Acción: Realiza commits de actualizaciones de traducción directamente a la rama de características

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Flujo: Cambios de contenido enviados a la rama de características → La integración realiza commits de traducciones a la misma rama

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 2: Solicitudes de fusión para actualizaciones (modo de solicitud de fusión)

Disparador: Push a cualquier rama configurada Acción: Crea una solicitud de fusión con actualizaciones de traducción

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY # o OPENAI_API_KEY/ANTHROPIC_API_KEY
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
  script:
    - echo "Done"

Flujo: Cambios de contenido enviados a la rama → La integración crea una solicitud de fusión con traducciones

Esto mantiene revisiones separadas para las actualizaciones de traducción.

Configuración avanzada

Personaliza el comportamiento de la integración utilizando variables adicionales:

Ejemplo con el motor de Lingo.dev:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Ejemplo con API LLM sin procesar:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    OPENAI_API_KEY: $MY_OPENAI_API_KEY # o ANTHROPIC_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

Opciones de configuración:

• LINGODOTDEV_API_KEY — Tu clave API del motor de Lingo.dev, si estás utilizando el motor de Lingo.dev
• OPENAI_API_KEY — Tu clave API de OpenAI, si estás utilizando la API LLM sin procesar
• ANTHROPIC_API_KEY — Tu clave API de Anthropic, si estás utilizando la API LLM sin procesar
• LINGODOTDEV_PULL_REQUEST — Crear solicitud de fusión en lugar de commit directo (predeterminado: false)
• LINGODOTDEV_PULL_REQUEST_TITLE — Título personalizado para la solicitud de fusión (predeterminado: feat: update translations via @lingodotdev)
• LINGODOTDEV_COMMIT_MESSAGE — Mensaje de commit personalizado (predeterminado: feat: update translations via @lingodotdev)
• LINGODOTDEV_WORKING_DIRECTORY — Ejecutar la integración en un subdirectorio (predeterminado: .)
• LINGODOTDEV_PROCESS_OWN_COMMITS — Procesar commits realizados por esta integración (predeterminado: false)

Solución de problemas

Errores comunes y sus soluciones: