Receta para Bitbucket Pipelines

Traduce archivos en Bitbucket Pipelines, guarda el resultado en el repositorio mediante un commit y haz que fallen las solicitudes de incorporación con traducciones desactualizadas.

Usa un pipeline de Bitbucket para traducir los archivos de origen que selecciona tu configuración de Lingo.dev. La CLI envía el trabajo y descarga los archivos de destino; tu pipeline decide cómo conservarlos y entregarlos. Esta receta empieza con un pipeline personalizado que se lanza manualmente, para que puedas revisar una traducción antes de programar trabajos recurrentes.

La conexión es una llamada a la API desde tu ejecutor, no un conector nativo de cuentas de Bitbucket. Para escribir en el repositorio y crear solicitudes de incorporación de cambios necesitas permisos de Bitbucket independientes.

Prepara un catálogo funcional #

Sigue la guía de inicio rápido de la CLI en local y, después, haz commit de .lingo/config.json, los archivos de destino revisados y .lingo/lock.json. Los idiomas de origen y destino, el motor de localización y los patrones de archivos se definen en esa configuración.

El ejemplo utiliza locales/en.json y un archivo en español ya existente en locales/es.json como único destino. Si hay 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 origen como traducido, por lo que el siguiente envío lo omite, y cualquier destino que quede fuera del artefacto seguirá 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 del origen. Un envío normal procesa los cambios posteriores del origen; la creación de los archivos que faltan no corrige la ausencia de claves en un destino existente.

Guarda LINGO_API_KEY como variable protegida del repositorio. La CLI solo lee este nombre; ignora la variable LINGODOTDEV_API_KEY de la CLI anterior, así que cámbiale el nombre. Ejecuta la canalización con código de confianza y desactiva el seguimiento de comandos del shell cuando se manejen credenciales. Proteger una variable no significa que sea seguro exponerla a scripts arbitrarios de una solicitud de incorporación.

Los ejemplos usan una versión fija de la CLI: la 1.21.0. lingo check comprueba los archivos de traducción desde la versión 1.20.0 de la CLI. Para gestionar la versión a través de las dependencias de tu proyecto y del Lockfile, sigue la guía de configuración de CI.

Traduce y conserva el resultado #

Añade este pipeline personalizado 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. Adapta las rutas de los archivos a tu configuración.

Comprueba los ID de la organización y del motor en el archivo .lingo/config.json incluido en el commit. Haz commit de una pequeña modificación del origen en inglés y ejecuta translate-catalog en esa rama de confianza. Revisa el resultado de la ejecución y las diferencias; después, descarga el artefacto y compara la entrada modificada en español con la revisión del origen. Carga el catálogo en la aplicación para comprobar las variables y cómo se muestra el texto.

Comprobar que los archivos existen y que el JSON se analiza correctamente permite detectar resultados ausentes o mal formados. Sin embargo, estas comprobaciones no distinguen un archivo antiguo pero válido de la nueva traducción que has solicitado. Si el motor de localización exige revisión humana, completa la revisión y recupera los resultados finalizados antes de aceptar el artefacto.

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

El envío es asíncrono por defecto. push --wait espera a que termine la ejecución y escribe los archivos traducidos en el checkout. Sin --wait, lingo push solo envía la ejecución y termina, por lo que el siguiente comando no encuentra archivos nuevos que conservar o incluir en un commit. Si hay que esperar a una revisión humana, puede seguir siendo necesario recuperar los resultados en un paso posterior.

Antes de una espera por revisión o de un paso de recuperación separado, añade el procedimiento de conservación del estado de ejecución de CI. Exporta el puntero concreto 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, con un periodo de retención suficiente para la revisión. Mantén visible el fallo del paso original y no archives nunca todo ~/.lingo ni las credenciales.

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

Elige cómo llegan los resultados al repositorio #

Un artefacto es suficiente cuando una persona o un trabajo de publicación posterior debe revisar los resultados antes de entregarlos. Conserva juntos los archivos traducidos y el lockfile de la misma operación finalizada.

Para actualizar el repositorio tras una revisión, envía los cambios a una rama de traducción y abre después una solicitud de incorporación en Bitbucket o mediante su API documentada. Un paso puede enviar cambios a su propio repositorio a través del origin predeterminado, sin credenciales adicionales, como muestra la siguiente sección. Añade una clave SSH del repositorio o un token de acceso solo si los permisos de la rama bloquean el envío, o si vas a crear la solicitud de incorporación mediante la API, que requiere permisos de escritura para esas solicitudes. Configura la identidad del bot del equipo, prepara para el commit solo las rutas de destino conocidas y .lingo/lock.json, y termina si no hay cambios preparados. 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 aplica las mismas comprobaciones de resultados y la misma preparación restringida, pero envía los cambios a la rama de confianza indicada de forma explícita. Entregar directamente en la rama predeterminada elimina la revisión de la solicitud de incorporación de cambios de la traducción, así que debe ser una decisión deliberada de tu política de ramas. En ambos modelos, revisa el resultado final en la aplicación.

