Çevirileri GitHub ile Otomatik Senkronize Etme: Kapsamlı Bir CI/CD Yerelleştirme Rehberi

Çoğu ekip çevirileri zahmetli bir manuel döngüyle yönetir: metinleri dışa aktar, çevirmenlere gönder, bekle, dosyaları geri al, depoya kopyala, birleştirme çakışmalarını çöz ve tekrarla. Sık sık sürüm çıkardığınızda veya birden fazla dili desteklediğinizde bu süreç hızla çöker.

Daha iyi bir yol var. GitHub deponuzu doğrudan çeviri yönetim sisteminize bağlayarak tüm döngüyü otomatikleştirebilirsiniz — koddaki yeni metinlerin algılanmasından, tamamlanan çevirilerin pull request olarak teslim edilmesine kadar.

Bu rehber, better-i18n kullanarak GitHub ile otomatik çeviri senkronizasyonunun kurulumunu anlatıyor; webhook mekanizmalarını, PR tabanlı teslimat iş akışını, çoklu depo yapılandırmalarını ve Doctor CI sağlık kontrolü iş akışını kapsıyor.

Çeviri Senkronizasyonu Neden Otomatikleştirilmeli?

Kuruluma geçmeden önce, manuel çeviri iş akışlarının size neye mal olduğunu anlamakta fayda var:

• Bağlam değişimi — Geliştiriciler kod ile çeviri dosyaları arasında gidip gelir
• Güncelliğini yitirmiş çeviriler — Manuel dışa aktarımlar, çevirmenlerin eski kaynak metinler üzerinde çalışması demektir
• Birleştirme çakışmaları — JSON çeviri dosyaları, birden fazla kişi dokunduğunda çakışma mıknatısıdır
• Eksik kapsam — Yeni bir özelliğin çevirisiz gönderilip gönderilmediğini bilmenin otomatik bir yolu yoktur
• Yavaş teslimat — Çeviriler sürekli akmak yerine kuyrukta bekler

GitHub ile çeviri platformunuz arasındaki senkronizasyonu otomatikleştirmek bu darboğazları ortadan kaldırır. Deponuza yapılan her push, anahtar algılamayı tetikler. Tamamlanan her çeviri, pull request olarak geri gelir. CI kontrolleri, eksik çevirileri üretime ulaşmadan yakalar.

Mimari Genel Bakış

Senkronizasyon sisteminin iki yönü vardır:

Gelen (Koddan Buluta): Geliştiriciler kod push ettiğinde, GitHub better-i18n'e bir webhook gönderir. Platform çeviri dosyalarınızı okur, yeni veya değişen anahtarları algılar ve bulut panosunu günceller. Çevirmenler yeni metinleri anında görür.

Giden (Buluttan Koda): Çeviriler tamamlandığında, better-i18n deponuzda güncellenmiş JSON dosyalarıyla bir pull request oluşturur. Ekibiniz standart kod inceleme iş akışıyla gözden geçirir ve birleştirir.

Her iki yön de HMAC-SHA256 imza doğrulamasıyla güvence altına alınmıştır. Doğrulanmamış hiçbir yük işlenmez.

Adım 1: GitHub App'i Yükleyin

GitHub hesabınızı better-i18n'e bağlayarak başlayın:

1. dash.better-i18n.com adresine gidin ve proje ayarlarınızı açın
2. better-i18n GitHub App'i yüklemek için Connect GitHub düğmesine tıklayın
3. Uygulamanın hangi depolara erişebileceğini seçin — belirli depolara veya tüm organizasyonunuza erişim verebilirsiniz
4. İstenen izinleri yetkilendirin

better-i18n minimum düzeyde izin ister:

Uygulama kaynak kodunuza, ortam değişkenlerinize, gizli anahtarlarınıza veya çeviri dosya kalıplarınız dışındaki herhangi bir dosyaya asla erişmez.

Adım 2: Depoları Ekleyin

GitHub App yüklendikten sonra senkronize etmek istediğiniz depoları ekleyin. Bunu panodan veya programatik olarak yapabilirsiniz:

