Automatiza las traducciones en CI
Haz que la traducción sea un proceso repetible en cada lanzamiento, desde una revisión conocida del contenido fuente hasta archivos revisados y verificaciones de la aplicación.
Un flujo de lanzamiento ya conecta una revisión del contenido fuente con algo que las personas pueden usar. La traducción debe mantener esa conexión. El trabajo necesita saber qué contenido fuente cambió, recuperar los archivos de destino correspondientes y aportar suficiente evidencia para que el siguiente paso pueda aceptarlos o rechazarlos.
Los casos más difíciles surgen después de la primera solicitud exitosa: una persona a cargo de la revisión sigue editando, un ejecutor deja de estar disponible 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 manejar estos casos sin publicar archivos desactualizados ni reemplazar innecesariamente las ediciones aceptadas. El YAML específico de cada proveedor está en las recetas de GitHub Actions, GitLab, Bitbucket y Buildkite.
Decide en qué punto del lanzamiento incorporar las traducciones #
Usa la GitHub App administrada si su flujo de trabajo para repositorios se ajusta a tus necesidades. Los cambios en la rama predeterminada generan una solicitud de incorporación de cambios de traducción; si habilitas el procesamiento de solicitudes de incorporación, los resultados se escriben en la rama de esa solicitud. Aprobar la ejecución autoriza el trabajo de traducción; la revisión del contenido y la integración se realizan después.
Con un ejecutor de CLI, tu flujo de lanzamiento se encarga del envío, la recuperación y la entrega. Elige un destino que se ajuste al proceso de lanzamiento:
| Destino | Decisión que facilita |
|---|---|
| Solo artefacto | Otro trabajo o una persona revisa el resultado antes de hacer cambios en el repositorio o el lanzamiento. |
| Rama de traducción y solicitud de incorporación de cambios | Revisar los cambios traducidos por separado antes de incorporarlos a la rama predeterminada. |
| Rama de la solicitud de incorporación de cambios del contenido fuente | Revisar el contenido fuente y las traducciones juntos en un solo cambio. |
| Commit directo en la rama predeterminada | Entregar sin una solicitud de incorporación de cambios de traducción independiente cuando la política de la rama lo permita explícitamente. |
Para escribir en el repositorio, designa un único ejecutor activo por estado de traducción. De lo contrario, dos ejecutores que trabajen con distintas revisiones del contenido fuente pueden competir por guardar los archivos y el Lockfile en commits. También necesitas reglas basadas en la rama, la ruta o los commits generados para evitar que estos últimos activen la traducción una y otra vez.
Establece el estado de referencia que heredará el ejecutor #
Antes de habilitar las ejecuciones recurrentes, traduce localmente un archivo fuente a un idioma y ejecuta las verificaciones de recursos de la aplicación. Guarda juntos en un commit la configuración, el archivo de destino aceptado y .lingo/lock.json. Un checkout limpio debe reproducir la misma selección de archivos fuente 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 administrar la CLI junto con las dependencias de tu proyecto, instálala con npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 y guarda package.json y package-lock.json en un commit. Luego 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 archivos y el motor de localización. Configura el acceso a la organización y al motor de localización durante la preparación. 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 al paquete que contiene la configuración que quieres usar antes de ejecutar la CLI. Los patrones posicionales acotan los archivos fuente 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 de variables protegidas y bifurcaciones deben determinar dónde se ejecuta el trabajo; no las elimines para conseguir que un trabajo no confiable se complete.
Envía el tipo de trabajo adecuado #
Para una primera traducción desde cero, solicita los archivos de destino faltantes. En un proyecto existente, primero completa las actualizaciones habituales del contenido fuente para los destinos existentes, recupera los resultados y revísalos. Después, agrega los idiomas faltantes y genera los archivos que faltan, sin cambiar esa revisión del contenido fuente. Sigue Agregar un idioma antes de ejecutar este comando:
lingo push --backfill-missing --waitPara cambios en el contenido fuente respecto al estado de referencia establecido:
lingo push --waitUn envío inicial sin opciones adicionales puede registrar el estado del contenido fuente sin traducirlo. La generación de archivos faltantes aporta esa tarea; los envíos habituales posteriores determinan el trabajo a partir de los cambios en el contenido fuente. Un envío con alcance limitado o para generar archivos faltantes no es una solución universal para corregir claves faltantes en archivos de destino existentes.
--wait espera a que termine la ejecución y descarga el resultado completo. Sin esta opción, el envío termina en cuanto se presenta la solicitud. Si hay una espera por revisión o un trabajo de recuperación independiente, necesitas 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 ubicado en el directorio personal, la ruta raíz absoluta original del proyecto y el estado correspondiente del contenido fuente, la configuración, los archivos de destino y el Lockfile. Restáuralos en esa misma ruta raíz y autentícate por separado antes de usar lingo pull --dry-run y luego 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 estado de salida y los resultados reportados para los destinos. La CLI actual falla si se reportan destinos fallidos, pero la revisión humana puede dejar una ejecución pendiente de decisiones. Un archivo anterior puede seguir existiendo 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 Descarga 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 se necesitan, sin deshabilitar el tráfico de traducción.
Comprueba que el siguiente paso tenga archivos utilizables #
Contrasta la entrada que debería haber cambiado con la revisión del contenido fuente. Que el archivo exista no es evidencia suficiente si el checkout ya contiene un archivo de destino anterior. Conserva el resultado descargado y el estado del Lockfile de la misma operación, y deja claramente marcados como incompletos los idiomas que fallaron o siguen en espera.
Luego usa verificaciones adecuadas para el recurso:
- Para la extracción de React, ejecuta
lingo extract --check,lingo check, la verificació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 y revisa los enlaces, las variables y la sintaxis preservada.
- Para que una solicitud de integración falle cuando las traducciones estén desactualizadas, ejecuta
lingo check. No necesita una clave de API.
lingo check funciona a nivel de archivo: reporta un archivo fuente modificado y un archivo de destino faltante para cada idioma configurado, no una clave faltante 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 con formato incorrecto y aun así aceptar una oración que cambie una condición importante. Una vez que las verificaciones y la revisión se completen correctamente, guarda en un commit o publica solo las rutas de salida previstas. Mantén una salida para cuando no haya cambios y deja que las verificaciones obligatorias hagan fallar el trabajo, en lugar de ocultar sus fallos con un commit incondicional.
Reanuda el trabajo registrado antes de crear uno que lo reemplace #
Tras la interrupción de un trabajo, recupera su identificador de ejecución y los resultados de los destinos. Si la traducción se completó, descarga ese resultado antes de enviar otra solicitud. Si un archivo de destino local cambió durante la espera, resuelve el conflicto de descarga teniendo a la vista la edición aceptada; sobrescribirlo a la fuerza puede descartar precisamente la corrección que el flujo de trabajo debe preservar.
Conserva el Lockfile durante el diagnóstico. Eliminarlo cambia el estado de referencia del contenido fuente para la siguiente ejecución y puede convertir una recuperación acotada en un trabajo diferente. Revisa las diferencias y vuelve a intentar solo la parte que siga incompleta. Recuperar una ejecución de localización interrumpida explica esa decisión en detalle.
Antes de programar el trabajo, prueba una espera por revisión humana y una recuperación interrumpida, además del caso exitoso. El paso de lanzamiento debe conservar el último estado aceptado e identificar el idioma incompleto, en lugar de aceptar cualquier archivo solo porque existe.