Integración con GitHub: Sincroniza traducciones con tu repositorio – better-i18n

Integración con GitHub: Sincroniza traducciones con tu repositorio

better-i18n se conecta directamente a tus repositorios de GitHub. Los eventos Push desencadenan una sincronización automática a través de Webhooks verificados con HMAC-SHA256, las actualizaciones de traducción se entregan como Pull Requests, y el flujo de trabajo Doctor CI protege la calidad de tus traducciones en cada Commit.

Cómo funciona

Entrada: Código a la nube

Cuando haces Push de código a GitHub, better-i18n recibe un evento de Webhook y sincroniza tus archivos de traducción:

1. Push a GitHub — Tu equipo hace Commit de cambios de código
2. Webhook se activa — GitHub envía un evento push, verificado con firma HMAC-SHA256
3. Sincronización de archivos — Los archivos de traducción que coinciden con tus patrones configurados se sincronizan con tu proyecto en la nube
4. Actualizaciones del dashboard — Aparecen nuevas keys, se reflejan las traducciones modificadas

Salida: Nube al código

Cuando los traductores actualizan traducciones en el dashboard (o a través de API/MCP), las publicas de vuelta en tu repositorio:

1. Traducciones actualizadas — A través del dashboard, REST API o herramientas MCP
2. Publish — Llama a publishTranslations o usa el botón Publish del dashboard
3. Pull Request creado — better-i18n crea un PR con los archivos de traducción actualizados en un Branch dedicado
4. Tu equipo revisa y hace Merge — Se aplica el flujo de trabajo estándar de revisión de código

Eventos de Webhook y seguridad

better-i18n usa Webhooks de GitHub App con verificación de firma HMAC-SHA256 para cada evento entrante. No se procesan payloads no autenticados.

Eventos de Webhook admitidos

Cada payload de Webhook se verifica contra la firma HMAC-SHA256 de GitHub antes de procesarse. Las firmas inválidas se rechazan inmediatamente.

Flujo de trabajo de traducción basado en PR

Las actualizaciones de traducción siguen tu proceso de revisión de código existente:

1. Los traductores o agentes de IA actualizan traducciones en el dashboard de better-i18n
2. Cuando estén listas, publica las traducciones en tu repositorio
3. better-i18n crea un Pull Request solo con los archivos de traducción modificados
4. Tu equipo revisa el diff — ve exactamente qué keys cambiaron, qué idiomas se actualizaron
5. Merge cuando estés satisfecho — las traducciones llegan a tu base de código a través del mismo flujo de trabajo que cualquier otro cambio de código

Este enfoque significa:

• Sin Pushes directos — Todos los cambios de traducción pasan por revisión de PR
• Historial de auditoría completo — Cada cambio de traducción se rastrea en el historial de git
• Validación CI — Tu pipeline de CI existente también se ejecuta contra los PRs de traducción
• Soporte de rollback — Revierte un PR de traducción como cualquier otro Commit

Soporte multi-repositorio

Conecta múltiples repositorios a un único proyecto de better-i18n, o conecta el mismo repositorio a múltiples proyectos. Las configuraciones comunes incluyen:

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

Gestión de repositorios

Usa el dashboard o la API tRPC para gestionar los repositorios conectados:

Flujo de trabajo Doctor CI

El flujo de trabajo Doctor es un flujo de trabajo de GitHub Actions que better-i18n puede generar para tu repositorio. Ejecuta verificaciones de salud de traducción en cada Push y Pull Request.

Qué verifica Doctor

• Traducciones faltantes — Keys presentes en tu idioma fuente pero ausentes en idiomas destino
• Keys no utilizadas — Keys definidas en archivos de traducción pero no referenciadas en el código
• Consistencia de formato — Validación de sintaxis de mensajes ICU en todos los idiomas
• Informe de cobertura — Porcentaje de finalización de traducción por idioma

Configurar Doctor

Genera el archivo de flujo de trabajo usando la API tRPC:

github.createDoctorWorkflow

Esto crea un archivo .github/workflows/i18n-doctor.yml en tu repositorio que se ejecuta en cada Push y Pull Request.