github.addRepository({
  project: "your-org/your-project",
  repositoryId: 123456789,
  branch: "main",
  filePattern: "locales/{locale}/{namespace}.json"
})

filePattern parametresi better-i18n'e çeviri dosyalarınızı nerede bulacağını söyler. Yaygın kalıplar şunlardır:

• locales/{locale}/{namespace}.json — Namespace dosyalarıyla yerel ayar klasörleri
• src/i18n/{locale}.json — Yerel ayar başına tek dosya
• packages/*/locales/{locale}.json — Paket başına çevirilerle monorepo

Çoklu Depo Desteği

Tek bir depoyla sınırlı değilsiniz. better-i18n birçok çoklu depo yapılandırmasını destekler:

• Monorepo: Bir çeviri projesini paylaşan birden fazla uygulamaya sahip tek depo
• Mikro-frontendler: Paylaşılan bir çeviri setine katkıda bulunan birden fazla depo
• Platform + mobil: Aynı çeviri kaynağından senkronize olan web ve mobil depoları

Her deponun kendi dosya kalıbı ve dal yapılandırması olabilir. Çeviriler, bağlı tüm depolar ile merkezi bulut projesi arasında akar.

Adım 3: Webhook Mekanizmalarını Anlayın

Bir depo bağlandığında, GitHub better-i18n'e webhook olayları gönderir. Her olayın ne yaptığı şöyledir:

Push Olayları

push olayı birincil senkronizasyon tetikleyicisidir. Bağlı bir dala kod push ettiğinizde:

1. GitHub, push yükünü better-i18n'e gönderir
2. Yük imzası HMAC-SHA256 kullanılarak doğrulanır
3. better-i18n, değişen dosyalardan herhangi birinin yapılandırılmış dosya kalıbıyla eşleşip eşleşmediğini kontrol eder
4. Çeviri dosyaları değiştiyse bir senkronizasyon işi başlar
5. Yeni anahtarlar bulut projesine eklenir, değişen çeviriler güncellenir
6. Senkronizasyon durumu izlenir ve panoda görünür olur

Yalnızca yapılandırılmış dallara yapılan pushlar senkronizasyonu tetikler. Bir özellik dalına push yapmak, açıkça yapılandırmadığınız sürece senkronizasyonu tetiklemez.

Kurulum Yaşam Döngüsü Olayları

Bu olaylar, entegrasyonun GitHub App kurulum durumunuzla senkronize kalmasını sağlar. Bir organizasyon yöneticisi uygulamayı askıya alırsa, better-i18n başarısız webhook teslimatları biriktirmek yerine işlemeyi hemen durdurur.

Adım 4: PR Tabanlı Çeviri İş Akışını Kurun

Giden akış — çevirilerin deponuza geri teslim edilmesi — doğrudan push yerine pull request kullanır. Bu bilinçli bir tasarım tercihidir:

Neden Pull Request?

• Kod incelemesi çeviriler için de geçerlidir. İnceleyenler bağlam sorunlarını, yer tutucu hatalarını veya biçimlendirme problemlerini çeviriler üretime ulaşmadan fark edebilir.
• CI, çeviri değişikliklerinde çalışır. Test paketiniz, linter'larınız ve derleme süreciniz yeni çevirilerin bir şeyleri bozup bozmadığını doğrular.
• Git'te tam denetim izi. Her çeviri değişikliği, tam olarak neyin değiştiğini gösteren net bir diff ile bir commit'tir.
• Kolay geri alma. Bir çeviri PR'ını diğer herhangi bir değişikliği geri aldığınız şekilde geri alın.

Nasıl Çalışır

1. Çevirmenler veya yapay zeka ajanları better-i18n panosunda çevirileri günceller
2. Bir çeviri grubu hazır olduğunda yayınlama tetiklenir
3. better-i18n deponuzda bir dal oluşturur (örn. better-i18n/translations-2026-03-13)
4. Güncellenmiş çeviri JSON dosyaları o dala commit edilir
5. Yapılandırılmış temel dalınıza karşı bir pull request açılır
6. Ekibiniz diff'i inceler ve memnun kaldığında birleştirir

PR yalnızca çeviri dosyalarını içerir — başka hiçbir dosyaya dokunulmaz. Diff, hangi anahtarların hangi dillerde değiştiğini açıkça gösterir.

Çevirileri Yayınlama

Yayınlamayı birden fazla kanal üzerinden tetikleyebilirsiniz:

• Pano: Proje ayarlarında "Publish to GitHub" düğmesine tıklayın
• REST API: Yayınlama endpoint'ini programatik olarak çağırın
• MCP araçları: Yapay zeka ajanı iş akışlarından publishTranslations kullanın

Adım 5: Doctor CI İş Akışını Etkinleştirin

Doctor iş akışı, her commit'te çeviri sağlığını izleyen bir GitHub Actions iş akışıdır. Çevirileriniz için ESLint gibi düşünün.

İş Akışını Oluşturma

İş akışı dosyasını oluşturmak için tRPC API'yi kullanın:

github.createDoctorWorkflow({
  project: "your-org/your-project",
  repositoryId: 123456789
})

Bu, deponuzda bir .github/workflows/i18n-doctor.yml dosyası oluşturur.

Doctor Ne Kontrol Eder

Eksik çeviriler — Kaynak dilinizde mevcut olan ancak bir veya daha fazla hedef dilde bulunmayan anahtarlar. Doctor, dil başına kesin sayıları raporlar.

Kullanılmayan anahtarlar — Çeviri dosyalarınızda tanımlı olan ancak kod tabanınızda hiç referans edilmeyen anahtarlar. Bunlar çeviri paketlerinize gereksiz yük ekler ve çevirmenlerin kafasını karıştırır.

Biçim tutarlılığı — Tüm dillerde ICU mesaj sözdizimi doğrulaması. Eşleşmeyen yer tutucular (İngilizce'de {count} ama İspanyolca'da {nombre}) veya bozuk çoğul kuralları gibi hataları yakalar.

Kapsam raporu — İlerlemeyi bir bakışta takip edebilmeniz için dil başına tamamlanma yüzdesi.

Örnek Doctor Çıktısı

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

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

Unused keys: 12
Format errors: 0

Result: WARNING — 3 languages below 95% threshold

Doctor, GitHub'ın kontrol sistemiyle entegre olur. Eksik çeviriler veya biçim hataları getiren pull request'ler bir uyarı durumu görüntüleyerek inceleyenlere çeviri etkisi konusunda anında görünürlük sağlar.

Doctor'ı CLI ile Birleştirme

En kapsamlı kapsam için, Doctor'ı CI pipeline'ınızda better-i18n CLI ile birleştirin:

name: i18n Health 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"

      # Çevrilmesi gereken sabit kodlanmış metinleri tara
      - name: Scan for untranslated strings
        run: npx @better-i18n/cli scan --ci

      # Yerel anahtarları bulut projesiyle karşılaştır
      - name: Sync coverage report
        run: npx @better-i18n/cli sync --format json

      # Doctor oluşturulan iş akışı aracılığıyla otomatik çalışır

scan --ci komutu çevrilmemiş metinler bulunursa sıfır olmayan bir kodla çıkış yaparak PR'ı engeller. sync --format json komutu makine tarafından okunabilir bir kapsam raporu çıktısı verir.

Adım 6: Pre-Commit Hook'larını Yapılandırın

Çeviri sorunlarını daha da erken yakalayın — kod commit edilmeden önce — pre-commit hook'larıyla:

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

--staged bayrağı CLI'ye yalnızca mevcut git hazırlık alanındaki dosyaları taramasını söyler ve büyük kod tabanlarında bile hook'u hızlı tutar.

Daha ayrıntılı kontrol için lint-staged kullanın:

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

Senkronizasyon İzleme ve Gözlemlenebilirlik

Her senkronizasyon işlemi — gelen veya giden — tam durum ve günlüklerle bir iş olarak izlenir. Senkronizasyon geçmişini MCP araçları veya REST API üzerinden sorgulayabilirsiniz:

Göreceğiniz senkronizasyon türleri:

• initial_import — Bir depo bağlandığında yapılan ilk senkronizasyon. Mevcut tüm çeviri dosyalarını içe aktarır.
• source_sync — GitHub push olayı tarafından tetiklenir. Değişen çeviri dosyalarını buluta senkronize eder.
• cdn_upload — Çevirileri çalışma zamanı tüketimi için CDN'e dağıtır.
• batch_publish — Çevirileri pull request olarak GitHub'a geri yayınlar.

Her iş, hata ayıklama için zaman damgaları, durum (beklemede, çalışıyor, tamamlandı, başarısız) ve ayrıntılı günlükler içerir.

Her Şeyi Bir Araya Getirmek

Kurulumdan sonra tam otomatik çeviri iş akışı şöyledir:

1. Bir geliştirici, kullanıcıya dönük metinler içeren yeni bir özellik ekler
2. Bileşenlerinde useTranslations('namespace') veya getTranslations('namespace') kullanır
3. Pre-commit hook scan --staged çalıştırır ve çevrilmemiş metinler hakkında uyarır
4. Geliştirici GitHub'a push eder
5. Push webhook'u gelen senkronizasyonu tetikler — yeni anahtarlar better-i18n panosunda görünür
6. Doctor CI, PR üzerinde çalışır ve çeviri kapsamını raporlar
7. Çevirmenler (veya MCP aracılığıyla yapay zeka ajanları) yeni anahtarları çevirir
8. Çeviriler yayınlanır — depoda güncellenmiş JSON dosyalarıyla bir PR oluşturulur
9. Ekip çeviri PR'ını inceler ve birleştirir
10. CDN dağıtımı, çevirileri çalışma zamanında anında kullanılabilir hale getirir

Tüm döngü, manuel dosya kopyalama, dışa/içe aktarma adımları veya birleştirme çakışması çözümü olmadan çalışır. Çeviriler, kod tabanınız ile bulut arasında sürekli olarak akar.

Yaygın Yapılandırmalar

Birden Fazla Uygulamalı Monorepo

your-monorepo/
├── apps/
│   ├── web/
│   │   └── locales/{locale}/{namespace}.json
│   └── admin/
│       └── locales/{locale}/{namespace}.json

Depoyu bir kez bağlayın, her iki uygulamayı da kapsayan bir dosya kalıbıyla: apps/*/locales/{locale}/{namespace}.json.

