Receta para Buildkite
Traduce archivos en un pipeline de Buildkite, sube el resultado a la rama y haz que fallen las pull requests con traducciones desactualizadas.
Un paso de Buildkite puede traducir los archivos del repositorio con la CLI de Lingo.dev en tus propios agentes. La CLI envía los archivos de origen seleccionados en tu configuración de Lingo.dev y escribe los archivos traducidos en el checkout; tu pipeline decide cómo entregarlos. Buildkite gestiona los agentes, los secretos y el acceso al repositorio; Lingo.dev procesa los archivos mediante un motor de localización.
Esta es una receta de CI, no una conexión nativa con Buildkite. Empieza con un paso de traducción en la rama predeterminada o en las compilaciones de pull requests y revisa su primer commit. Añade la comprobación de pull requests solo en los casos en los que la tabla indique que este control es adecuado.
Prepara el repositorio y el agente #
Completa la guía de inicio rápido de la CLI en local. Incluye en un commit .lingo/config.json, los archivos de destino aceptados y .lingo/lock.json. La configuración selecciona el idioma de origen, los idiomas de destino, los patrones de archivos y el motor de localización. Los ejemplos usan locales/en.json como origen y un archivo de destino en español ya existente 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, o añade al área de preparación todo el directorio de destino, como locales/. El Lockfile registra el origen como traducido, de modo que un envío posterior lo omite y cualquier destino que quede fuera del commit seguirá desactualizado.
Crea los archivos de destino que falten con lingo push --backfill-missing --wait antes de incorporar el paso recurrente. Para los cambios posteriores en el origen, usa el comando habitual lingo push --wait. La creación de los archivos que faltan no corrige las claves ausentes en un archivo de destino existente.
El agente necesita Node.js, npm y Git, además de acceso de red al registro de npm y a Lingo.dev. La credencial del repositorio que utiliza el agente para el checkout, como una clave de despliegue, también debe permitir subir cambios a la rama en la que escribe el paso.
Guarda la clave de API de Lingo.dev como un secreto de Buildkite llamado LINGO_API_KEY. La CLI solo lee este nombre e ignora la variable LINGODOTDEV_API_KEY de la CLI anterior, así que cámbiale el nombre. Carga el secreto únicamente en el paso de traducción. La clave secrets: del paso requiere un agente de Buildkite de la versión 3.106.0 o posterior que se ejecute en el clúster donde está el secreto; los agentes de versiones anteriores hacen que el pipeline falle. En agentes más antiguos o que no pertenezcan a un clúster, elimina secrets: y exporta LINGO_API_KEY para ese paso desde un hook environment del agente o desde tu plugin de secretos.
Mantén desactivada la opción Permitir compilaciones de repositorios bifurcados de terceros en la configuración de GitHub del pipeline. Las pull requests de una bifurcación se compilan con el propio pipeline.yml de esa bifurcación, que puede añadir un paso que lea el secreto, y ningún if: de tu archivo puede impedirlo. Añade también una política de acceso al secreto para que solo puedan leerlo las compilaciones de este pipeline.
Los ejemplos fijan la versión 1.21.0 de la CLI. lingo check comprueba 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 sube el resultado a la misma rama #
Este paso traduce cada cambio que llega a la rama predeterminada y sube el resultado a esa misma rama. Da por hecho que los archivos de destino creados inicialmente ya están incluidos 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ñádelo a .buildkite/pipeline.yml:
steps:
- label: "Translate"
if: build.branch == pipeline.default_branch && build.pull_request.id == null
concurrency: 1
concurrency_group: "lingo-translations"
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# 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:refs/heads/$${BUILDKITE_BRANCH}"--wait hace que el paso espere a que termine la ejecución y escriba los archivos traducidos en el checkout. Sin él, lingo push solo envía la ejecución y termina, por lo que el paso no encuentra nada que incluir en un commit. lingo push --wait termina con un código distinto de cero cuando falla un destino, así que el paso se detiene antes de crear el commit. Cuando no hay cambios, muestra "Nada que subir", no hay diferencias en el área de preparación y el paso termina sin crear un commit.
Buildkite hace checkout de un único commit, no de una rama, por lo que el comando de envío especifica el nombre de la rama. $$ deja BUILDKITE_BRANCH para que el intérprete de comandos lo expanda al ejecutarse el paso; con un solo $, Buildkite escribiría el nombre de la rama en el texto del comando al subir el pipeline. concurrency y concurrency_group ejecutan una sola traducción a la vez. Si la rama ha avanzado durante la traducción, Git rechaza el envío; la compilación del commit más reciente se encarga de traducirlo.
El paso no entra en bucle. Buildkite omite las compilaciones de los commits cuyo mensaje contiene [skip ci]. Sin él, la siguiente compilación no encontraría nada que subir, porque el .lingo/lock.json incluido en el commit ya registra el nuevo origen.
Subir los cambios directamente a la rama predeterminada elimina la revisión de una pull request de traducción, así que hazlo solo como parte de una decisión deliberada sobre la política de ramas. Para revisar primero las traducciones, sube los cambios a una rama aparte, como lingo/translations, y abre una pull request con las herramientas de tu proveedor de Git.
Traduce en las compilaciones de pull requests #
Para traducir los cambios de origen de cada pull request en su propia rama, usa este paso en lugar del de la rama predeterminada. Parte de los mismos supuestos. Su if: omite las pull requests de bifurcaciones, porque el paso no puede subir cambios a la rama de una bifurcación.
El paso necesita dos ajustes en la configuración de GitHub del pipeline. Activa Compilar cuando se abra o actualice una pull request. Desactiva Compilar ramas o limita esta opción a la rama predeterminada. Con las compilaciones de ramas activadas, un envío a la rama de una pull request puede iniciar una compilación sin los datos de la pull request. El paso omite esa compilación, por lo que no se traduce nada ni se produce ningún fallo.
El if: no protege LINGO_API_KEY. Buildkite lo lee del propio pipeline.yml de la pull request, y una bifurcación puede modificar ese archivo. Por eso, las compilaciones de bifurcaciones deben seguir desactivadas, como indica la configuración inicial. Una pull request de una rama del repositorio también puede modificar el archivo, así que cualquier persona que pueda subir cambios a una rama puede leer la clave mediante este paso. Úsalo solo si todas las personas con permiso para subir cambios pueden disponer de la clave.
steps:
- label: "Translate pull request"
if: build.pull_request.id != null && build.pull_request.repository.fork != true
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# 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 "Update translations"
git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"El mensaje del commit no contiene [skip ci], y es intencionado. Buildkite compila el commit de traducción, el paso vuelve a ejecutarse, no encuentra nada que subir y termina sin crear un commit. Así, el bucle acaba tras una única compilación adicional. Esa compilación asigna un estado al commit más reciente de la pull request. Con [skip ci], el commit más reciente no tendría ninguna compilación de Buildkite, y una comprobación de estado obligatoria de Buildkite bloquearía la fusión.
La credencial de checkout del agente debe permitir subir cambios a las ramas de pull requests. Si la rama ha avanzado durante la traducción, Git rechaza el envío y el paso falla; la compilación del commit más reciente se encarga de traducirlo. Por tanto, dos envíos rápidos inician dos traducciones, y ambas se facturan. Activa Cancelar compilaciones intermedias en la configuración del pipeline para que un envío más reciente cancele la compilación anterior. Si la compilación anterior ya ha enviado una traducción, esa traducción no se cancela.
Haz que fallen las pull requests con traducciones desactualizadas #
lingo check compara cada origen configurado con .lingo/lock.json y exige que existan todos los archivos de destino. Termina con el código 1 cuando un origen ha cambiado desde su última traducción, un origen no tiene ninguna entrada en el Lockfile, falta un archivo de destino o ningún archivo de origen coincide con los patrones de files. No necesita ninguna clave de API ni ningún secreto y no escribe nada. Salvo la telemetría de la CLI, que DO_NOT_TRACK=1 desactiva, no realiza ninguna llamada de red; el ejemplo de npx sigue descargando la CLI desde npm antes de ejecutar la comprobación. Sustituye al control --frozen de la CLI anterior.
Comprueba archivos, no claves: un destino editado a mano pasa la comprobación y no se informa de 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 nunca enviado no hace que falle; la comprobación lo advierte en stderr. Incluye en un commit el Lockfile que escribe lingo push.
Añade este paso a .buildkite/pipeline.yml cuando la tabla siguiente indique que el control es adecuado. Está pensado para una configuración sin ninguno de los dos pasos de traducción anteriores, así que cada ejemplo de esta sección contiene una lista steps: completa para una configuración. Incorpora el paso del ejemplo a tu lista steps: existente en lugar de añadir una segunda clave steps::
steps:
- label: "Check translations"
if: build.pull_request.id != null
command:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkEl control es adecuado para una configuración en la que las traducciones se incluyen en un commit junto con el cambio de origen:
| Dónde se ejecuta la traducción | Control en cada pull request |
|---|---|
El equipo de desarrollo ejecuta lingo push --wait e incluye el resultado en un commit antes de abrir la pull request | Sí. Hace que falle una pull request cuyo origen haya cambiado sin traducirse. |
| El paso de traducción sube los cambios a la rama predeterminada después de la fusión | No. Por diseño, las pull requests de funcionalidades modifican los archivos de origen antes de traducirlos. |
| El paso de pull requests crea un commit en la rama de la pull request | No. En la compilación que traduce, la comprobación ve el commit anterior a la traducción y falla. Al volver a ejecutarse sobre el commit de traducción, el propio paso no encuentra nada que subir, lo que demuestra que ningún origen ha cambiado desde .lingo/lock.json. |
Los hashes de origen se calculan con precisión de 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.
Adapta el paso #
En un monorepositorio, ejecuta la CLI desde el paquete que contiene .lingo/config.json, por ejemplo con cd apps/web al principio del comando, y añade al área de preparación los archivos de destino y el Lockfile de ese paquete. Los paquetes independientes mantienen archivos Lockfile separados y pueden usar distintos motores de localización.
Si el motor de localización envía el trabajo a revisión humana, lingo push --wait termina con el código 0 después de escribir únicamente los archivos finalizados. No incluyas ese resultado parcial en un commit como si estuviera completo. Añade el procedimiento de conservación del estado de ejecución en CI y recupera el resto con Pull en el mismo agente cuando termine la revisión.
Recupera el paso tras un fallo y retíralo #
Usa el error para determinar la siguiente acción: reparar la instalación de paquetes, proporcionar el secreto, completar la revisión, resolver un conflicto al obtener cambios o volver a intentar el trabajo de destino que haya fallado después de corregir su causa. Mantén visibles las salidas con códigos distintos de cero; || true oculta la causa.
Elimina el paso o su activador para detener las nuevas compilaciones. Al cancelar una compilación, revisa por separado cualquier traducción que ya se haya enviado. Elimina el secreto LINGO_API_KEY y el permiso de escritura del agente cuando retires la receta.