Ejemplo de salida de Doctor

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

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

Unused keys: 12
Format errors: 0

Result: WARNING — 2 languages below 95% threshold

Doctor se integra con el sistema de checks de GitHub — los PRs que introducen traducciones faltantes o errores de formato muestran un estado de advertencia.

Permisos de GitHub

better-i18n solicita permisos mínimos de GitHub:

Solo se accede a los archivos que coinciden con tus patrones configurados (p. ej., locales/**/*.json). better-i18n nunca lee tu código fuente, archivos de configuración, ni nada fuera de las rutas de archivos de traducción.

Formato de archivos

better-i18n trabaja con archivos de traducción JSON organizados por locale y namespace:

your-repo/
├── locales/
│   ├── en/
│   │   ├── common.json
│   │   ├── auth.json
│   │   └── dashboard.json
│   ├── tr/
│   │   ├── common.json
│   │   ├── auth.json
│   │   └── dashboard.json
│   └── de/
│       └── ...

Configura qué patrones de archivos sincroniza better-i18n en la configuración de tu proyecto.

CLI: Detecta keys de tu base de código

La @better-i18n/cli conecta tu desarrollo local con el proyecto en la nube.

Buscar cadenas codificadas

npx @better-i18n/cli scan

Detecta texto sin traducir en tu base de código React/Next.js:

components/sign-up.tsx (11)
  24:13  missing  "Create an account"  i18n/jsx-text
  32:22  missing  "Name"               i18n/jsx-text

✖ 87 problems (87 missing translations)

Compatible con:

• useTranslations('namespace') — Componentes cliente
• getTranslations('namespace') — Componentes servidor (Next.js App Router)
• Texto JSX, atributos y ternarios basados en locale

Comparar local vs. nube

npx @better-i18n/cli sync

Muestra qué está en tu código pero no en la nube, y qué está en la nube pero no se usa en el código:

Coverage:
  Local → Remote: 59%
  Remote Used: 63%

⊕ Missing in Remote (473 keys)
  pages (300)
    affordableEnglishLearning (meta.title, meta.description, ...+12)

⊖ Unused in Code (386 keys)
  features (25)
    practiceSpeaking (title, subtitle, icon)

Integración CI/CD

Agrega a tu flujo de trabajo de GitHub Actions:

name: i18n 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"
      - run: npx @better-i18n/cli scan --ci
      - run: npx @better-i18n/cli sync --format json

Bloquea los PRs que introducen cadenas sin traducir. Audita la cobertura de traducción en cada Push.

Hooks pre-Commit

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

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

Seguimiento de Sync

Cada operación de Sync se rastrea como un trabajo con estado completo y logs:

// MCP tool: getSyncs
{
  "project": "your-org/your-project",
  "status": "completed",
  "type": "source_sync"
}

Tipos de Sync:

• initial_import — Primera sincronización al conectar un repositorio
• source_sync — Desencadenado por eventos Push de GitHub
• cdn_upload — Despliegue CDN
• batch_publish — Publicación de traducciones a GitHub

Configuración

i18n.config.ts

La CLI lee la configuración de tu proyecto desde i18n.config.ts:

export const project = "your-org/your-project";
export const defaultLocale = "en";

export const i18nWorkspaceConfig = {
  project,
  defaultLocale,
  lint: {
    include: ["src/**/*.tsx", "app/**/*.tsx"],
    exclude: ["**/*.test.tsx", "**/*.stories.tsx"],
  },
};

Primeros pasos

1. Instalar la GitHub App — Conecta tu cuenta de GitHub en dash.better-i18n.com
2. Agregar repositorios — Selecciona qué repositorios sincronizar a través de github.addRepository
3. Configurar patrones de archivos — Indica a better-i18n dónde viven tus archivos de traducción
4. Habilitar Doctor CI — Genera el flujo de trabajo de verificación de salud i18n con github.createDoctorWorkflow
5. Instalar la CLI — npm install -D @better-i18n/cli
6. Empezar a sincronizar — Haz Push del código y observa cómo fluyen las traducciones entre GitHub y la nube

La integración con GitHub está disponible en todos los planes.