Ingeniería/12 de marzo de 2026/9 min de lectura

Cómo sincronizar traducciones con GitHub automáticamente: Una guía completa de localización CI/CD

Eray Gündoğmuş

La mayoría de los equipos gestionan las traducciones a través de un doloroso ciclo manual: exportar cadenas, enviarlas a traductores, esperar, recibir archivos de vuelta, copiarlos al repositorio, resolver conflictos de merge y repetir. Este proceso se rompe rápidamente cuando publicas con frecuencia o soportas múltiples idiomas.

Hay una mejor manera. Conectando tu repositorio de GitHub directamente a tu sistema de gestión de traducciones, puedes automatizar todo el ciclo — desde la detección de nuevas cadenas en el código hasta la entrega de traducciones terminadas como pull requests.

Esta guía explica cómo configurar la sincronización automática de traducciones con GitHub usando better-i18n, cubriendo los mecanismos de webhook, el flujo de trabajo de entrega basado en PRs, las configuraciones multi-repositorio y el flujo de trabajo de verificación de salud Doctor CI.

¿Por qué automatizar la sincronización de traducciones?

Antes de entrar en la configuración, vale la pena entender qué te cuestan los flujos de trabajo manuales de traducción:

Cambio de contexto — Los desarrolladores alternan entre código y archivos de traducción
Traducciones desactualizadas — Las exportaciones manuales significan que los traductores trabajan con cadenas fuente obsoletas
Conflictos de merge — Los archivos JSON de traducción son imanes de conflictos cuando varias personas los tocan
Cobertura faltante — No hay forma automatizada de saber si una nueva característica se publicó sin traducciones
Entrega lenta — Las traducciones esperan en una cola en lugar de fluir continuamente

Automatizar la sincronización entre GitHub y tu plataforma de traducción elimina estos cuellos de botella. Cada push a tu repositorio activa la detección de claves. Cada traducción completada se entrega como un pull request. Las verificaciones CI detectan traducciones faltantes antes de que lleguen a producción.

Descripción general de la arquitectura

El sistema de sincronización tiene dos direcciones:

Entrante (Código a la nube): Cuando los desarrolladores hacen push de código, GitHub envía un webhook a better-i18n. La plataforma lee tus archivos de traducción, detecta claves nuevas o modificadas y actualiza el panel de control en la nube. Los traductores ven las nuevas cadenas inmediatamente.

Saliente (Nube al código): Cuando las traducciones están completas, better-i18n crea un pull request en tu repositorio con los archivos JSON actualizados. Tu equipo revisa y hace merge a través del flujo de trabajo estándar de revisión de código.

Ambas direcciones están aseguradas con verificación de firma HMAC-SHA256. No se procesan payloads no autenticados.

Paso 1: Instalar la GitHub App

Comienza conectando tu cuenta de GitHub a better-i18n:

Ve a dash.better-i18n.com y abre la configuración de tu proyecto
Haz clic en Connect GitHub para instalar la GitHub App de better-i18n
Selecciona a qué repositorios puede acceder la app — puedes conceder acceso a repositorios específicos o a toda tu organización
Autoriza los permisos solicitados

better-i18n solicita permisos mínimos:

Permiso	Propósito
Repository Contents	Leer/escribir archivos de traducción (solo archivos que coincidan con tus patrones configurados)
Pull Requests	Crear PRs para actualizaciones de traducción
Webhooks	Recibir eventos push para activar la sincronización

La app nunca accede a tu código fuente, variables de entorno, secrets o archivos fuera de tus patrones de archivos de traducción.

Paso 2: Añadir repositorios

Una vez instalada la GitHub App, añade los repositorios que quieres sincronizar. Puedes hacerlo desde el panel de control o programáticamente:

github.addRepository({
  project: "your-org/your-project",
  repositoryId: 123456789,
  branch: "main",
  filePattern: "locales/{locale}/{namespace}.json"
})

El parámetro filePattern le indica a better-i18n dónde encontrar tus archivos de traducción. Los patrones comunes incluyen:

locales/{locale}/{namespace}.json — Carpetas de locale con archivos de namespace
src/i18n/{locale}.json — Archivo único por locale
packages/*/locales/{locale}.json — Monorepo con traducciones por paquete

Soporte multi-repositorio

No estás limitado a un solo repositorio. better-i18n soporta varias configuraciones multi-repositorio:

Monorepo: Un repositorio con múltiples apps que comparten un proyecto de traducción
Micro-frontends: Múltiples repositorios que contribuyen a un conjunto de traducciones compartido
Plataforma + móvil: Repositorios web y móvil sincronizándose desde la misma fuente de traducción

Cada repositorio puede tener su propio patrón de archivo y configuración de rama. Las traducciones fluyen entre todos los repositorios conectados y el proyecto central en la nube.

Paso 3: Entender los mecanismos de webhook

Una vez que un repositorio está conectado, GitHub envía eventos webhook a better-i18n. Esto es lo que hace cada evento:

Eventos Push

El evento push es el activador principal de sincronización. Cuando haces push de código a una rama conectada:

GitHub envía el payload del push a better-i18n
La firma del payload se verifica usando HMAC-SHA256
better-i18n comprueba si algún archivo modificado coincide con tu patrón de archivo configurado
Si los archivos de traducción cambiaron, comienza un trabajo de sincronización
Las nuevas claves se añaden al proyecto en la nube, las traducciones modificadas se actualizan
El estado de sincronización se rastrea y es visible en el panel de control

Solo los pushes a ramas configuradas activan la sincronización. Hacer push a una rama de característica no activará la sincronización a menos que la hayas configurado explícitamente.

Eventos del ciclo de vida de la instalación

Evento	Qué sucede
`installation.deleted`	La integración se desinstala automáticamente y todas las suscripciones de webhook se limpian
`installation.suspend`	La sincronización se pausa — no se procesan webhooks hasta que se reanude la instalación
`installation.unsuspend`	La sincronización se reanuda — los webhooks se procesan normalmente de nuevo

Estos eventos aseguran que la integración permanezca sincronizada con el estado de instalación de tu GitHub App. Si un administrador de la organización suspende la app, better-i18n detiene el procesamiento inmediatamente en lugar de acumular entregas de webhook fallidas.

Paso 4: Configurar el flujo de trabajo de traducción basado en PRs

El flujo saliente — entregar traducciones de vuelta a tu repositorio — usa pull requests en lugar de pushes directos. Esta es una elección de diseño deliberada:

¿Por qué Pull Requests?

La revisión de código también aplica a las traducciones. Los revisores pueden detectar problemas de contexto, errores de marcadores de posición o problemas de formato antes de que las traducciones lleguen a producción.
CI se ejecuta contra los cambios de traducción. Tu suite de pruebas, linters y proceso de build validan que las nuevas traducciones no rompan nada.
Rastro de auditoría completo en git. Cada cambio de traducción es un commit con un diff claro que muestra exactamente qué cambió.
Reversión fácil. Revierte un PR de traducción de la misma manera que reviertes cualquier otro cambio.

Cómo funciona

Los traductores o agentes de IA actualizan traducciones en el panel de better-i18n
Cuando un lote de traducciones está listo, se activa una publicación
better-i18n crea una rama en tu repositorio (p.ej., better-i18n/translations-2026-03-13)
Los archivos JSON de traducción actualizados se commitean a esa rama
Se abre un pull request contra tu rama base configurada
Tu equipo revisa el diff y hace merge cuando está satisfecho

El PR incluye solo archivos de traducción — no se tocan otros archivos. El diff muestra claramente qué claves cambiaron y en qué idiomas.

Publicar traducciones

Puedes activar una publicación a través de múltiples canales:

Panel de control: Haz clic en el botón "Publish to GitHub" en la configuración del proyecto
REST API: Llama al endpoint de publicación programáticamente
Herramientas MCP: Usa publishTranslations desde flujos de trabajo de agentes de IA

Paso 5: Activar el flujo de trabajo Doctor CI

El flujo de trabajo Doctor es un flujo de trabajo de GitHub Actions que monitorea la salud de las traducciones en cada commit. Piénsalo como ESLint para tus traducciones.

Generando el flujo de trabajo

Usa la API tRPC para generar el archivo de flujo de trabajo:

github.createDoctorWorkflow({
  project: "your-org/your-project",
  repositoryId: 123456789
})

Esto crea un archivo .github/workflows/i18n-doctor.yml en tu repositorio.

Qué verifica Doctor

Traducciones faltantes — Claves presentes en tu idioma fuente pero ausentes en uno o más idiomas de destino. Doctor reporta recuentos exactos por idioma.

Claves sin usar — Claves definidas en tus archivos de traducción pero que nunca se referencian en tu base de código. Estas añaden sobrecarga a tus bundles de traducción y confunden a los traductores.

Consistencia de formato — Validación de sintaxis de mensajes ICU en todos los idiomas. Detecta errores como marcadores de posición no coincidentes ({count} en inglés pero {nombre} en español) o reglas de plural rotas.

Reporte de cobertura — Un porcentaje de completitud por idioma para que puedas rastrear el progreso de un vistazo.

Ejemplo de salida de Doctor

i18n Doctor Report
==================

Coverage:
  en: 100% (source)
  tr: 94.2% (missing 23 keys)
  de: 87.1% (missing 51 keys)
  ja: 78.3% (missing 86 keys)

Unused keys: 12
Format errors: 0

Result: WARNING — 3 languages below 95% threshold

Doctor se integra con el sistema de verificación de GitHub. Los pull requests que introducen traducciones faltantes o errores de formato muestran un estado de advertencia, dando a los revisores visibilidad inmediata sobre el impacto de las traducciones.

Combinando Doctor con la CLI

Para la cobertura más exhaustiva, combina Doctor con la CLI de better-i18n en tu pipeline de CI:

name: i18n Health Check
on: [push, pull_request]

jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      # Buscar cadenas hardcodeadas que deberían traducirse
      - name: Scan for untranslated strings
        run: npx @better-i18n/cli scan --ci

      # Comparar claves locales con el proyecto en la nube
      - name: Sync coverage report
        run: npx @better-i18n/cli sync --format json

      # Doctor se ejecuta automáticamente a través del flujo de trabajo generado

El comando scan --ci sale con un código distinto de cero si se encuentran cadenas sin traducir, bloqueando el PR. El comando sync --format json produce un reporte de cobertura legible por máquina.

Paso 6: Configurar hooks pre-commit

Detecta problemas de traducción aún antes — antes de que se commitee el código — con hooks pre-commit:

# Usando Husky
npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

El flag --staged le indica a la CLI que solo escanee archivos en el área de staging actual de git, manteniendo el hook rápido incluso en bases de código grandes.

Para un control más granular, usa lint-staged:

{
  "lint-staged": {
    "*.{tsx,jsx}": ["better-i18n scan --ci"]
  }
}

Seguimiento de sincronización y observabilidad

Cada operación de sincronización — entrante o saliente — se rastrea como un trabajo con estado completo y registros. Puedes consultar el historial de sincronización a través de las herramientas MCP o la REST API:

Tipos de sincronización que verás:

initial_import — La primera sincronización cuando se conecta un repositorio. Importa todos los archivos de traducción existentes.
source_sync — Activado por un evento push de GitHub. Sincroniza los archivos de traducción modificados a la nube.
cdn_upload — Deploy de traducciones al CDN para consumo en tiempo de ejecución.
batch_publish — Publica traducciones de vuelta a GitHub como un pull request.

Cada trabajo incluye marcas de tiempo, estado (pendiente, ejecutándose, completado, fallido) y registros detallados para depuración.

Poniendo todo junto

Aquí está el flujo de trabajo de traducción automatizado completo después de la configuración:

Un desarrollador añade una nueva característica con cadenas de cara al usuario
Usan useTranslations('namespace') o getTranslations('namespace') en sus componentes
El hook pre-commit ejecuta scan --staged y advierte sobre cadenas sin traducir
El desarrollador hace push a GitHub
El webhook de push activa una sincronización entrante — las nuevas claves aparecen en el panel de better-i18n
Doctor CI se ejecuta en el PR y reporta la cobertura de traducción
Los traductores (o agentes de IA vía MCP) traducen las nuevas claves
Las traducciones se publican — se crea un PR en el repositorio con archivos JSON actualizados
El equipo revisa y hace merge del PR de traducción
El Deploy al CDN hace las traducciones disponibles en tiempo de ejecución inmediatamente

Todo el ciclo funciona sin copia manual de archivos, pasos de exportación/importación o resolución de conflictos de merge. Las traducciones fluyen continuamente entre tu base de código y la nube.

Configuraciones comunes

Monorepo con múltiples apps

your-monorepo/
├── apps/
│   ├── web/
│   │   └── locales/{locale}/{namespace}.json
│   └── admin/
│       └── locales/{locale}/{namespace}.json

Conecta el repositorio una vez, con un patrón de archivo que cubra ambas apps: apps/*/locales/{locale}/{namespace}.json.

