Intégration GitHub : Synchronisez vos traductions avec votre repository – better-i18n

Intégration GitHub : Synchronisez vos traductions avec votre repository

better-i18n se connecte directement à vos repositories GitHub. Les événements Push déclenchent une synchronisation automatique via des Webhooks vérifiés HMAC-SHA256, les mises à jour de traduction sont livrées sous forme de Pull Requests, et le workflow Doctor CI surveille la santé de vos traductions à chaque Commit.

Comment ça fonctionne

Entrant : Code vers le cloud

Lorsque vous Pushez du code vers GitHub, better-i18n reçoit un événement Webhook et synchronise vos fichiers de traduction :

1. Push vers GitHub — Votre équipe Commit des modifications de code
2. Le Webhook se déclenche — GitHub envoie un événement push, vérifié avec une signature HMAC-SHA256
3. Synchronisation des fichiers — Les fichiers de traduction correspondant à vos patterns configurés sont synchronisés avec votre projet cloud
4. Mises à jour du dashboard — Les nouvelles keys apparaissent, les traductions modifiées sont reflétées

Sortant : Cloud vers le code

Lorsque les traducteurs mettent à jour des traductions dans le dashboard (ou via API/MCP), vous les publiez dans votre repository :

1. Traductions mises à jour — Via le dashboard, REST API ou les outils MCP
2. Publish — Appelez publishTranslations ou utilisez le bouton Publish du dashboard
3. Pull Request créé — better-i18n crée un PR avec les fichiers de traduction mis à jour sur un Branch dédié
4. Votre équipe révise et Merge — Le workflow standard de révision de code s'applique

Événements Webhook et sécurité

better-i18n utilise les Webhooks de GitHub App avec vérification de signature HMAC-SHA256 pour chaque événement entrant. Aucun payload non authentifié n'est traité.

Événements Webhook pris en charge

Chaque payload Webhook est vérifié par rapport à la signature HMAC-SHA256 de GitHub avant traitement. Les signatures invalides sont rejetées immédiatement.

Workflow de traduction basé sur PR

Les mises à jour de traduction suivent votre processus de révision de code existant :

1. Les traducteurs ou agents IA mettent à jour les traductions dans le dashboard better-i18n
2. Quand elles sont prêtes, publiez les traductions dans votre repository
3. better-i18n crée un Pull Request uniquement avec les fichiers de traduction modifiés
4. Votre équipe révise le diff — voyez exactement quelles keys ont changé, quelles langues ont été mises à jour
5. Merge quand satisfait — les traductions atterrissent dans votre base de code via le même workflow que tout autre changement de code

Cette approche signifie :

• Pas de Pushes directs — Tous les changements de traduction passent par la révision PR
• Piste d'audit complète — Chaque changement de traduction est suivi dans l'historique git
• Validation CI — Votre pipeline CI existant s'exécute aussi contre les PRs de traduction
• Support de rollback — Revertez un PR de traduction comme n'importe quel autre Commit

Support multi-repository

Connectez plusieurs repositories à un seul projet better-i18n, ou connectez le même repository à plusieurs projets. Les configurations courantes incluent :

• Monorepo — Un repository avec plusieurs apps partageant un projet de traduction
• Micro-frontends — Plusieurs repositories contribuant à un ensemble partagé de traductions
• Plateforme + mobile — Repositories web et mobile synchronisant depuis la même source de traduction

Gestion des repositories

Utilisez le dashboard ou l'API tRPC pour gérer les repositories connectés :

Workflow Doctor CI

Le workflow Doctor est un workflow GitHub Actions que better-i18n peut générer pour votre repository. Il exécute des vérifications de santé des traductions à chaque Push et Pull Request.

Ce que Doctor vérifie

• Traductions manquantes — Keys présentes dans votre langue source mais absentes dans les langues cibles
• Keys inutilisées — Keys définies dans les fichiers de traduction mais non référencées dans le code
• Cohérence du format — Validation de la syntaxe des messages ICU dans toutes les langues
• Rapport de couverture — Pourcentage de complétion de traduction par langue

Configurer Doctor

Générez le fichier de workflow en utilisant l'API tRPC :

github.createDoctorWorkflow

Cela crée un fichier .github/workflows/i18n-doctor.yml dans votre repository qui s'exécute à chaque Push et Pull Request.

Exemple de sortie 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 s'intègre avec le système de checks de GitHub — les PRs qui introduisent des traductions manquantes ou des erreurs de format affichent un statut d'avertissement.

Permissions GitHub

better-i18n demande des permissions GitHub minimales :

Seuls les fichiers correspondant à vos patterns configurés (ex. locales/**/*.json) sont accédés. better-i18n ne lit jamais votre code source, vos fichiers de configuration, ni rien en dehors des chemins de fichiers de traduction.

Format de fichier

better-i18n fonctionne avec des fichiers de traduction JSON organisés par locale et namespace :

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

Configurez quels patterns de fichiers better-i18n synchronise dans les paramètres de votre projet.

CLI : Détecter les keys depuis votre base de code

La @better-i18n/cli relie votre développement local au projet cloud.

Scanner les chaînes codées en dur

npx @better-i18n/cli scan

Détecte le texte non traduit dans votre base de code 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)

Supporte :

• useTranslations('namespace') — Composants client
• getTranslations('namespace') — Composants serveur (Next.js App Router)
• Texte JSX, attributs et ternaires basés sur la locale

Comparer local vs. cloud

npx @better-i18n/cli sync

Montre ce qui est dans votre code mais pas dans le cloud, et ce qui est dans le cloud mais pas utilisé dans le code :

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)

Intégration CI/CD

Ajoutez à votre workflow 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

Bloquez les PRs qui introduisent des chaînes non traduites. Auditez la couverture des traductions à chaque Push.

Hooks pre-Commit

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

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

Suivi du Sync

Chaque opération de Sync est suivie comme un job avec statut complet et logs :

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

Types de Sync :

• initial_import — Première synchronisation lors de la connexion d'un repository
• source_sync — Déclenché par les événements Push GitHub
• cdn_upload — Déploiement CDN
• batch_publish — Publication des traductions vers GitHub

Configuration

i18n.config.ts

La CLI lit la configuration de votre projet depuis 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"],
  },
};

Démarrage

1. Installer la GitHub App — Connectez votre compte GitHub sur dash.better-i18n.com
2. Ajouter des repositories — Sélectionnez quels repositories synchroniser via github.addRepository
3. Configurer les patterns de fichiers — Indiquez à better-i18n où se trouvent vos fichiers de traduction
4. Activer Doctor CI — Générez le workflow de vérification de santé i18n avec github.createDoctorWorkflow
5. Installer la CLI — npm install -D @better-i18n/cli
6. Commencer à synchroniser — Pushez du code et regardez les traductions circuler entre GitHub et le cloud

L'intégration GitHub est disponible sur tous les plans.