Receta de CI para GitLab

Traduce archivos en una canalización de confianza de GitLab, 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 conservar los resultados como artefactos del trabajo. Así, la traducción usa el mismo checkout, las mismas verificaciones y el mismo proceso de publicación que el resto de tu aplicación. GitLab se encarga de ejecutar la canalización y entregar los resultados al repositorio; Lingo.dev procesa los archivos de origen seleccionados mediante un motor de localización.

Esta es una receta de CI, no una conexión nativa con una cuenta de GitLab. Comienza con una canalización iniciada manualmente en la rama predeterminada. Después de revisar el resultado, agrega activadores recurrentes 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 tu entorno local. Crea un commit con .lingo/config.json, los archivos de destino aceptados y .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 que contiene esa configuración.

Crea los archivos de destino faltantes con lingo push --backfill-missing --wait. Para los cambios posteriores en el origen, usa lingo push --wait de la forma habitual. Cambiar las instrucciones del motor de localización no reescribe por sí solo los archivos aceptados; regenerarlos de forma deliberada 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 lee este nombre e ignora las variables LINGODOTDEV_API_KEY de la CLI anterior, así que cambia el nombre de la variable. Restringe su uso a las ramas o los entornos de confianza autorizados para enviar trabajos de traducción. Una variable protegida puede no estar disponible en una rama o solicitud de fusión no protegida; usa una rama autorizada en lugar de exponerla a código que no sea de confianza.

La clave de API autoriza la traducción. Solo necesitas una credencial de GitLab con acceso de escritura al repositorio cuando agregues la entrega mediante commits.

Los ejemplos usan una versión fija de la CLI: 1.21.0. lingo check verifica 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.

Ejecuta una canalización que genere artefactos primero #

Este ejemplo de .gitlab-ci.yml supone que locales/en.json es el origen configurado y que locales/es.json, un archivo existente en español, es su único destino. Si tienes más destinos, ejecuta test -s y las verificaciones 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 los envíos posteriores lo omiten. Si un destino queda fuera del artefacto o del commit, seguirá desactualizado. El ejemplo usa 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 para inspeccionar ni incluir en un commit.

Verifica que el ejecutor tenga acceso al registro y proporciona las herramientas que necesiten los pasos posteriores. Por ejemplo, una imagen mínima alternativa podría requerir la instalación de Git antes de poder revisar diferencias o crear un commit con ellas.

Verifica los ID de la organización y del motor en el .lingo/config.json incluido en el commit. Haz un cambio en el origen e inicia la canalización. En el registro, confirma el estado de ejecución informado 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 verificaciones de presencia de archivos y de JSON no permiten determinar por sí solas si el contenido está actualizado ni si su significado es correcto.

--wait descarga los resultados completados, 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, agrega el procedimiento de conservación del estado de ejecución de CI. Después del envío, exporta el puntero específico y la ruta absoluta original del directorio raíz del proyecto. Incluye .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, el archivo de destino y el Lockfile en artefactos del trabajo con acceso restringido. Establece when: always en la configuración de artifacts y define un período de retención suficiente para la revisión. Asegúrate de que la exportación también se ejecute si falla una validación posterior; no ocultes el error original.

Completa la revisión y luego restaura la revisión registrada y el estado de los archivos en la misma ruta absoluta del directorio raíz en el ejecutor de recuperación. Restaura solo ese puntero, autentícate por separado y usa lingo pull --dry-run antes de recopilar los resultados. Si el ejecutor no puede recrear la ruta original, usa un ejecutor persistente autorizado para ambos trabajos. Nunca archives todo el contenido de ~/.lingo. Un envío exitoso o un archivo de destino antiguo, por sí solos, no proporcionan archivos nuevos para publicar.

Crea un commit con las traducciones en una solicitud de fusión #

Este trabajo traduce los cambios de origen de una solicitud de fusión y crea un commit con los resultados en la misma rama. Supone que la generación inicial de los archivos faltantes ya está incluida en un commit y que la opción Revisión humana del motor está desactivada, para que la traducción pueda completarse en un solo trabajo.

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

Mantén LINGO_API_KEY enmascarado y protegido. Usa ramas de origen y destino de confianza en el mismo proyecto, protege ambas ramas y activa Permitir que las canalizaciones de solicitudes de fusión accedan a variables y ejecutores protegidos en la configuración de CI/CD del proyecto. La persona que inicia la canalización también necesita acceso 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. Agrega 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 solo trabajo de traducción a la vez por cada MR. El trabajo crea un commit únicamente con el archivo de destino en español y el Lockfile de traducción. Si la rama cambia durante la traducción, Git rechaza el envío; ejecuta una canalización para la rama actualizada.

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

Como ese envío no inicia ninguna canalización, el commit más reciente de la solicitud de fusión queda sin una. Si el proyecto exige 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 le asigna un estado al commit más reciente.

Abre 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, sin necesidad de llamar a la API ni usar herramientas adicionales. Parte de los mismos supuestos que la tarea anterior: la traducción inicial completa ya está guardada en un commit y la revisión humana está desactivada.

