GitHub Integration: Sync Translations with Your Repository

GitHub Integration: Sync Translations with Your Repository

better-i18n connects directly to your GitHub repositories. Push events trigger automatic sync via HMAC-SHA256 verified webhooks, translation updates ship as pull requests, and the Doctor CI workflow guards your translation health on every commit.

How It Works

Inbound: Code to Cloud

When you push code to GitHub, better-i18n receives a webhook event and syncs your translation files:

1. Push to GitHub — Your team commits code changes
2. Webhook fires — GitHub sends a push event, verified with HMAC-SHA256 signature
3. File sync — Translation files matching your configured patterns are synced to your cloud project
4. Dashboard updates — New keys appear, changed translations are reflected

Outbound: Cloud to Code

When translators update translations in the dashboard (or via API/MCP), you publish them back to your repository:

1. Translations updated — Via dashboard, REST API, or MCP tools
2. Publish — Call publishTranslations or use the dashboard publish button
3. Pull request created — better-i18n creates a PR with the updated translation files on a dedicated branch
4. Your team reviews and merges — Standard code review workflow applies

Webhook Events and Security

better-i18n uses GitHub App webhooks with HMAC-SHA256 signature verification for every incoming event. No unauthenticated payloads are processed.

Supported Webhook Events

Every webhook payload is verified against GitHub's HMAC-SHA256 signature before processing. Invalid signatures are rejected immediately.

PR-Based Translation Workflow

Translation updates follow your existing code review process:

1. Translators or AI agents update translations in the better-i18n dashboard
2. When ready, publish translations to your repository
3. better-i18n creates a pull request with only the changed translation files
4. Your team reviews the diff — see exactly which keys changed, which languages were updated
5. Merge when satisfied — translations land in your codebase through the same workflow as any other code change

This approach means:

• No direct pushes — All translation changes go through PR review
• Full audit trail — Every translation change is tracked in git history
• CI validation — Your existing CI pipeline runs against translation PRs too
• Rollback support — Revert a translation PR like any other commit

Multi-Repository Support

Connect multiple repositories to a single better-i18n project, or connect the same repository to multiple projects. Common setups include:

• Monorepo — One repository with multiple apps sharing a translation project
• Micro-frontends — Multiple repositories contributing to a shared set of translations
• Platform + mobile — Web and mobile repositories syncing from the same translation source

Repository Management

Use the dashboard or the tRPC API to manage connected repositories:

Doctor CI Workflow

The Doctor workflow is a GitHub Actions workflow that better-i18n can generate for your repository. It runs translation health checks on every push and pull request.

What Doctor Checks

• Missing translations — Keys present in your source language but missing in target languages
• Unused keys — Keys defined in translation files but not referenced in code
• Format consistency — ICU message syntax validation across all languages
• Coverage report — Per-language translation completion percentage

Setting Up Doctor

Generate the workflow file using the tRPC API:

github.createDoctorWorkflow

This creates a .github/workflows/i18n-doctor.yml file in your repository that runs on every push and pull request.

Example Doctor Output

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 integrates with GitHub's check system — PRs that introduce missing translations or format errors show a warning status.

GitHub Permissions

better-i18n requests minimal GitHub permissions:

Only files matching your configured patterns (e.g., locales/**/*.json) are accessed. better-i18n never reads your source code, configuration files, or anything outside the translation file paths.

File Format

better-i18n works with JSON translation files organized by locale and namespace:

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

Configure which file patterns better-i18n syncs in your project settings.

CLI: Detect Keys from Your Codebase

The @better-i18n/cli bridges your local development with the cloud project.

Scan for Hardcoded Strings

npx @better-i18n/cli scan

Detects untranslated text in your React/Next.js codebase:

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)

Supports:

• useTranslations('namespace') — Client components
• getTranslations('namespace') — Server components (Next.js App Router)
• JSX text, attributes, and locale-based ternaries

Compare Local vs Cloud

npx @better-i18n/cli sync

Shows what is in your code but not in the cloud, and what is in the cloud but not used in 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)

CI/CD Integration

Add to your GitHub Actions workflow:

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

Block PRs that introduce untranslated strings. Audit translation coverage on every push.

Pre-Commit Hooks

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

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

Sync Tracking

Every sync operation is tracked as a job with full status and logs:

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

Sync types:

• initial_import — First sync when connecting a repository
• source_sync — Triggered by GitHub push events
• cdn_upload — CDN deployment
• batch_publish — Publishing translations to GitHub

Configuration

i18n.config.ts

The CLI reads your project configuration from 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"],
  },
};

Getting Started

1. Install the GitHub App — Connect your GitHub account at dash.better-i18n.com
2. Add repositories — Select which repositories to sync via github.addRepository
3. Configure file patterns — Tell better-i18n where your translation files live
4. Enable Doctor CI — Generate the i18n health check workflow with github.createDoctorWorkflow
5. Install the CLI — npm install -D @better-i18n/cli
6. Start syncing — Push code and watch translations flow between GitHub and the cloud

GitHub integration is available on all plans.