Receta de CI para GitLab

Traduce archivos en una canalización de GitLab de confianza, entrégalos mediante una solicitud de fusión y haz que fallen las solicitudes de fusión con traducciones desactualizadas.

Un ejecutor de GitLab puede traducir archivos del repositorio con la CLI de Lingo.dev y guardar los resultados como artefactos del trabajo. Así, la traducción aprovecha el mismo checkout, las mismas comprobaciones y el mismo proceso de publicación que el resto de tu aplicación. GitLab se encarga de ejecutar la canalización y de entregar los resultados en el repositorio; Lingo.dev procesa los archivos de origen seleccionados con un motor de localización.

Se trata de una receta de CI, no de una conexión nativa con una cuenta de GitLab. Empieza con una canalización que se inicie manualmente en la rama predeterminada y, cuando hayas revisado el resultado, añade activadores periódicos y la entrega mediante solicitudes de fusión.

Define el origen y las credenciales #

Completa la guía de inicio rápido de la CLI en local. Haz commit de .lingo/config.json, de los archivos de destino aceptados y de .lingo/lock.json. La configuración define el idioma de origen, los idiomas de destino, los patrones de archivos y el motor de localización. Ejecuta la CLI desde el directorio al que pertenece la configuración.

Crea los archivos de destino que falten con lingo push --backfill-missing --wait. Para las modificaciones posteriores del origen, usa lingo push --wait como de costumbre. Cambiar las instrucciones del motor de localización no reescribe por sí solo los archivos aceptados: regenerarlos deliberadamente es una tarea aparte.

En la configuración de variables de CI/CD del proyecto, guarda LINGO_API_KEY como variable enmascarada. La CLI solo reconoce este nombre; ignora la variable LINGODOTDEV_API_KEY de la CLI anterior, así que cámbiale el nombre. Restringe su uso a las ramas o entornos de confianza que puedan enviar tareas de traducción. Una variable protegida puede no estar disponible en una rama o solicitud de fusión no protegida; utiliza una rama autorizada en lugar de exponerla a código que no sea de confianza.

La clave de API autoriza la traducción. Solo necesitarás una credencial de GitLab con acceso de escritura al repositorio cuando añadas la entrega mediante commits.

Los ejemplos utilizan la versión fija 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.

Ejecuta una canalización centrada en artefactos #

Este ejemplo de .gitlab-ci.yml presupone que locales/en.json es el origen configurado y que locales/es.json, un archivo en español ya existente, es su ú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 mencionen locales/es.json. El Lockfile registra el origen como traducido, por lo que un envío posterior lo omite, y cualquier destino que quede fuera del artefacto o del commit seguirá desactualizado. El ejemplo utiliza una canalización iniciada manualmente en la rama predeterminada:

yaml
stages:
  - translate

translate_catalog:
  stage: translate
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  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:
    paths:
      - locales/es.json
      - .lingo/lock.json

--wait hace que la tarea 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 los pasos posteriores no encuentran archivos nuevos que comprobar o incluir en un commit.

Comprueba que tu ejecutor tiene acceso al registro y proporciona las herramientas que necesiten los pasos posteriores. Por ejemplo, con una imagen mínima alternativa quizá tengas que instalar Git antes de poder revisar las diferencias o hacer commit de ellas.

Comprueba los ID de la organización y del motor en el .lingo/config.json confirmado. Haz un cambio en el origen e inicia la canalización. En el registro, confirma el estado de ejecución indicado y la entrada de destino modificada. Descarga el artefacto, compara la traducción con esa revisión del origen y cárgala en tu aplicación. Las comprobaciones de existencia de archivos y de JSON no bastan por sí solas para garantizar que el contenido esté actualizado ni que conserve su significado.

--wait descarga los resultados terminados, pero si hay una revisión humana configurada, el trabajo puede quedar a la espera de una persona. Antes de usar una espera de revisión o un trabajo de recuperación independiente, añade el procedimiento de conservación del estado de ejecución en CI. Tras el envío, exporta el puntero concreto y la ruta absoluta original de la raíz del proyecto. Incluye .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, el destino y el Lockfile en artefactos del trabajo de acceso restringido. Establece when: always en la configuración de artifacts y reserva un plazo de conservación suficiente para la revisión. Asegúrate de que la exportación se ejecute también si falla una validación posterior, sin ocultar el fallo original.

Completa la revisión y, después, restaura la revisión y el estado de los archivos registrados en la misma ruta raíz absoluta del ejecutor de recuperación. Restaura solo ese puntero, autentícate por separado y usa lingo pull --dry-run antes de recoger los resultados. Si el ejecutor no puede recrear la ruta original, utiliza un mismo ejecutor persistente y autorizado para ambos trabajos. No archives nunca todo el contenido de ~/.lingo. Un envío correcto o un archivo de destino antiguo no aportan, por sí solos, archivos nuevos que publicar.

Haz commit de las traducciones en una solicitud de fusión #

