GitHub Çeviri Senkronizasyonu: Lokalizasyon İş Akışınızı Otomatikleştirin

Dallara dağılmış çeviri dosyaları, JSON anahtarlarının elle kopyala-yapıştır edilmesi, Slack'te "Fransızca çevirileri birisi push etti mi?" diye sorulan mesajlar — bunlar tanıdık geliyorsa, lokalizasyon iş akışınızın otomasyona ihtiyacı var.

GitHub Çeviri Senkronizasyonu, çeviri dosyalarını kod tabanınızla senkronize tutmanın getirdiği manuel yükü ortadan kaldırır. Deponuzdaki yeni çeviri anahtarlarını izler, bunları çeviri için gönderir (yapay zeka veya insan çevirisi) ve tamamlanan çevirileri pull request olarak geri iletir — tüm bunları Git iş akışınızdan ayrılmadan yapar.

Bu rehber, GitHub Çeviri Senkronizasyonunu sıfırdan kurma, PR tabanlı iş akışlarını yapılandırma, CI entegrasyonu ve ekip iş birliği için optimizasyon konularını adım adım ele alır.

GitHub Çeviri Senkronizasyonu Nedir?

GitHub Çeviri Senkronizasyonu, Git deponuz ile çeviri yönetim platformu arasında çift yönlü bir senkronizasyon mekanizmasıdır. Çeviri dosyalarını elle push/pull yapmak yerine, senkronizasyon şunları yapar:

1. Yeni veya değişen anahtarları tespit eder — kod push ettiğinizde
2. Bunları çeviri platformunuza gönderir — çeviriye iletir
3. Tamamlanan çevirileri geri iletir — pull request olarak
4. Çeviri dosyalarını senkronize tutar — dallar arasında

Neden PR Tabanlı Çeviri Teslimi?

Geleneksel lokalizasyon iş akışları CLI push/pull komutlarını kullanır. PR tabanlı yaklaşım daha iyidir çünkü:

Ön Koşullar

GitHub Çeviri Senkronizasyonunu kurmadan önce ihtiyacınız olanlar:

• Çeviri dosyaları içeren bir GitHub deposu (JSON, YAML, PO veya ARB formatında)
• Bir Better i18n projesi (better-i18n.com üzerinden kayıt olabilirsiniz)
• Depo yönetici erişimi (GitHub App yüklemek için)
• Tutarlı bir dizin yapısında çeviri dosyaları

Desteklenen Dizin Yapıları

# Desen 1: Dil dizinleri
locales/
  en/
    common.json
    dashboard.json
  es/
    common.json
    dashboard.json

# Desen 2: Dil dosya son eki
locales/
  common.en.json
  common.es.json
  dashboard.en.json
  dashboard.es.json

# Desen 3: Tek dizin, dil ön eki
i18n/
  en.json
  es.json
  fr.json

# Desen 4: Framework'e özel (ör. Flutter ARB)
lib/l10n/
  app_en.arb
  app_es.arb

Adım 1: GitHub App Kurulumu

GitHub Senkronizasyonu, deponuzdaki çeviri dosyalarına okuma/yazma erişimine sahip bir GitHub App aracılığıyla çalışır.

1. Better i18n proje paneline gidin
2. Settings ardından Integrations bölümüne gidin
3. Connect GitHub butonuna tıklayın
4. Senkronize etmek istediğiniz depoları seçin
5. İstenen izinleri onaylayın

İzin Açıklamaları

GitHub App yalnızca çeviriyle ilgili dosyalara erişir. Kaynak kodunuzu, ortam değişkenlerinizi veya gizli anahtarlarınızı okumaz.

Adım 2: Senkronizasyonu Yapılandırma

Depo kök dizininizde bir yapılandırma dosyası oluşturun:

