Guía para Bitbucket Pipelines

Traduce archivos en Bitbucket Pipelines, confirma los resultados en el repositorio y haz que fallen las solicitudes de extracción con traducciones desactualizadas.

Usa una canalización de Bitbucket para traducir los archivos de origen seleccionados en tu configuración de Lingo.dev. La CLI envía el trabajo y descarga los archivos de destino; tu canalización determina cómo conservarlos y entregarlos. Esta guía comienza con una canalización personalizada de ejecución manual para que puedas revisar una traducción antes de programar tareas recurrentes.

La conexión se realiza mediante una llamada a la API desde tu ejecutor, no mediante un conector nativo para cuentas de Bitbucket. Escribir en el repositorio y crear solicitudes de incorporación de cambios requiere permisos independientes de Bitbucket.

Prepara un catálogo funcional #

Sigue la guía de inicio rápido de la CLI en tu entorno local y luego incluye en un commit .lingo/config.json, los archivos de destino revisados y .lingo/lock.json. Esa configuración debe definir los idiomas de origen y destino, el motor de localización y los patrones de archivos.

El ejemplo usa locales/en.json y tiene como único destino un archivo en español que ya existe en locales/es.json. Si tienes más destinos, ejecuta test -s y las comprobaciones de JSON una vez por cada archivo de destino, e incluye todas las rutas de destino en los demás comandos que mencionan locales/es.json. El Lockfile registra el contenido de origen como traducido, por lo que un push posterior lo omite, y cualquier destino que quede fuera del artefacto permanece desactualizado. Crea los archivos de destino que falten con lingo push --backfill-missing --wait antes de empezar a usar el comando que se muestra a continuación para procesar los cambios recurrentes en el contenido de origen. El comando push habitual procesa las modificaciones posteriores del contenido de origen; la creación de archivos faltantes no corrige las claves que faltan en un destino existente.

Guarda LINGO_API_KEY como una variable protegida del repositorio. La CLI solo lee este nombre e ignora una variable LINGODOTDEV_API_KEY de la CLI anterior, así que cámbiale el nombre. Ejecuta la canalización con código de confianza y mantén desactivado el rastreo del shell al trabajar con credenciales. Proteger una variable no significa que sea seguro exponerla a scripts arbitrarios de una solicitud de extracción.

Los ejemplos usan la versión fija 1.21.0 de la CLI. lingo check verifica los archivos de traducción a partir de la versión 1.20.0 de la CLI. Para gestionar la versión mediante las dependencias y el Lockfile de tu proyecto, sigue la guía de configuración de CI.

Traduce y conserva el resultado #

Agrega esta canalización personalizada a bitbucket-pipelines.yml:

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          script:
            # Replace 1.21.0 with the current CLI version.
            - npx -y @lingo.dev/cli@1.21.0 push --wait
            - 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
          artifacts:
            - locales/es.json
            - .lingo/lock.json

Asegúrate de que el ejecutor pueda descargar la CLI desde npm. Ajusta las rutas de los archivos a tu configuración.

Verifica los ID de la organización y del motor en .lingo/config.json, incluido en el commit. Crea un commit con un pequeño cambio en el contenido de origen en inglés y ejecuta translate-catalog en esa rama de confianza. Revisa el resultado de la ejecución y las diferencias; luego descarga el artefacto y compara la entrada modificada en español con la versión del contenido de origen. Carga el catálogo en la aplicación para comprobar las variables y la visualización.

Comprobar que los archivos existan y analizar el JSON permite detectar resultados faltantes o con formato incorrecto. Estas comprobaciones no distinguen un archivo antiguo y válido de la nueva traducción que solicitaste. Si el motor de localización requiere una revisión humana, completa la revisión y recupera el resultado finalizado antes de aceptar el artefacto.

Conserva el estado de envío y recuperación #

El envío es asíncrono de forma predeterminada. push --wait espera a que termine la ejecución y escribe los archivos traducidos en el checkout. Sin --wait, lingo push solo solicita la ejecución y termina, por lo que el siguiente comando no encuentra archivos nuevos para conservar o confirmar. Las esperas por revisión humana pueden requerir un paso posterior para recuperar los resultados.

Antes de esperar una revisión o de recuperar los resultados en un paso separado, agrega el procedimiento para conservar el estado de ejecución de CI. Exporta el puntero específico y la ruta absoluta original de la raíz del proyecto después del envío, incluso si falla una validación posterior. Conserva .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 durante el tiempo necesario para la revisión. Mantén visible el fallo del paso original y nunca archives todo ~/.lingo ni las credenciales.