Este trabajo traduce los cambios del origen en una solicitud de fusión y hace commit de los resultados en la misma rama. Da por hecho que la carga inicial de los archivos que faltaban ya está confirmada y que la revisión humana del motor está desactivada, de modo que la traducción pueda completarse en un solo trabajo.

En GitLab 18.4 o posterior, activa Configuración → CI/CD → Permisos del token del trabajo → Permitir solicitudes de envío de Git al repositorio. El trabajo usa el token integrado de GitLab, y la persona que lo inicia debe tener permiso para enviar cambios a la rama de origen. Consulta la configuración del token del trabajo de GitLab.

Mantén LINGO_API_KEY enmascarado y protegido. Usa ramas de origen y destino de confianza dentro del mismo proyecto, protege ambas y activa Permitir que las canalizaciones de solicitudes de fusión accedan a variables y ejecutores protegidos en los ajustes de CI/CD del proyecto. La persona que inicia la canalización también necesita permiso para enviar o fusionar cambios en la rama de destino. Estos son los requisitos de GitLab para las variables protegidas.

Usa las mismas rutas de origen y destino que en el primer ejemplo. Añade este trabajo a la etapa translate:

yaml
translate_merge_request:
  stage: translate
  image: node:22
  resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
  rules:
    - if: >-
        $CI_PIPELINE_SOURCE == "merge_request_event" &&
        $CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
        $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
  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 "Update translations"
    - git push "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"

resource_group ejecuta un único trabajo de traducción a la vez por cada MR. El trabajo solo hace commit del destino en español y del Lockfile de traducción. Si la rama cambia durante la traducción, Git rechaza el envío; en ese caso, ejecuta una canalización para la rama actualizada.

CI_REPOSITORY_URL proporciona las credenciales del token del trabajo. Los envíos con este token no inician otra canalización, así que añade las comprobaciones de recursos de tu aplicación antes del paso de commit. Revisa las diferencias de la traducción en la MR y ejecuta las comprobaciones pendientes antes de fusionar.

Como ese envío no inicia ninguna canalización, el commit más reciente de la solicitud de fusión no tiene ninguna asociada. Si el proyecto exige que Las canalizaciones deben completarse correctamente, GitLab puede bloquear la fusión. En ese caso, selecciona Ejecutar canalización en la pestaña Canalizaciones de la solicitud de fusión. La tarea no encuentra nada que enviar y termina sin crear un commit; esa canalización asigna un estado al commit más reciente.

Abrir una solicitud de fusión de traducciones desde la rama predeterminada #

Esta tarea traduce cada cambio que llega a la rama predeterminada y abre una solicitud de fusión con el resultado. Las opciones de envío de GitLab crean la solicitud de fusión en el mismo git push, por lo que no hace falta ninguna llamada a la API ni ninguna herramienta adicional. Parte de los mismos supuestos que la tarea anterior: la traducción inicial ya se ha incluido en un commit y la revisión humana está desactivada.

Crea un token de acceso al proyecto con el rol Desarrollador y el ámbito write_repository. Guárdalo como variable de CI/CD enmascarada y protegida con el nombre GITLAB_PUSH_TOKEN. En GitLab.com, los tokens de acceso al proyecto requieren un plan de pago. Aquí no se utiliza CI_JOB_TOKEN, porque GitLab no inicia ninguna canalización cuando el envío se realiza con ese token. La URL de envío utiliza CI_SERVER_FQDN, que conserva el puerto de una instancia autogestionada que use uno no estándar. CI_SERVER_FQDN requiere GitLab 16.10 o posterior. En una instancia autogestionada con una versión anterior, utiliza ${CI_SERVER_HOST}:${CI_SERVER_PORT} en su lugar.

Añade esta tarea a la etapa translate:

yaml
translate_default_branch:
  stage: translate
  image: node:22
  resource_group: lingo-translations
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
    - if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
    # 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 --force
      -o ci.skip
      -o merge_request.create
      -o merge_request.target="$CI_DEFAULT_BRANCH"
      -o merge_request.title="Update translations"
      "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
      "HEAD:refs/heads/lingo/translations"

lingo push --wait termina con un código de salida distinto de cero cuando falla un destino, por lo que la tarea se detiene antes de crear el commit. Si no ha cambiado nada, muestra "No hay nada que enviar", no hay diferencias preparadas para el commit y la tarea termina sin crearlo.

Las dos primeras líneas detienen la tarea si la rama predeterminada ha avanzado más allá del commit en el que se ejecuta. resource_group ejecuta una sola tarea a la vez, pero, en el modo de procesamiento unordered predeterminado de GitLab, inicia las tareas en espera sin un orden fijo. Sin esta comprobación, una tarea anterior podría ejecutarse en último lugar y sobrescribir traducciones más recientes con otras antiguas mediante un envío forzado. La tarea correspondiente al commit más reciente lo traduce, y no se envía nada para un commit que ya esté desactualizado.