Mantén la clave de API de Lingo.dev separada de las credenciales del repositorio. Su sitio es el entorno del proceso de traducción, nunca un remoto de Git, un archivo con commit ni un artefacto de salida. Añade rutas explícitas al área de preparación en lugar de git add . para no recopilar archivos del ejecutor que no tengan nada que ver.

Guarda las traducciones en la rama mediante un commit#

Esta canalización de rama traduce cada cambio que llega a main y guarda el resultado en main mediante un commit. Se presupone que la traducción inicial ya está guardada en un commit y que la revisión humana del motor está desactivada, de modo que la traducción termina en un solo paso. Añade 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 si falla un destino, por lo que el paso se detiene antes del commit. Si no hay cambios, muestra "No hay nada que enviar", no hay cambios preparados y el paso termina sin crear un commit.

Pipelines configura el remoto origin para que un paso pueda enviar cambios a su propio repositorio sin credenciales adicionales. El bloque auth del paso concede a su token integrado acceso para enviar cambios mediante Git. A partir del 30 de abril de 2027, Bitbucket dejará de conceder ese acceso a los pasos que no tengan un bloque auth. Los ejecutores autoalojados necesitan la versión 6.1.0 o posterior para usar auth. Si una restricción de rama en main bloquea el envío, añade main como rama de origen en el apartado de 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, tal como se describe en la guía de Bitbucket para enviar cambios al repositorio.

El paso no entra en bucle. Incluir [skip ci] en el mensaje del commit impide que Bitbucket inicie una canalización para el commit de traducción. Sin ello, la siguiente ejecución no encontraría nada que enviar, porque el .lingo/lock.json guardado en el commit ya registra el nuevo contenido de origen. Si la rama avanza durante la traducción, Git rechaza el envío; la canalización del commit más reciente se encarga de traducirlo.

Adapta los activadores y las rutas de los paquetes #

Añade activadores automáticos para ramas o solicitudes de incorporación de cambios solo después de decidir qué código puede acceder a las credenciales y qué rama puede recibir escrituras. Un fork puede no tener acceso a los secretos ni a un destino con permisos de escritura; no lo soluciones ejecutando su código no fiable con credenciales privilegiadas.

Los commits generados no deben activar la traducción en bucle. Selecciona las rutas de origen pertinentes y las ramas de confianza, aplica una regla adecuada para los commits generados y mantén la salida cuando no haya cambios. Es perfectamente normal que un origen sin cambios no produzca diferencias.

Si la configuración está en apps/web/.lingo/config.json, ejecuta la CLI desde apps/web. Las rutas de los artefactos del pipeline 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 incorporación con traducciones desactualizadas #

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

Comprueba archivos, no claves: un destino editado a mano supera la comprobación y no se notifican las claves que falten en un destino existente, salvo en los catálogos .jsonc de React. Sin .lingo/lock.json no puede detectar cambios en el origen, por lo que un origen modificado o que nunca se haya enviado no hace que la comprobación falle; esta limitación se indica en stderr. Incluye en un commit el Lockfile que genera lingo push.

Este control está pensado para una configuración sin la canalización de rama anterior; la tabla siguiente explica por qué. Añade una sección pull-requests bajo pipelines, junto a custom si mantienes la canalización manual. El archivo con solo este control 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 encaja en una configuración en la que las traducciones se guardan mediante un commit junto con el cambio del contenido de origen:

Dónde se ejecuta la traducciónControl en cada solicitud de incorporación
El equipo de desarrollo ejecuta lingo push --wait y guarda el resultado en un commit antes de abrir la solicitud de incorporaciónSí. Hace que falle una solicitud de incorporación si el contenido de origen ha cambiado sin traducirse.
La canalización de rama guarda el resultado en main mediante un commit después de la fusiónNo. Por diseño, las solicitudes de incorporación de nuevas funcionalidades cambian el contenido de origen antes de traducirlo.

Los hashes del contenido de origen dependen de cada byte. 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 comprobaciones de recursos de la aplicación.

Recupera los resultados que faltan o detén el trabajo #

Si faltan resultados, revisa los archivos de origen seleccionados, el estado de referencia, la cobertura de los archivos de destino, la disponibilidad de las variables protegidas, el estado de revisión y los fallos notificados. Recupera la ejecución registrada antes de decidirte por otro envío. Antes de crear los archivos de destino que falten en un proyecto existente, completa, recupera y revisa las actualizaciones habituales de sus archivos de destino actuales; después, mantén fija la revisión del origen mientras creas los que faltan. Sigue Añadir un idioma para esa secuencia. Usa la regeneración forzada solo cuando de verdad quieras reemplazar el texto aceptado seleccionado; recuperación de ejecuciones fallidas explica cómo solicitar otro intento sin forzar el reemplazo.

Desactiva el activador del pipeline para detener nuevos trabajos. Al cancelar el ejecutor, revisa por separado cualquier ejecución que ya se haya enviado al servidor. Cuando retires la receta, elimina las variables de API que ya no uses y el acceso de escritura del proveedor.