Automatiza las traducciones en CI

Integra la traducción de forma repetible en cada lanzamiento, desde una revisión conocida del contenido de origen hasta la inspección de archivos y las comprobaciones de la aplicación.

El proceso de lanzamiento ya conecta una revisión del contenido de origen con algo que las personas pueden usar. La traducción debe mantener esa conexión. El trabajo debe identificar qué contenido de origen ha cambiado, recuperar los archivos de destino correspondientes y dejar al siguiente paso pruebas suficientes para aceptarlos o rechazarlos.

Los casos complicados surgen tras la primera solicitud completada con éxito: una persona sigue editando durante la revisión, un ejecutor desaparece o llega una versión más reciente del contenido original antes de que termine una traducción anterior. Esta guía explica cómo crear un proceso de CI capaz de gestionar estos casos sin publicar archivos desactualizados ni sustituir innecesariamente los cambios aceptados. El YAML específico de cada proveedor se encuentra en las guías de GitHub Actions, GitLab, Bitbucket y Buildkite.

Decide en qué punto del lanzamiento incorporar las traducciones #

Usa la GitHub App gestionada si su flujo de trabajo para repositorios encaja con tus necesidades. Los cambios en la rama predeterminada generan una solicitud de incorporación de traducciones; si activas el procesamiento de solicitudes de incorporación, las traducciones se escriben en la rama de la propia solicitud. La aprobación de la ejecución autoriza el trabajo de traducción; la revisión del contenido y la fusión se realizan después.

Con un ejecutor de CLI, tu proceso se encarga del envío, la recuperación y la entrega. Elige un destino que encaje con el proceso de lanzamiento:

DestinoDecisión que permite tomar
Solo artefactoOtro trabajo o una persona inspecciona el resultado antes de modificar el repositorio o el lanzamiento.
Rama de traducción y solicitud de incorporaciónRevisar los cambios traducidos por separado antes de incorporarlos a la rama predeterminada.
Rama de la solicitud de incorporación del contenido de origenRevisar el contenido de origen y las traducciones juntos en un único cambio.
Confirmación directa en la rama predeterminadaEntregar sin una solicitud de incorporación de traducciones independiente cuando la política de la rama lo permita expresamente.

Para escribir en el repositorio, designa un único ejecutor activo con capacidad de escritura para cada estado de traducción. De lo contrario, dos ejecutores que trabajen con distintas revisiones del contenido de origen pueden competir por confirmar los archivos y el Lockfile. Las confirmaciones generadas también deben estar sujetas a reglas basadas en la rama, la ruta o su condición de confirmaciones generadas, para evitar que activen la traducción una y otra vez.

Establece el estado de referencia que heredará el ejecutor #

Antes de activar las ejecuciones periódicas, traduce localmente un archivo de origen a un idioma y ejecuta las comprobaciones de recursos de la aplicación. Confirma juntos la configuración, el archivo de destino aceptado y .lingo/lock.json. Un checkout limpio debe reproducir la misma selección de archivos de origen y la misma estructura de destino.

Los ejemplos de los proveedores fijan @lingo.dev/cli@1.21.0. Sustituye esa versión por la versión actual de la CLI al configurar tu flujo de trabajo. Para gestionar la CLI junto con las dependencias del proyecto, instálala con npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 y confirma package.json y package-lock.json. Después, usa npm ci y npx --no-install lingo para ejecutar la versión registrada en el Lockfile.

.lingo/config.json selecciona los idiomas, los patrones de archivo y el motor de localización. Configura el acceso a la organización y al motor de localización durante la puesta en marcha. Si el trabajo debe inicializar o vincular un proyecto, usa las opciones explícitas de las referencias de Inicialización y Vinculación, en lugar de dejar una ejecución desatendida esperando una respuesta interactiva.

En un monorepositorio, entra en el paquete que contiene la configuración deseada antes de ejecutar la CLI. Los patrones posicionales acotan los archivos de origen seleccionados por esa configuración; no seleccionan la configuración de otro paquete. Mantén juntos el estado y las rutas de los artefactos de cada paquete configurado de forma independiente.

Inyecta LINGO_API_KEY mediante el mecanismo de secretos del ejecutor. Funciona sin iniciar sesión de forma interactiva. Ejecuta trabajos con credenciales solo desde código de confianza, ya que una rama puede modificar los scripts para exponer la clave. Las restricciones relativas a las variables protegidas y las bifurcaciones deben determinar dónde se ejecuta el trabajo; no las elimines para que un trabajo no fiable se complete correctamente.

Envía el tipo de trabajo adecuado #

Para una primera traducción desde cero, solicita los archivos de destino que faltan. En un proyecto existente, completa primero las actualizaciones habituales del contenido de origen para los destinos existentes, recupera los resultados e inspecciónalos. Después, añade los idiomas que faltan y genera sus archivos sin cambiar esa revisión del contenido de origen. Sigue Añadir un idioma antes de ejecutar este comando:

sh
lingo push --backfill-missing --wait

Para cambios en el contenido de origen respecto al estado de referencia establecido:

sh
lingo push --wait

Un envío inicial sin opciones adicionales puede registrar el estado del contenido de origen sin traducirlo. La generación de archivos faltantes crea la tarea correspondiente; los envíos habituales posteriores determinan el trabajo a partir de los cambios en el contenido de origen. Un envío con un ámbito limitado o destinado a generar archivos faltantes no es una solución universal para reparar las claves que faltan en archivos de destino existentes.

--wait espera a que termine la ejecución y descarga los resultados completados. Sin esta opción, el comando de envío termina tras presentar la solicitud. Si hay una espera de revisión o un trabajo de recuperación independiente, aplica el procedimiento de conservación del estado de ejecución en CI: antes de que termine el ejecutor, conserva el puntero específico sin secretos situado en el directorio personal, la ruta absoluta original de la raíz del proyecto y el estado correspondiente del contenido de origen, la configuración, los archivos de destino y el Lockfile. Restáuralos en esa misma raíz y autentícate por separado antes de usar lingo pull --dry-run y, después, lingo pull. Si el ejecutor no puede recrear la ruta, usa un checkout persistente y autorizado. Nunca archives credenciales ni todo el contenido de ~/.lingo.

Conserva el código de salida y los resultados notificados para los destinos. La CLI actual falla cuando se notifican destinos fallidos, pero la revisión humana puede dejar una ejecución pendiente de decisiones. Puede seguir existiendo un archivo antiguo mientras la nueva versión está en espera. Completa la revisión y recupera el resultado antes de permitir que el trabajo de entrega lo publique.

Consulta Envío y Recuperación para conocer el comportamiento exacto de los comandos. --yes omite la confirmación de regeneración forzada; no aprueba la revisión humana ni convierte todas las acciones pendientes en trabajo completado.

La CLI omite las comprobaciones de actualizaciones en CI. LINGO_DISABLE_UPDATE_CHECK=1 y LINGO_TELEMETRY_DISABLED=1 ofrecen controles explícitos cuando hacen falta, sin desactivar el tráfico de traducción.

Verifica que el siguiente paso dispone de archivos utilizables #

Contrasta la entrada que debería haber cambiado con la revisión del contenido de origen. La mera existencia de un archivo es una prueba poco sólida si el checkout ya contiene un archivo de destino anterior. Conserva los resultados descargados y el estado del Lockfile de la misma operación, y deja claramente marcados como incompletos los idiomas que hayan fallado o sigan pendientes.

Después, aplica comprobaciones específicas para el recurso:

  • Para la extracción de React, ejecuta lingo extract --check, lingo check, la comprobación de TypeScript del proyecto y la compilación real de la aplicación. Cada una examina una parte distinta del resultado.
  • Para recursos nativos, ejecuta la generación o compilación de recursos de la plataforma.
  • Para contenido estático, analiza los documentos traducidos e inspecciona los enlaces, las variables y la sintaxis conservada.
  • Para que una solicitud de fusión falle cuando las traducciones no estén actualizadas, ejecuta lingo check. No necesita ninguna clave de API.

lingo check funciona a nivel de archivo: informa de un archivo de origen modificado y de un archivo de destino ausente para cada idioma configurado, no de una clave que falte dentro de un archivo existente de Android, Apple, ARB o Markdoc.

Revisa el significado de la traducción como parte del proceso de aceptación elegido. Una compilación puede detectar un recurso mal formado y, aun así, aceptar una frase que cambie una condición importante. Una vez superadas las comprobaciones y la revisión, confirma o publica únicamente las rutas de salida previstas. Mantén una vía de salida para cuando no haya cambios y deja que las comprobaciones obligatorias hagan fallar el trabajo, en lugar de ocultar sus fallos con una confirmación incondicional.

Reanuda el trabajo registrado antes de crear otro que lo sustituya #

Si un trabajo se interrumpe, recupera el identificador de su ejecución y los resultados de los destinos. Si la traducción ha terminado, recupera ese resultado antes de enviar otra solicitud. Si un archivo de destino local ha cambiado durante la espera, resuelve el conflicto de recuperación teniendo a la vista la modificación aceptada; forzar la sobrescritura puede descartar precisamente la corrección que el flujo de trabajo debería conservar.

Conserva el Lockfile durante el diagnóstico. Eliminarlo cambia el estado de referencia del contenido de origen para la siguiente ejecución y puede convertir una recuperación acotada en un trabajo distinto. Inspecciona las diferencias y reintenta solo el ámbito que siga incompleto. Recuperar una ejecución de localización interrumpida explica cómo tomar esa decisión.

Antes de programar el trabajo, prueba tanto el caso de éxito como una espera de revisión humana y una recuperación interrumpida. El paso de lanzamiento debe conservar el último estado aceptado e identificar el idioma incompleto, en lugar de aceptar cualquier archivo por el mero hecho de existir.