Platform Başına Ayrı Depolar

Her depoyu kendi dosya kalıbıyla bağımsız olarak bağlayın. Çeviriler merkezi bulut projesi aracılığıyla paylaşılır — bir kez güncelleyin, tüm depolara yayınlayın.

Özellik Dalı İş Akışı

Varsayılan olarak, senkronizasyon yalnızca yapılandırılmış temel dalınıza (genellikle main) yapılan pushlarla tetiklenir. Özellik dallarında çeviri senkronizasyonu isteyen ekipler için depo ayarlarında birden fazla dal yapılandırın.

Sonuç

GitHub ile çeviri senkronizasyonunu otomatikleştirmek, uluslararası ürün geliştirmeyi yavaşlatan manuel darboğazları ortadan kaldırır. Webhook tabanlı gelen senkronizasyon, çevirmenlerin güncel metinler üzerinde çalışmasını sağlar. PR tabanlı giden teslimat, çeviri değişikliklerinin kodla aynı inceleme sürecinden geçmesini garanti eder. Doctor CI, kapsam boşluklarını üretime ulaşmadan yakalar.

Kurulum yaklaşık on beş dakika sürer: GitHub App'i yükleyin, depolarınızı ekleyin, dosya kalıplarını yapılandırın ve Doctor iş akışını etkinleştirin. Bu noktadan itibaren çeviriler, kod tabanınız ile bulut arasında otomatik olarak akar.

Birden fazla depoda çeviri yönetiyorsanız veya birkaçtan fazla dilde kullanıcılara ulaşıyorsanız, bu otomasyon ilk sprint'te kendini amorti eder.