# better-i18n.yml
sync:
  # Kaynak dil — anahtarlar bu dilin dosyalarından çıkarılır
  sourceLanguage: en

  # Hedef diller — çeviriler bunlar için oluşturulur
  targetLanguages:
    - es
    - fr
    - de
    - ja
    - ko
    - "zh-CN"

  # Çeviri dosyaları için yol deseni
  # {locale} ve {namespace} yer tutucularıyla glob desenleri destekler
  paths:
    - "locales/{locale}/{namespace}.json"

  # Alternatif: dil başına tek dosya
  # paths:
  #   - "locales/{locale}.json"

  # Değişiklikleri izlenecek dal (varsayılan: main)
  baseBranch: main

  # Çevirilerin teslim şekli
  delivery:
    # "pr" pull request oluşturur, "commit" doğrudan push eder (önerilmez)
    method: pr

    # PR dal adlandırma deseni
    branchPattern: "i18n/sync-{timestamp}"

    # Tüm kontroller geçtiğinde PR'ları otomatik birleştir (dal koruması gerekir)
    autoMerge: false

    # Çeviri PR'larına atanacak incelemeciler
    reviewers:
      - "@i18n-team"

    # Çeviri PR'larına eklenecek etiketler
    labels:
      - "i18n"
      - "automated"

  # Yapay zeka çeviri ayarları
  ai:
    # Yeni anahtarları yapay zeka ile otomatik çevir
    autoTranslate: true

    # PR oluşturulmadan önce insan onayı gerektir
    requireApproval: false

    # Yapay zeka çevirmeni için özel talimatlar
    instructions: |
      - Use formal register for German (Sie, not du)
      - Keep brand name "Better i18n" untranslated in all languages
      - Use Oxford comma in English translations

Yapılandırma Seçenekleri Referansı

Adım 3: Senkronizasyon İş Akışını Anlama

Yapılandırma tamamlandıktan sonra, tipik bir geliştirme döngüsünde şunlar gerçekleşir:

Yeni Anahtar Ekleme

Geliştirici               GitHub                Better i18n              GitHub
    |                        |                       |                      |
    |-- commit push -------->|                       |                      |
    |   (en/common.json'a    |-- webhook ----------->|                      |
    |    yeni anahtar ekler) |                       |                      |
    |                        |                       |-- Yapay zeka ------->|
    |                        |                       |   tüm hedef diller   |
    |                        |                       |   için çevirir       |
    |                        |                       |                      |
    |                        |<---------- çevirilerle PR oluştur -----------|
    |                        |                       |                      |
    |<-- PR bildirimi -------|                       |                      |
    |                        |                       |                      |
    |-- incele & birleştir ->|                       |                      |

Mevcut Anahtarları Güncelleme

Mevcut bir anahtarın kaynak metnini değiştirdiğinizde:

1. Senkronizasyon, webhook aracılığıyla değişikliği tespit eder
2. Mevcut çeviriler "inceleme gerekli" olarak işaretlenir
3. Yapay zeka güncellenmiş çevirileri oluşturur
4. Güncellenmiş çevirilerle bir PR oluşturulur
5. İnceleme yapanın karşılaştırabilmesi için önceki çeviriler PR açıklamasında korunur

Anahtar Silme

Kaynak dilden bir anahtar kaldırdığınızda:

1. Senkronizasyon silme işlemini tespit eder
2. İlgili anahtar tüm hedef dil dosyalarından kaldırılır
3. Silme işlemleriyle bir PR oluşturulur
4. Denetim amacıyla silinen tüm anahtarlar PR açıklamasında listelenir

Adım 4: CI Entegrasyonu

Çeviriler birleştirilmeden önce sorunları yakalamak için CI pipeline'ınıza çeviri doğrulama adımları ekleyin.

GitHub Actions İş Akışı

# .github/workflows/i18n-validate.yml
name: Validate Translations

