GitHub Entegrasyonu: Çevirilerinizi Reponuzla Sync Edin – better-i18n

GitHub Entegrasyonu: Çevirilerinizi Repolarınızla Senkronize Edin

better-i18n, GitHub repolarınıza doğrudan bağlanır. Push olayları HMAC-SHA256 ile doğrulanmış Webhook'lar aracılığıyla otomatik senkronizasyon tetikler, çeviri güncellemeleri Pull Request olarak iletilir ve Doctor CI iş akışı her Commit'te çeviri kalitesini korur.

Nasıl Çalışır

Gelen: Koddan Buluta

GitHub'a kod Push ettiğinizde, better-i18n bir Webhook olayı alır ve çeviri dosyalarınızı senkronize eder:

1. GitHub'a Push — Ekibiniz kod değişikliklerini Commit eder
2. Webhook tetiklenir — GitHub, HMAC-SHA256 imzasıyla doğrulanmış bir push olayı gönderir
3. Dosya Sync — Yapılandırılmış kalıplarınızla eşleşen çeviri dosyaları bulut projenizle senkronize edilir
4. Dashboard güncellemeleri — Yeni anahtarlar görünür, değiştirilen çeviriler yansıtılır

Giden: Buluttan Koda

Çevirmenler çevirileri dashboard'da (veya API/MCP aracılığıyla) güncellediğinde, bunları reponuza geri yayınlarsınız:

1. Çeviriler güncellendi — Dashboard, REST API veya MCP araçları aracılığıyla
2. Publish — publishTranslations çağırın veya dashboard'daki Publish düğmesini kullanın
3. Pull Request oluşturuldu — better-i18n, özel bir Branch'ta güncellenmiş çeviri dosyalarıyla bir PR oluşturur
4. Ekibiniz inceler ve Merge eder — Standart kod inceleme iş akışı geçerlidir

Webhook Olayları ve Güvenlik

better-i18n, her gelen olay için HMAC-SHA256 imza doğrulamasıyla GitHub App Webhook'larını kullanır. Kimliği doğrulanmamış payload'lar işlenmez.

Desteklenen Webhook Olayları

Her Webhook payload'ı işlenmeden önce GitHub'ın HMAC-SHA256 imzasına karşı doğrulanır. Geçersiz imzalar hemen reddedilir.

PR Tabanlı Çeviri İş Akışı

Çeviri güncellemeleri mevcut kod inceleme sürecinizi izler:

1. Çevirmenler veya AI ajanları better-i18n dashboard'unda çevirileri günceller
2. Hazır olduğunda çevirileri reponuza yayınlayın
3. better-i18n yalnızca değiştirilen çeviri dosyalarıyla bir Pull Request oluşturur
4. Ekibiniz diff'i inceler — hangi anahtarların değiştiğini, hangi dillerin güncellendiğini tam olarak görür
5. Tatmin olduğunuzda Merge edin — çeviriler, diğer kod değişiklikleriyle aynı iş akışıyla kod tabanınıza eklenir

Bu yaklaşımın anlamı:

• Doğrudan Push yok — Tüm çeviri değişiklikleri PR incelemesinden geçer
• Tam denetim kaydı — Her çeviri değişikliği git geçmişinde izlenir
• CI doğrulama — Mevcut CI pipeline'ınız çeviri PR'larına karşı da çalışır
• Rollback desteği — Çeviri PR'ını diğer Commit'ler gibi geri alın

Çoklu Repo Desteği

Birden fazla repoyu tek bir better-i18n projesine bağlayın veya aynı repoyu birden fazla projeye bağlayın. Yaygın kurulumlar:

• Monorepo — Bir çeviri projesini paylaşan birden fazla uygulamayla tek bir repo
• Mikro ön yüzler — Paylaşılan bir çeviri setine katkıda bulunan birden fazla repo
• Platform + Mobil — Aynı çeviri kaynağından senkronize eden web ve mobil repolar

Repo Yönetimi

Bağlı repoları yönetmek için dashboard'u veya tRPC API'sini kullanın:

Doctor CI İş Akışı

