Integración de Lingo.dev con Bitbucket

La Integración de Lingo.dev con Bitbucket Pipelines es una integración de CI/CD segura y de código abierto que localiza automáticamente el contenido nuevo y evita que las traducciones incompletas lleguen a producción. Crea solicitudes de extracció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 permanecen 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 extracció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 extracción;
  4. 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

La Integración de Lingo.dev con Bitbucket 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 Configuración del repositorio → Variables del repositorio, 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 un token de acceso de Bitbucket (para modo de solicitud de extracción)

Si planeas usar el modo de solicitud de extracción, crea un token de acceso:

  1. Ve a Configuración del repositorio → Tokens de acceso → Crear token de acceso al repositorio
  2. Otorga estos permisos:
    • Leer y escribir repositorios
    • Leer y escribir solicitudes de extracción
  3. Añade el token como una variable de repositorio:
    • Nombre de variable: BB_TOKEN
    • Valor de variable: Tu token de acceso de Bitbucket

Paso 2. Crear el flujo de trabajo

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

script:
  - pipe: lingodotdev/lingo.dev:main

Esta configuración utiliza el pipe de Lingo.dev y ejecuta el motor de traducción automáticamente.

Permisos requeridos

Bitbucket Pipelines requiere acceso a 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

Para el modo de solicitud de extracción:

  • BB_TOKEN — Requerido para crear y gestionar solicitudes de extracción

Ámbitos del token de acceso (cuando se utiliza el modo de solicitud de extracción):

  • Leer y escribir repositorios — Acceder y modificar el contenido del repositorio
  • Leer y escribir solicitudes de extracción — Crear y gestionar solicitudes de extracción

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

Paso 3. Elegir tu modo de flujo de trabajo

La integración de Lingo.dev con Bitbucket 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:

script:
  - pipe: lingodotdev/lingo.dev:main

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 extracción

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

script:
  - pipe: lingodotdev/lingo.dev:main
    variables:
      LINGODOTDEV_PULL_REQUEST: "true"

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

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

Requisitos del token de acceso: Tu BB_TOKEN debe incluir permisos de lectura y escritura tanto para repositorios como para solicitudes de extracción.

Nota: La variable BB_TOKEN es obligatoria cuando se utiliza el modo de solicitud de extracció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 Bitbucket se adapta a diferentes flujos de trabajo de desarrollo. Comprender estos escenarios te ayuda a elegir la configuración correcta para tu equipo.

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

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main

Flujo: Cambios de contenido enviados a la rama de características → La integración hace 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: Pull Requests para actualizaciones (modo Pull Request)

Disparador: Push a cualquier rama configurada Acción: Crea pull request con actualizaciones de traducción

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}" # o OPENAI_API_KEY/ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

Flujo: Cambios de contenido enviados a la rama → La integración crea pull request 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 motor Lingo.dev:

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}"
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

Ejemplo con API LLM directa:

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                OPENAI_API_KEY: "${MY_OPENAI_API_KEY}" # o ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

Opciones de configuración:

  • LINGODOTDEV_API_KEY — Tu clave API del motor Lingo.dev, si estás utilizando el motor Lingo.dev
  • OPENAI_API_KEY — Tu clave API de OpenAI, si estás utilizando la API LLM directa
  • ANTHROPIC_API_KEY — Tu clave API de Anthropic, si estás utilizando la API LLM directa
  • LINGODOTDEV_PULL_REQUEST — Crear pull request en lugar de commit directo (predeterminado: false)
  • LINGODOTDEV_PULL_REQUEST_TITLE — Título personalizado del pull request (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)
  • BB_TOKEN — Token de acceso de Bitbucket (requerido para el modo pull request)