Crea un token de acceso al proyecto con el rol Desarrollador y el alcance 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 usa CI_JOB_TOKEN, porque GitLab no inicia ninguna canalización para los envíos realizados con ese token. La URL de envío usa CI_SERVER_FQDN, que conserva el puerto de una instancia autogestionada cuando esta usa un puerto no estándar. CI_SERVER_FQDN requiere GitLab 16.10 o una versión posterior. En una instancia autogestionada más antigua, usa ${CI_SERVER_HOST}:${CI_SERVER_PORT} en su lugar.

Agrega 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 estado distinto de cero cuando falla un destino, por lo que la tarea se detiene antes de crear el commit. Cuando no hay cambios, muestra "No hay nada que enviar", la comparación de los cambios preparados está vacía y la tarea termina sin crear un commit.

Las primeras dos líneas detienen la tarea si la rama predeterminada ya avanzó más allá del commit en el que se ejecuta. resource_group ejecuta una tarea a la vez, pero en el modo de procesamiento unordered predeterminado de GitLab, las tareas en espera se inician sin un orden fijo. Sin esta verificación, una tarea más antigua podría ejecutarse al final y forzar un envío que sobrescriba las traducciones más recientes con versiones anteriores. La tarea correspondiente al commit más reciente lo traduce, y no se envía nada para los commits que ya están desactualizados.

La tarea no se ejecuta en bucle. Solo se ejecuta cuando hay envíos a la rama predeterminada y solo escribe en lingo/translations. La documentación de GitLab indica que -o ci.skip afecta únicamente a las canalizaciones de ramas, 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 eso, el control que se muestra 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 fuerza su envío. Así, una solicitud de fusión abierta muestra los cambios de traducción más recientes. La siguiente ejecución reemplaza los cambios manuales realizados en esa rama; hazlos después de fusionar. 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 del origen. Si los commits posteriores deshacen todos los cambios del origen que tradujo la solicitud de fusión, la siguiente ejecución no encuentra nada que enviar y deja la solicitud abierta con traducciones desactualizadas; ciérrala en lugar de fusionarla.

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

lingo check compara cada origen configurado con .lingo/lock.json y exige que estén presentes todos los archivos de destino. Termina con el estado 1 si un origen cambió desde su última traducción, si un origen 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 una clave de API ni una variable de CI/CD y no escribe nada, por lo que también se ejecuta en solicitudes de fusión de repositorios derivados. 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 verificación. Reemplaza el control --frozen de la CLI anterior.

Verifica archivos, no claves: un destino editado a mano pasa la verificació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 origen, por lo que un origen modificado o que nunca se haya enviado no hace fallar la verificación; esta lo indica en stderr. Incluye en un commit el Lockfile que escribe lingo push.

Agrega check a la lista stages y luego agrega 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 del origen, verifica cada solicitud 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, verifica 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

El control funciona para una configuración en la que las traducciones se incluyen en un commit junto con el cambio del 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 cambió sin traducirse.
La tarea de la solicitud de fusión crea un commit en la rama de origenNo. La verificación inspeccionaría el commit antes de la traducción, y el envío de la tarea no inicia una nueva canalización.
La tarea de la rama predeterminada abre una solicitud de fusión de traduccionesSolo en lingo/translations, con la segunda tarea de arriba. Por diseño, las solicitudes de fusión de funcionalidades modifican los orígenes antes de traducirlos.

Los hashes del origen dependen de cada byte exacto. 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.

Haz que el trabajo recurrente sea predecible #

Filtra los trabajos automáticos para que se ejecuten solo en las ramas de confianza y las rutas de origen previstas. Si usas activadores de solicitudes de fusión, restringe también el proyecto de origen y la rama de destino. Evita que los commits generados envíen trabajos de traducción una y otra vez: usa una regla de rama adecuada o una política para omitir CI y finaliza cuando no haya diferencias.

En un monorepositorio, entra en el paquete que contiene la configuración prevista y conserva los resultados y el estado en rutas relativas a ese paquete. Los paquetes independientes pueden tener distintos motores de localización e idiomas; mantén sus archivos Lockfile separados. El mismo enfoque con ejecutores funciona en GitLab autogestionado cuando el acceso a la red, las herramientas del ejecutor, las variables y las políticas del repositorio lo permiten.

La traducción incremental habitual puede conservar una clave de destino editada manualmente mientras su origen no cambie. Un cambio en el origen puede regenerar esa clave. La generación de archivos faltantes y la regeneración forzada tienen alcances distintos. Sin patrones de archivos, --force abarca todos los idiomas de origen y destino configurados y puede reemplazar las traducciones aceptadas. Usa patrones explícitos y revisa una estimación antes de forzar el trabajo. Consulta Enviar al cambiar 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 después de corregir su causa. Conserva los artefactos exitosos, pero deja claramente indicado que una publicación completada solo en parte sigue incompleta.

Desactiva el activador para detener las canalizaciones nuevas. Al cancelar su ejecutor, revisa por separado cualquier traducción que ya se haya enviado. Elimina las credenciales de API y del repositorio que hayan quedado obsoletas cuando retires la receta.