Receta para Buildkite
Traduce archivos en una canalización de Buildkite, envía el resultado a la misma rama y haz que fallen las solicitudes de cambios con traducciones desactualizadas.
Un paso de Buildkite puede traducir archivos del repositorio con la CLI de Lingo.dev en tus propios agentes. La CLI envía los archivos de origen que selecciona tu configuración de Lingo.dev y escribe los archivos traducidos en el checkout; tu canalización decide cómo entregarlos. Buildkite administra 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 solicitudes de cambios y revisa su primer commit. Agrega la comprobación de solicitudes de cambios solo cuando 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 tu entorno 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 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, o agrega al área de preparación todo el directorio de destino, como locales/. El Lockfile registra el origen como traducido, por lo que un envío posterior lo omite y cualquier destino que quede fuera del commit sigue desactualizado.
Crea los archivos de destino que falten con lingo push --backfill-missing --wait antes de usar el paso recurrente. Para los cambios posteriores en el origen, usa lingo push --wait de la forma habitual. La generación de archivos faltantes no corrige las claves que falten en un 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 usa el agente para el checkout, como una clave de despliegue, también debe permitir enviar 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; 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 el agente de Buildkite 3.106.0 o posterior, ejecutándose en el clúster que contiene el secreto; los agentes anteriores hacen que falle la canalización. En agentes más antiguos o que no pertenecen a un clúster, elimina secrets: y, en su lugar, exporta LINGO_API_KEY para ese paso desde un hook environment del agente o desde tu complemento de secretos.
Mantén desactivada la opción Permitir compilaciones desde repositorios bifurcados de terceros en la Configuración de GitHub de la canalización. La solicitud de cambios de una bifurcación se compila con el pipeline.yml de esa misma bifurcación, que puede agregar un paso que lea el secreto, y ningún if: de tu archivo puede impedirlo. Agrega también una política de acceso al secreto para que solo las compilaciones de esta canalización puedan leerlo.
Los ejemplos fijan la versión de la CLI en 1.21.0. lingo check comprueba los archivos de traducción a partir de la versión 1.20.0 de la CLI. Para administrar la versión mediante las dependencias y el Lockfile de tu proyecto, sigue la guía de configuración de CI.
Traduce y envía el resultado a la misma rama #
Este paso traduce cada cambio que llega a la rama predeterminada y envía el resultado a esa misma rama. Da por hecho que la generación inicial de archivos ya está incluida en un commit y que la opción Revisión humana del motor está desactivada, de modo que la traducción termina en un solo paso. Agrégalo 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 esta opción, 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 del commit. Cuando no hay cambios, imprime "No hay nada que enviar", no hay diferencias en el área de preparación y el paso termina sin crear un commit.
Buildkite hace checkout de un solo commit, no de una rama, por lo que el envío especifica el nombre de la rama. $$ deja BUILDKITE_BRANCH para que el intérprete de comandos lo expanda cuando se ejecute el paso; con un solo $, Buildkite escribiría el nombre de la rama en el texto del comando al cargar la canalización. concurrency y concurrency_group ejecutan una traducción a la vez. Si la rama avanzó durante la traducción, Git rechaza el envío; la compilación del commit más reciente traduce ese cambio.
El paso no se ejecuta en bucle. Buildkite omite las compilaciones de los commits cuyo mensaje contiene [skip ci]. Sin esto, la siguiente compilación no encontraría nada que enviar, porque el .lingo/lock.json incluido en el commit ya registra el nuevo origen.
Enviar directamente a la rama predeterminada elimina la revisión de una solicitud de cambios de traducción, así que toma esta decisión de forma deliberada dentro de tu política de ramas. Para revisar primero las traducciones, envíalas a una rama separada, como lingo/translations, y abre una solicitud de cambios con las herramientas de tu proveedor de Git.
Traduce en las compilaciones de solicitudes de cambios #
Para traducir los cambios de origen de cada solicitud de cambios en su propia rama, usa este paso en lugar del de la rama predeterminada. Parte de los mismos supuestos que ese paso. Su if: omite las solicitudes de cambios de bifurcaciones, porque el paso no puede enviar cambios a la rama de una bifurcación.
El paso requiere dos opciones en la Configuración de GitHub de la canalización. Activa Compilar cuando se abra o actualice una solicitud de cambios. Desactiva Compilar ramas o limita esta opción a la rama predeterminada. Si las compilaciones de ramas están activadas, un envío a la rama de una solicitud de cambios puede iniciar una compilación sin los detalles de la solicitud. El paso omite esa compilación, así que no se traduce nada ni se produce ningún fallo.
El if: no protege LINGO_API_KEY. Buildkite lo lee del pipeline.yml de la propia solicitud de cambios y una bifurcación puede modificar ese archivo. Por eso, las compilaciones de bifurcaciones deben permanecer desactivadas, como indica la configuración. Una solicitud de cambios desde una rama del repositorio también puede modificar el archivo, así que cualquier persona que pueda enviar cambios a una rama puede leer la clave mediante este paso. Úsalo solo cuando todas las personas con acceso de escritura estén autorizadas a tener 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] a propósito. Buildkite compila el commit de traducción, el paso vuelve a ejecutarse, no encuentra nada que enviar y termina sin crear un commit, de modo que el bucle termina después de una compilación adicional. Esa compilación asigna un estado al commit más reciente de la solicitud de cambios. Con [skip ci], el commit más reciente no tendría una 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 envíos a las ramas de solicitudes de cambios. Si la rama avanzó durante la traducción, Git rechaza el envío y el paso falla; la compilación del commit más reciente traduce ese cambio. Por eso, dos envíos seguidos inician dos traducciones y ambas se facturan. Activa Cancelar compilaciones intermedias en la configuración de la canalización para que un envío más reciente cancele la compilación anterior. Una traducción que la compilación anterior ya haya enviado no se cancela.
Haz que fallen las solicitudes de cambios 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 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 un secreto y no escribe nada. Aparte de la telemetría de la CLI, que DO_NOT_TRACK=1 desactiva, no realiza llamadas de red; el ejemplo con npx sí descarga la CLI desde npm antes de ejecutar la comprobación. Reemplaza el control --frozen de la CLI anterior.
Comprueba archivos, no claves: un destino editado a mano pasa la comprobación y no se informa de una clave faltante dentro de un destino existente, excepto 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 falle; la comprobación lo indica en stderr. Incluye en un commit el Lockfile que escribe lingo push.
Agrega este paso a .buildkite/pipeline.yml cuando la tabla de abajo indique que el control es adecuado. Se usa en una configuración sin ninguno de los dos pasos de traducción anteriores, así que cada ejemplo de aquí es una lista steps: completa para una configuración. Incorpora el paso a tu lista steps: existente en lugar de agregar 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 solicitud de cambios |
|---|---|
El equipo de desarrollo ejecuta lingo push --wait e incluye el resultado en un commit antes de abrir la solicitud de cambios | Sí. Hace que falle una solicitud de cambios cuyo origen cambió sin traducirse. |
| El paso de traducción envía los cambios a la rama predeterminada después de la fusión | No. Por diseño, las solicitudes de cambios de nuevas funciones modifican los archivos de origen antes de la traducción. |
| El paso de solicitudes de cambios crea commits en la rama de la solicitud | No. En la compilación que traduce, la comprobación ve el commit anterior a la traducción y falla. La nueva ejecución del propio paso en el commit de traducción, que no encuentra nada que enviar, demuestra que ningún origen cambió desde .lingo/lock.json. |
Los hashes de origen reflejan el contenido exacto, byte por 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 #
Para un monorrepositorio, ejecuta la CLI desde el paquete que contiene .lingo/config.json, por ejemplo, con cd apps/web al inicio del comando, y agrega 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 trabajo a revisión humana, lingo push --wait termina con el código 0 después de escribir solo los archivos finalizados. No incluyas ese resultado parcial en un commit como si estuviera completo. Agrega el procedimiento para conservar el estado de ejecución de CI y recupera el resto con Pull en el mismo agente una vez que termine la revisión.
Resuelve fallos y retira el paso #
Usa el error para identificar la siguiente acción: reparar la instalación de paquetes, proporcionar el secreto, completar la revisión, resolver un conflicto al obtener cambios o reintentar el trabajo de destino que falló después de corregir su causa. Mantén visibles los códigos de salida 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 acceso de escritura del agente cuando retires la receta.