Repositorios separados por plataforma

Conecta cada repositorio independientemente con su propio patrón de archivo. Las traducciones se comparten a través del proyecto central en la nube — actualiza una vez, publica en todos los repositorios.

Flujo de trabajo con ramas de características

Por defecto, la sincronización solo se activa en pushes a tu rama base configurada (normalmente main). Para equipos que quieren sincronización de traducciones en ramas de características, configura múltiples ramas en la configuración del repositorio.

Conclusión

Automatizar la sincronización de traducciones con GitHub elimina los cuellos de botella manuales que ralentizan el desarrollo de productos internacionales. La sincronización entrante impulsada por webhooks mantiene a los traductores trabajando con cadenas frescas. La entrega saliente basada en PRs asegura que los cambios de traducción pasen por el mismo proceso de revisión que el código. Doctor CI detecta brechas de cobertura antes de que lleguen a producción.

La configuración tarda unos quince minutos: instala la GitHub App, añade tus repositorios, configura los patrones de archivo y activa el flujo de trabajo Doctor. A partir de ese momento, las traducciones fluyen automáticamente entre tu base de código y la nube.

Si gestionas traducciones en múltiples repositorios o publicas para usuarios en más de unos pocos idiomas, esta automatización se amortiza en el primer sprint.

Comments

Loading comments...