on:
  pull_request:
    paths:
      - "locales/**"
    types: [opened, synchronize]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install

      - name: Validate translation coverage
        run: |
          bunx @better-i18n/cli coverage \
            --min 95 \
            --format github-actions

      - name: Validate ICU syntax
        run: |
          bunx @better-i18n/cli validate \
            --format github-actions

      - name: Check for unused keys
        run: |
          bunx @better-i18n/cli lint \
            --unused \
            --format github-actions

      - name: Comment coverage report on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const { execSync } = require('child_process');
            const report = execSync('bunx @better-i18n/cli coverage --format markdown').toString();
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Translation Coverage Report\n\n${report}`
            });

Zorunlu Durum Kontrolleri

Çeviri doğrulamasını zorunlu kılmak için dal korumasını yapılandırın:

1. Settings ardından Branches ardından Branch protection rules bölümüne gidin
2. Require status checks to pass before merging seçeneğini etkinleştirin
3. Şu kontrolleri ekleyin:
   • Validate translation coverage
   • Validate ICU syntax

Bu sayede bozuk çeviriler veya yetersiz kapsam içeren hiçbir PR birleştirilemez.

Adım 5: Çeviriler için Dal Stratejisi

Varsayılan: Tek Çeviri Dalı

Varsayılan olarak, her senkronizasyon tamamlanan çevirilerle yeni bir dal oluşturur:

main ------------------------------------------------
  \                                 |
   \-- i18n/sync-20260315 ---------/
       (yeni anahtarlar için çeviriler)

Bu, çoğu ekip için iyi çalışır. Her senkronizasyon izole edilmiştir ve çevirileri birleştirmeden önce inceleyebilirsiniz.

İleri Düzey: Özellik Dalı Senkronizasyonu

Özellik dalları kullanan ekipler için, senkronizasyonu özellik dallarını hedefleyecek şekilde yapılandırın:

# better-i18n.yml
sync:
  baseBranch: main
  featureBranchSync:
    enabled: true
    # Bu dalları hedefleyen PR'lar için çevirileri senkronize et
    targetBranches:
      - "main"
      - "develop"
    # Çeviri PR'ını özellik PR'ıyla aynı dalı hedefleyecek şekilde oluştur
    followBranch: true

Özellik dalı senkronizasyonuyla:

main ------------------------------------------------
  \
   \-- feature/new-checkout -------------------------
        \                           |
         \-- i18n/new-checkout -----/
             (bu özellik için çeviriler)

Birleştirme Çakışmalarını Yönetme

Senkronizasyon, çoğu birleştirme çakışmasını otomatik olarak şu şekilde çözer:

1. PR oluşturmadan önce çeviri dallarını rebase eder
2. Çeviri dosyaları için satır tabanlı değil, JSON-farkındalıklı birleştirme kullanır
3. Bir çakışma tespit edilirse senkronizasyonu yeniden tetikler

Otomatik çözüm mümkün değilse, senkronizasyon PR'a bir yorum ekleyerek çakışmayı açıklar ve elle çözüm adımları önerir.

Adım 6: İzleme ve Sorun Giderme

Senkronizasyon Durum Paneli

Better i18n panelinizdeki senkronizasyon sağlığını izleyin:

• Senkronizasyon Geçmişi: Durumlarıyla birlikte her senkronizasyon olayı (başarılı, kısmi, başarısız)
• Bekleyen Çeviriler: Çeviri bekleyen anahtarlar
• Kapsam Trendleri: Dil bazında zaman içinde çeviri kapsamı
• PR Aktivitesi: Açık, birleştirilmiş ve kapatılmış çeviri PR'ları

Yaygın Sorunlar ve Çözümleri

Sorun: Push sırasında senkronizasyon tetiklenmiyor

• GitHub App'in depoya yüklendiğini doğrulayın
• Settings ardından Webhooks bölümünde webhook'un aktif olduğunu kontrol edin
• Push'un yapılandırılmış baseBranch'e yapıldığından emin olun
• Değiştirilen dosyaların yapılandırılmış paths desenleriyle eşleştiğini kontrol edin

Sorun: PR'da birleştirme çakışmaları var

• Senkronizasyon otomatik rebase yapar, ancak dalınız önemli ölçüde ayrıştıysa elle çözüm gerekebilir
• Çeviri PR'ındaki çakışmaları çözün, ardından push edin — senkronizasyon çözümünüzün üzerine yazmaz

Sorun: Yapay zeka çevirileri düşük kaliteli

• Yapılandırmanıza ayrıntılı ai.instructions ekleyin
• Sözlük terimleri ve marka yönergeleri dahil edin
• Kritik diller için requireApproval seçeneğini etkinleştirmeyi düşünün

Sorun: Çok fazla küçük PR oluşuyor

• Değişiklikleri gruplamak için delivery.batchWindow yapılandırın:

sync:
  delivery:
    # Birden fazla push'u tek bir PR'da toplamak için 30 dakika bekle
    batchWindow: 30

İleri Düzey Yapılandırma

Namespace Filtreleme

Yalnızca belirli namespace'leri senkronize edin:

sync:
  paths:
    - "locales/{locale}/common.json"
    - "locales/{locale}/marketing.json"
  # Dahili namespace'leri açıkça hariç tut
  exclude:
    - "locales/{locale}/internal.json"
    - "locales/{locale}/test-fixtures.json"

Özel Commit Mesajları

sync:
  delivery:
    commitMessage: "chore(i18n): sync translations for {languages}"
    prTitle: "chore(i18n): translations update ({date})"
    prBody: |
      ## Automated Translation Update

      This PR contains translations synced from Better i18n.

      **Languages updated:** {languages}
      **Keys added:** {keysAdded}
      **Keys updated:** {keysUpdated}
      **Keys removed:** {keysRemoved}

      ---
      _Generated by Better i18n GitHub Sync_

Webhook Olayları

Özel entegrasyonlar için webhook'lar aracılığıyla senkronizasyon olaylarına abone olabilirsiniz:

sync:
  webhooks:
    - url: "https://your-server.com/api/i18n-webhook"
      events:
        - sync.completed
        - sync.failed
        - pr.created
        - pr.merged
      secret: "${WEBHOOK_SECRET}"  # Better i18n panelinde ayarlayın

Gerçek Dünya Örneği: E-Ticaret Uygulaması Kurulumu

Next.js kullanan tipik bir e-ticaret uygulaması için eksiksiz yapılandırma:

# better-i18n.yml
sync:
  sourceLanguage: en
  targetLanguages:
    - es
    - fr
    - de
    - ja
    - "pt-BR"
    - "zh-CN"

  paths:
    - "messages/{locale}/{namespace}.json"

  baseBranch: main

  delivery:
    method: pr
    branchPattern: "i18n/translations-{date}"
    autoMerge: true  # CI geçtiğinde otomatik birleştir
    reviewers:
      - "@frontend-team"
    labels:
      - "i18n"
      - "auto-merge"
    batchWindow: 15  # Değişiklikleri 15 dakika içinde topla

  ai:
    autoTranslate: true
    requireApproval: false
    instructions: |
      E-commerce context:
      - "Cart" should use shopping cart terminology (not vehicle)
      - Currency amounts should not be translated (they are formatted by code)
      - Product names in {curly braces} are variables — do not translate
      - Use formal register for German and Japanese
      - Use informal register for Spanish and Portuguese
      - Keep "Better i18n" as-is in all languages

  featureBranchSync:
    enabled: true
    targetBranches: ["main", "staging"]
    followBranch: true

Bu yapılandırmayla:

1. main veya staging'e yapılan her push bir senkronizasyonu tetikler
2. Yeni anahtarlar dakikalar içinde yapay zeka ile çevrilir
3. Çeviriler otomatik birleştirilebilir PR'lar olarak gelir
4. Özellik dalları kendi çeviri PR'larını alır
5. CI, birleştirme öncesinde kapsam ve sözdizimini doğrular

Sonuç

GitHub Çeviri Senkronizasyonu, lokalizasyonu manuel ve hataya açık bir süreçten, mevcut geliştirme iş akışınıza doğal olarak uyan otomatik bir pipeline'a dönüştürür. Temel ilkeler:

1. Çeviriler Git'te yaşar — tam geçmiş, dal koruması, kod incelemesi
2. Senkronizasyon otomatiktir — unutulacak manuel push/pull komutları yok
3. PR'lar inceleme sağlar — çeviriler, diğer kod değişiklikleri gibi incelenir
4. CI kaliteyi garanti eder — kapsam eşikleri ve sözdizimi doğrulaması hatalı çevirileri engeller
5. Yapay zeka hızlandırır — yeni anahtarlar günler değil, dakikalar içinde çevrilir

Kurulum yaklaşık 30 dakika sürer. İlk haftada kazanılan zaman genellikle kurulum yatırımını aşar.

Çeviri iş akışınızı otomatikleştirmeye hazır mısınız? Better i18n ile başlayın ve GitHub deponuzu dakikalar içinde bağlayın.