Para recuperar los resultados, restaura la misma revisión y el estado de los archivos conservados en la ruta raíz absoluta registrada. Restaura solo ese puntero, proporciona las credenciales por separado y usa Pull con --dry-run antes de recopilar los resultados. Si un paso posterior de la canalización no puede recrear la ruta, usa un ejecutor persistente autorizado tanto para el envío como para la recuperación. Resuelve los conflictos de los resultados locales de forma deliberada; forzar un pull puede descartar los cambios de quien hizo la revisión.

Elige cómo llega el resultado al repositorio #

Un artefacto basta cuando una persona o una tarea de publicación posterior debe revisar el resultado antes de entregarlo. Conserva juntos los archivos traducidos y el Lockfile de la misma operación finalizada.

Para actualizar el repositorio con una revisión previa, envía los cambios a una rama de traducción y luego abre una solicitud de extracción en Bitbucket o mediante su API documentada. Un paso puede enviar cambios a su propio repositorio a través del origin predeterminado sin una credencial adicional, como muestra la siguiente sección. Agrega una clave SSH del repositorio o un token de acceso solo si los permisos de la rama bloquean ese envío, o para crear la solicitud de extracción mediante la API, que requiere acceso de escritura a las solicitudes de extracción. Configura la identidad del bot del equipo, prepara para la confirmación solo las rutas de destino conocidas y .lingo/lock.json, y termina si no hay diferencias preparadas. Usa nombres de rama distintos o reutiliza las ramas de forma deliberada para que las ejecuciones simultáneas no se sobrescriban entre sí.

Un commit directo usa las mismas comprobaciones de resultados y las mismas restricciones al agregar archivos al área de preparación, pero envía los cambios a la rama de confianza elegida explícitamente. La entrega directa a la rama predeterminada elimina el paso de revisión de la solicitud de incorporación de cambios de la traducción, por lo que debe ser una decisión deliberada de la política de ramas. Revisa el resultado en la aplicación con cualquiera de los dos modelos.

Mantén la clave de API de Lingo.dev separada de las credenciales del repositorio. Debe estar en el entorno del proceso de traducción, nunca en un remoto de Git, un archivo incluido en un commit ni un artefacto de salida. Agrega rutas explícitas al área de preparación en lugar de git add . para evitar recopilar archivos del ejecutor que no estén relacionados.

Confirma las traducciones en la rama #

Esta canalización de rama traduce cada cambio que llega a main y confirma el resultado en main. Supone que la traducción inicial de todo el contenido ya está confirmada y que la revisión humana del motor está desactivada, de modo que la traducción termina en un solo paso. Agrega su sección branches bajo la misma clave pipelines que la canalización personalizada. El archivo completo queda así:

yaml
image: node:22

pipelines:
  custom:
    translate-catalog:
      - step:
          name: Translate and inspect
          script:
            - npx -y @lingo.dev/cli@1.21.0 push --wait
            - 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
          artifacts:
            - locales/es.json
            - .lingo/lock.json
  branches:
    main:
      - step:
          name: Translate and commit
          auth:
            system:
              scopes:
                - read:git:bitbucket
                - write:git:bitbucket
          script:
            # Replace 1.21.0 with the current CLI version.
            - npx -y @lingo.dev/cli@1.21.0 push --wait
            - test -s locales/es.json
            - node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
            - git add -- locales/es.json .lingo/lock.json
            - if git diff --cached --quiet; then exit 0; fi
            - git config user.name "Localization bot"
            - git config user.email "localization@example.com"
            - git commit -m "[skip ci] Update translations"
            - git push origin "HEAD:$BITBUCKET_BRANCH"

lingo push --wait termina con un código distinto de cero cuando falla un destino, por lo que el paso se detiene antes de confirmar los cambios. Si nada cambió, muestra "No hay nada que enviar", no hay diferencias preparadas y el paso termina sin confirmar cambios.

Pipelines configura el remoto origin para que un paso pueda enviar cambios a su propio repositorio sin una credencial adicional. El bloque auth del paso otorga a su token integrado acceso para enviar cambios con Git. A partir del 30 de abril de 2027, Bitbucket dejará de otorgar ese acceso a los pasos que no tengan un bloque auth. Los ejecutores autohospedados necesitan la versión 6.1.0 o posterior para usar auth. Si una restricción de rama en main bloquea el envío, agrega main como rama de origen en el acceso de escritura de Pipelines de esa restricción, o proporciona al paso una clave SSH o un token de acceso con permisos de escritura, como se describe en la guía de Bitbucket para enviar cambios al repositorio.

El paso no entra en un bucle. [skip ci] en el mensaje de confirmación impide que Bitbucket inicie una canalización para la confirmación de las traducciones. Sin él, la siguiente ejecución no encontraría nada que enviar, porque el .lingo/lock.json confirmado ya registra el nuevo contenido de origen. Si la rama avanzó durante la traducción, Git rechaza el envío; la canalización de la confirmación más reciente traduce ese cambio.

