Bitbucket Pipelines

Traducción automática con Bitbucket Pipelines y Lingo.dev CI/CD

Integración de Lingo.dev con Bitbucket Pipelines es una integración CI/CD de código abierto y segura que localiza contenido nuevo automáticamente y evita que traducciones incompletas lleguen a producción. Puede crear pull requests o hacer commits directos a tu rama, según lo que necesite tu equipo.

También implementa la resolución automática de conflictos mediante rebase, así tus traducciones se mantienen sincronizadas con el código sin intervención manual.

La integración soporta varios escenarios de flujo de trabajo:

  1. Commits directos a las ramas cuando se realizan cambios en el contenido
  2. Pull requests dirigidos a ramas para actualizar traducciones

Al terminar esta guía, podrás:

  1. Configurar la localización automática activada por pushes de código;
  2. Configurar autenticación segura usando variables del repositorio;
  3. Elegir entre flujos de trabajo de commits directos o pull requests;
  4. Comprender cómo la localización continua se integra en tu proceso actual.

¡Empecemos!

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 tienes listo, primero completa 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 mediante variables del repositorio que mantienen tus credenciales seguras.

Agrega tu clave API

Ve a Configuración del repositorio → Variables del repositorio en tu repositorio y agrega las credenciales de tu motor de traducción:

Para usuarios de API LLM sin intermediarios:

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

Para usuarios de Lingo.dev Engine:

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

Agrega el token de acceso de Bitbucket (Para modo Pull Request)

Si piensas usar el modo pull request, crea un token de acceso:

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

Paso 2. Crea el workflow

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 necesita acceso a las variables del repositorio y operaciones de git:

Variables del repositorio:

  • LINGODOTDEV_API_KEY — Requerido para usuarios del motor de Lingo.dev
  • OPENAI_API_KEY o ANTHROPIC_API_KEY — Requerido para usuarios de la API LLM sin procesar

Para el modo Pull Request:

  • BB_TOKEN — Necesario para crear y administrar pull requests

Ámbitos del token de acceso (al usar el modo pull request):

  • Leer y escribir repositorios — Acceder y modificar el contenido del repositorio
  • Leer y escribir pull requests — Crear y administrar pull requests

Estos permisos permiten que la integración lea tu contenido, genere traducciones y actualice tu repositorio con el contenido localizado.

Paso 3. Elige tu modo de workflow

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

Modo de commit directo (por defecto)

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

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

Este modo es ideal para:

  • Desarrolladores individuales o equipos pequeños
  • Ramas de funcionalidades que serán revisadas antes de hacer merge
  • Proyectos donde las actualizaciones de traducción no requieren revisión aparte

Modo Pull Request

La integración crea solicitudes de extracción para las 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 estar configuradas como variables del repositorio.

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

Nota: La variable BB_TOKEN es obligatoria al usar el modo de solicitud de extracción.

Este modo es ideal para:

  • Teams con requisitos estrictos de revisión de código
  • Proyectos donde los cambios de traducción necesitan una aprobación por separado
  • 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 distintos flujos de trabajo de desarrollo. Comprender estos escenarios te ayuda a elegir la configuración adecuada para tu Team.

Escenario 1: Actualizaciones en Ramas de Funcionalidades (Commits Directos)

Disparador: Push a ramas de funcionalidad Acción: Realiza commits de actualizaciones de traducción directamente en la rama de funcionalidad

image:
  name: atlassian/default-image:2

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

Flujo: Se suben cambios de contenido a la rama de funcionalidad → La integración agrega las traducciones a esa misma rama

Esto mantiene las actualizaciones de traducción dentro de la rama de funcionalidad, asegurando que sean revisadas junto con los cambios originales.

Escenario 2: Solicitudes de Extracción para Actualizaciones (Modo de Pull Request)

Disparador: Push a cualquier rama configurada Acción: Crea una solicitud de extracción con las 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}" # or 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: Se suben cambios de contenido a la rama → La integración crea la solicitud de extracción con las traducciones

Esto permite que las actualizaciones de traducción se revisen por separado.

Configuración avanzada

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

Ejemplo con el motor de 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 sin procesar:

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}" # or 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 de Lingo.dev Engine, si usas Lingo.dev Engine
  • OPENAI_API_KEY — Tu clave API de OpenAI, si usas la API LLM directamente
  • ANTHROPIC_API_KEY — Tu clave API de Anthropic, si usas la API LLM directamente
  • LINGODOTDEV_PULL_REQUEST — Crear una solicitud de extracción en vez de un commit directo (por defecto: false)
  • LINGODOTDEV_PULL_REQUEST_TITLE — Título personalizado para la solicitud de extracción (por defecto: feat: update translations via @lingodotdev)
  • LINGODOTDEV_COMMIT_MESSAGE — Mensaje personalizado para el commit (por defecto: feat: update translations via @lingodotdev)
  • LINGODOTDEV_WORKING_DIRECTORY — Ejecutar la integración en un subdirectorio (por defecto: .)
  • LINGODOTDEV_PROCESS_OWN_COMMITS — Procesar los commits realizados por esta integración (por defecto: false)
  • BB_TOKEN — Token de acceso Bitbucket (requerido en el modo de solicitud de extracción)