La tarea no entra en bucle. Solo se ejecuta cuando se envían cambios a la rama predeterminada y solo escribe en lingo/translations. La documentación de GitLab indica que -o ci.skip solo afecta a las canalizaciones de rama, no a las de solicitudes de fusión, y que una canalización de solicitud de fusión se ejecuta cuando se crea la solicitud o cuando su rama de origen recibe un nuevo commit. Por tanto, el control que aparece a continuación debería ejecutarse en la solicitud de fusión de traducciones; confírmalo en la primera ejecución. Al fusionar esa solicitud, la tarea se ejecuta una vez más y no encuentra nada que enviar.

Cada ejecución reconstruye lingo/translations a partir del commit de la rama predeterminada en el que se ejecutó y lo envía de forma forzada, de modo que una solicitud de fusión abierta muestra las diferencias de traducción más recientes. La siguiente ejecución sobrescribe los cambios manuales realizados en esa rama; hazlos después de la fusión. Hasta que se fusione la solicitud, la rama predeterminada conserva el .lingo/lock.json anterior, por lo que la siguiente ejecución vuelve a enviar los mismos cambios de origen. Si los commits posteriores deshacen todos los cambios de origen traducidos por la solicitud de fusión, la siguiente ejecución no encuentra nada que enviar y deja abierta la solicitud con traducciones desactualizadas; ciérrala en lugar de fusionarla.

Hacer que fallen las solicitudes de fusión 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 de salida 1 si un origen ha cambiado 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 ninguna clave de API ni variable de CI/CD y no escribe nada, por lo que también se ejecuta en solicitudes de fusión procedentes de bifurcaciones. Aparte de la telemetría de la CLI, que DO_NOT_TRACK=1 desactiva, no realiza llamadas de red; los ejemplos de npx siguen 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 supera 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 los cambios de origen, por lo que un origen modificado o que nunca se haya enviado no hace que falle la comprobación, y esta lo indica en stderr. Incluye en un commit el Lockfile que escribe lingo push.

Añade check a la lista stages y, después, añade la tarea correspondiente a tu configuración. Si el equipo de desarrollo ejecuta lingo push --wait e incluye el resultado en un commit junto con el cambio de origen, comprueba todas las solicitudes de fusión:

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

Con la tarea de la rama predeterminada, comprueba solo su solicitud de fusión de traducciones, porque las solicitudes de fusión de funcionalidades modifican los orígenes antes de traducirlos:

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

Este control encaja en 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ónControl en cada solicitud de fusión
El equipo de desarrollo ejecuta lingo push --wait e incluye el resultado en un commit antes de abrir la solicitud de fusiónSí. Hace que falle una solicitud de fusión cuyo origen haya cambiado sin traducirse.
La tarea de la solicitud de fusión crea un commit en la rama de origenNo. La comprobación examinaría el commit anterior a la traducción, y el envío de la tarea no inicia ninguna canalización nueva.
La tarea de la rama predeterminada abre una solicitud de fusión de traduccionesSolo en lingo/translations, con la segunda tarea anterior. Por diseño, las solicitudes de fusión de funcionalidades modifican los orígenes antes de traducirlos.

Los hashes del origen tienen en cuenta cada byte. Asegúrate de que el checkout en el que se ejecutó lingo push y el checkout de CI utilicen los mismos finales de línea, por ejemplo, con * text=auto eol=lf en .gitattributes.

Haz que el trabajo periódico sea predecible #

Filtra los trabajos automáticos para que solo se ejecuten en las ramas de confianza y las rutas de origen previstas. Si usas activadores de solicitudes de fusión, limita también el proyecto de origen y la rama de destino. Evita que los commits generados vuelvan a enviar traducciones una y otra vez con una regla de rama adecuada o una política para omitir CI, además de una salida cuando no haya diferencias.

En un monorepositorio, entra en el paquete que contiene la configuración prevista y conserva sus resultados y su estado con rutas relativas al paquete. Los paquetes independientes pueden tener motores de localización e idiomas distintos; mantén sus Lockfile por separado. Este mismo enfoque con ejecutores funciona con GitLab autogestionado, siempre que lo permitan el acceso a la red, las herramientas del ejecutor, las variables y la política del repositorio.

La traducción incremental habitual puede conservar una clave de destino editada a mano mientras su origen no cambie. Si el origen cambia, esa clave puede regenerarse. La carga de archivos que faltan y la regeneración forzada tienen alcances distintos. Sin patrones de archivos, --force abarca todos los idiomas de origen y destino configurados y puede sustituir traducciones aceptadas. Usa patrones explícitos y revisa una estimación antes de forzar el trabajo. Consulta Push si cambias el comando de envío.

Recupera y retira la canalización #

Usa el error para identificar el siguiente paso: reparar la instalación de paquetes, proporcionar una variable autorizada, completar la revisión, resolver un conflicto de fusión o reintentar el trabajo de destino fallido una vez corregida la causa. Conserva los artefactos correctos, pero deja bien claro que una publicación parcial sigue incompleta.

Desactiva el activador para que no se inicien nuevas canalizaciones. Si cancelas un ejecutor, revisa por separado las traducciones que ya se hayan enviado. Cuando retires la receta, elimina las credenciales de API y del repositorio que ya no se usen.