Ajusta los activadores y las rutas de los paquetes #

Agrega activadores automáticos para ramas o solicitudes de incorporación de cambios solo después de decidir qué código de origen puede acceder a las credenciales y qué rama puede recibir escrituras. Una bifurcación puede no tener secretos ni un destino con acceso de escritura; no lo resuelvas ejecutando su código no confiable con credenciales privilegiadas.

Los commits generados no deben activar la traducción indefinidamente. Selecciona las rutas de origen pertinentes y las ramas de confianza, aplica una regla adecuada para los commits generados y conserva la condición de salida cuando no haya cambios. Es válido que un contenido de origen sin cambios no produzca diferencias.

Para una configuración en apps/web/.lingo/config.json, ejecuta la CLI desde apps/web. Las rutas de los artefactos de la canalización siguen las reglas de Bitbucket relativas al repositorio, así que usa rutas como apps/web/locales/es.json y apps/web/.lingo/lock.json. Cambiar el directorio de trabajo de la CLI no cambia la convención de rutas de los artefactos.

Haz que fallen las solicitudes de extracción con traducciones desactualizadas #

lingo check compara cada origen configurado con .lingo/lock.json y requiere que existan todos los archivos de destino. Finaliza con el código 1 cuando un origen cambió desde su última traducción, un origen no tiene una entrada en el Lockfile, falta un archivo de destino o ningún archivo de origen coincide con los patrones de files. No necesita una clave de API ni una variable de repositorio y no escribe nada. Salvo por la telemetría de la CLI, que se desactiva con DO_NOT_TRACK=1, no realiza llamadas de red; el ejemplo de npx sigue descargando la CLI desde npm antes de ejecutar la comprobación. Reemplaza la verificación de --frozen de la CLI anterior.

Comprueba archivos, no claves: un destino editado a mano pasa la comprobación, y no se informa si falta una clave en un destino existente, excepto en los catálogos .jsonc de React. Sin .lingo/lock.json no puede detectar cambios en el contenido de origen, por lo que un origen modificado o que nunca se haya procesado con push no hace que la comprobación falle; esto se indica en stderr. Incluye en un commit el Lockfile que escribe lingo push.

Este control se usa en una configuración sin la canalización de rama descrita arriba; la siguiente tabla explica por qué. Agrega una sección pull-requests bajo pipelines, junto a custom si conservas la canalización manual. Por sí solo, el archivo queda así:

yaml
image: node:22

pipelines:
  pull-requests:
    "**":
      - step:
          name: Check translations
          script:
            # lingo check needs CLI 1.20.0 or newer.
            - npx -y @lingo.dev/cli@1.21.0 check

El control es adecuado para una configuración en la que las traducciones se confirman junto con el cambio en el contenido de origen:

Dónde se ejecuta la traducciónControl en cada solicitud de extracción
El equipo de desarrollo ejecuta lingo push --wait y confirma el resultado antes de abrir la solicitud de extracciónSí. Hace que falle una solicitud de extracción cuyo contenido de origen cambió sin traducirse.
La canalización de rama confirma los cambios en main después de la fusiónNo. Por diseño, las solicitudes de extracción de funcionalidades cambian el contenido de origen antes de la traducción.

Los hashes del contenido de origen reflejan los bytes exactos. Asegúrate de que el checkout que ejecutó lingo push y el checkout de CI usen los mismos finales de línea, por ejemplo, con * text=auto eol=lf en .gitattributes. Mantén también las verificaciones de recursos de la aplicación.

Recupera los resultados faltantes o detén el trabajo #

Si faltan resultados, revisa los archivos de origen seleccionados, la referencia inicial, la cobertura de los archivos de destino, la disponibilidad de las variables protegidas, el estado de la revisión y los fallos reportados. Recupera la ejecución registrada antes de optar por otro envío. Antes de crear los archivos de destino faltantes en un proyecto existente, completa, recupera y revisa las actualizaciones habituales de sus archivos de destino existentes; luego mantén fija la revisión del contenido de origen mientras creas los archivos faltantes. Sigue Agregar un idioma para conocer esa secuencia. Usa la regeneración forzada solo cuando quieras reemplazar el texto aceptado seleccionado; la recuperación de ejecuciones fallidas explica cómo solicitar otro intento sin forzar el reemplazo.

Desactiva el activador de la canalización para detener los trabajos nuevos. Al cancelar el ejecutor, revisa por separado cualquier ejecución ya enviada al servidor. Elimina las variables de API que ya no uses y el acceso de escritura del proveedor cuando dejes de usar esta configuración.