Doctor iş akışı, better-i18n'nin reponuz için oluşturabileceği bir GitHub Actions iş akışıdır. Her Push ve Pull Request'te çeviri sağlık kontrollerini çalıştırır.

Doctor'ın Kontrol Ettikleri

• Eksik çeviriler — Kaynak dilinizde bulunan ancak hedef dillerde eksik olan anahtarlar
• Kullanılmayan anahtarlar — Çeviri dosyalarında tanımlanan ancak kodda referans verilmeyen anahtarlar
• Format tutarlılığı — Tüm dillerde ICU mesaj sözdizimi doğrulaması
• Kapsam raporu — Dil başına çeviri tamamlama yüzdesi

Doctor Kurulumu

tRPC API'sini kullanarak iş akışı dosyasını oluşturun:

github.createDoctorWorkflow

Bu, reponuzda her Push ve Pull Request'te çalışan bir .github/workflows/i18n-doctor.yml dosyası oluşturur.

Doctor Çıktı Örneği

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, GitHub'ın kontrol sistemiyle entegre olur — eksik çeviriler veya format hataları içeren PR'lar uyarı durumu gösterir.

GitHub İzinleri

better-i18n minimal GitHub izinleri talep eder:

Yalnızca yapılandırılmış kalıplarınızla eşleşen dosyalara (ör. locales/**/*.json) erişilir. better-i18n asla kaynak kodunuzu, yapılandırma dosyalarınızı veya çeviri dosyası yolları dışındaki hiçbir şeyi okumaz.

Dosya Formatı

better-i18n, locale ve namespace'e göre düzenlenmiş JSON çeviri dosyalarıyla çalışır:

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

better-i18n'nin senkronize ettiği dosya kalıplarını proje ayarlarınızda yapılandırın.

CLI: Kod Tabanınızdaki Anahtarları Tespit Edin

@better-i18n/cli, yerel geliştirmenizi bulut projesiyle köprüler.

Sabit Kodlanmış Dizeleri Tara

npx @better-i18n/cli scan

React/Next.js kod tabanınızdaki çevrilmemiş metni tespit eder:

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)

Destekler:

• useTranslations('namespace') — İstemci bileşenleri
• getTranslations('namespace') — Sunucu bileşenleri (Next.js App Router)
• JSX metni, öznitelikler ve locale tabanlı üçlü ifadeler

Yerel vs. Bulut Karşılaştırması

npx @better-i18n/cli sync

Kodunuzda olup bulutta olmayan ve bulutta olup kodda kullanılmayan şeyleri gösterir:

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 Entegrasyonu

GitHub Actions iş akışınıza ekleyin:

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

Çevrilmemiş dizeler ekleyen PR'ları engelleyin. Her Push'ta çeviri kapsamını denetleyin.

Pre-Commit Hook'lar

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

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

Sync Takibi

Her Sync işlemi, tam durum ve günlüklerle bir iş olarak izlenir:

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

Sync türleri:

• initial_import — Repo bağlanırken ilk senkronizasyon
• source_sync — GitHub Push olayları tarafından tetiklenir
• cdn_upload — CDN dağıtımı
• batch_publish — Çevirileri GitHub'a yayınlama

Yapılandırma

i18n.config.ts

CLI, i18n.config.ts dosyasından proje yapılandırmanızı okur:

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"],
  },
};

Başlarken

1. GitHub App'i yükleyin — GitHub hesabınızı dash.better-i18n.com adresinde bağlayın
2. Repolar ekleyin — github.addRepository aracılığıyla hangi repoların senkronize edileceğini seçin
3. Dosya kalıplarını yapılandırın — better-i18n'e çeviri dosyalarınızın nerede olduğunu bildirin
4. Doctor CI'ı etkinleştirin — github.createDoctorWorkflow ile i18n sağlık kontrolü iş akışını oluşturun
5. CLI'ı yükleyin — npm install -D @better-i18n/cli
6. Senkronizasyonu başlatın — Kod Push edin ve çevirilerin GitHub ile bulut arasında aktığını izleyin

GitHub entegrasyonu tüm planlarda kullanılabilir.