← Bloga geri dön
A git diff view showing a locale file with three changed keys highlighted, and only those three keys being sent to the translation API below.

Her şeyi yeniden çevirmenize gerek yok: CI'de delta çeviri nasıl çalışır

By Robert M

Her şeyi yeniden çevirmeye gerek yok: CI'da delta çevirisi nasıl çalışır

Otomatik çeviriyi CI hattınıza bağladıktan sonra doğal olarak şu soru ortaya çıkar: Birisi değişiklik yaptığında her seferinde tüm yerel dosya yeniden mi çevriliyor?

Delta modu olmadan, evet. Kaynak yerel dosyanıza dokunan her push, tüm dosyayı API'ye gönderir; her anahtar, her dize, değişmiş olsun ya da olmasın. Küçük bir proje için başlangıçta bu sorun olmaz. Ancak 10 veya 20 dilde yüzlerce çeviri anahtarı olan olgun bir proje için, son çalıştırmadan beri değişmeyen dizeler için token harcıyor ve aynı çıktıyı almak için gereksiz yere kaynak tüketiyorsunuz.

Delta çeviri bunu çözer. Tam dosyayı göndermek yerine, Action mevcut kaynak dosyanızı saklanan bir baseline ile karşılaştırır, sadece eklenen veya değiştirilmiş anahtarları belirler ve sadece onları API'ye gönderir. Değişmeyen anahtarların çıktısı mevcut çevrilmiş dosyalardan alınır. Token kullanımı yapılan gerçek işe göre düşer.

Baseline nasıl çalışır

Delta modu ilk kez çalıştığında veya tam yenileme zorlandığında, Action kaynak dosyanın tamamını çevirir ve bunu repository'nizde baseline dosyası olarak düz JSON biçiminde saklar. Sonraki çalıştırmalarda Action bu baseline'ı yükler, mevcut kaynak dosyayla farkını alır ve sadece değişen anahtarları içeren bir payload oluşturur.

JSON yerel dosyalar için baseline, mesajlar dizininde .polylingo-baseline.json olarak saklanır. YAML yerel dosyalar için baseline, yerel dizininde .polylingo-yaml-baseline.json olarak saklanır. Laravel PHP lang dosyaları için baseline, lang dizininde .polylingo-laravel-php-baseline.json olarak saklanır.

Baseline, çevrilmiş dosyalarınızla birlikte commit edilir, böylece repository ile birlikte taşınır. Repoyu klonlayan herhangi bir geliştirici, pipeline'ın kullandığı aynı baseline'a sahip olur.

Değişiklik olarak sayılan nedir

Diff, kaynak dosyanızın düzleştirilmiş anahtar temsili üzerinde çalışır. İç içe yapılar karşılaştırmadan önce nokta gösterimi anahtarlarına düzleştirilir:

{
  "nav.home": "Ana Sayfa",
  "nav.about": "Hakkımızda",
  "hero.title": "Platformumuza Hoşgeldiniz",
  "hero.cta": "Başlayın"
}

Bir anahtar delta payload'ına dahil edilir eğer:

  • Mevcut kaynak dosyada var ama baseline'da yok (yeni anahtar)
  • İkisinde de var ama değeri değişmiş (değiştirilmiş anahtar) Baseline'da olup mevcut kaynak dosyada olmayan anahtarlar (silinmiş anahtarlar) çevrilmiş çıktı dosyalarından otomatik olarak kaldırılır. İki tarafta da aynı olan anahtarlar tamamen atlanır ve mevcut çevirileri yerinde bırakılır.

Pratikte nasıl görünüyor

Diyelim ki messages/en.json dosyasında 200 çeviri anahtarı olan bir Next.js projeniz var ve bunlar zaten 12 dile çevrilmiş. Bir geliştirici hero bölümündeki metni güncelliyor ve bir özellik duyurusu için iki yeni anahtar ekliyor. Bu, 200 anahtardan 4'ü değişmiş demektir.

Delta modu olmadan pipeline, her push'ta 12 dilde 200 anahtarın tamamını gönderir. Delta modu ile sadece 4 anahtar gönderilir. Bu çalıştırma için token kullanımı tam çevirinin yaklaşık %2'sidir. Pipeline ayrıca daha hızlıdır çünkü gönderilecek ve beklenilecek veri daha azdır.

Bir ay boyunca düzenli geliştirmede, tasarruf önemli ölçüde birikir. Çoğu push sadece birkaç dizeyi etkiler. Tam yeniden çeviri yalnızca yeni bir dil eklediğinizde veya baseline'ı açıkça sıfırladığınızda gerçekleşir.

Üç PolyLingo GitHub Action'ı

Delta modu, üç PolyLingo çeviri Action'ının tamamında mevcuttur. Her biri belirli içerik türü ve proje yapısı için tasarlanmıştır.

translateAction — JSON ve Markdown

Orijinal Action. next-intl ve i18next tarzında düz JSON yerel dosyalarını işler, büyük dosyalar için async jobs API üzerinden isteğe bağlı Markdown dokümantasyon geçişi ile.

- uses: UsePolyLingo/translate-action@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es,ja,zh
    delta: true
    commit: true
    commit_message: "chore(i18n): sync translations"

Delta baseline: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Marketplace'te Görüntüle

translate-action-yaml — YAML yerel dosyaları

İç içe YAML yerel dosyaları kullanan projeler için: Rails i18n, Vue i18n ve YAML formatını kullanan diğer frameworkler. Action, Rails'in kök yerel anahtarı konvansiyonunu otomatik olarak işler — en.yml bir en: kök anahtarına sahiptir ve her çıktı dosyası doğru hedef yerel anahtarını alır (fr:, de: vb).

PolyLingo API JSON ile doğal olarak çalıştığından, Action iç içe YAML'yi gönderilmeden önce nokta gösterimi JSON'a düzleştirir, çevirir, sonra iç içe yapıyı yeniden oluşturur ve geçerli YAML çıktısı yazar. v1 için bir uyarı: doğal olarak nokta içeren anahtarlar desteklenmez çünkü nokta gösterimi düzleştirmesiyle çakışır.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    source_file: config/locales/en.yml
    locales: fr,de,es,ja
    delta: true
    commit: true

Delta baseline: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Marketplace'te Görüntüle

translate-action-laravel — Laravel lang dosyaları

Laravel projeleri için, JSON çeviri dosyaları (lang/en.json, Laravel 9+ tarzında hem iç içe hem düz yapıları destekler) veya PHP dizi lang dosyaları (lang/en/*.php) kullananlar için. Action, projenizin kullandığı formatı php_format: auto ile otomatik algılar — önce lang/en.json dosyasını kontrol eder, bulunmazsa PHP dizi dosyalarına döner.

PHP dosyaları için, kaynak dosyaları okumak üzere PHP CLI'yi çağırır ve çevrilmiş çıktıyı JavaScript'te geçerli PHP dizi sözdizimine seri hale getirir, ek bağımlılık olmadan. GitHub tarafından barındırılan ubuntu-latest runner'lar varsayılan olarak PHP 8.x içerir, bu yüzden ekstra kurulum gerekmez. PHP 7.4 veya üstü gereklidir.

v1 için bir uyarı: Nokta içeren anahtarlar, nokta gösterimi düzleştirme stratejisi nedeniyle PHP modunda desteklenmez.

- uses: UsePolyLingo/translate-action-laravel@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    lang_dir: lang
    source_locale: en
    locales: fr,de,es,pt,nl
    php_format: auto
    delta: true
    open_pr: true

Delta baseline: formatına bağlı olarak lang/.polylingo-laravel-json-baseline.json veya lang/.polylingo-laravel-php-baseline.json

github.com/UsePolyLingo/translate-action-laravel — Marketplace'te Görüntüle

PR modu vs commit modu

Üç Action da iki çıktı modunu destekler.

Commit modu (commit: true) çevrilmiş dosyaları yazar ve doğrudan mevcut dala commit eder. Basit kurulum, çeviriyi inceleme gerektirmeyen otomatik bir süreç olarak ele alan takımlar için uygundur.

PR modu (open_pr: true) yeni bir dal (polylingo/yaml-<sha>, polylingo/laravel-<sha> vb.) oluşturur, çevrilmiş dosyaları oraya yazar ve temel dalınıza karşı bir pull request açar. Çevrilmiş içeriğin bir insan tarafından incelenmesini isteyen takımlar veya çeviri kalitesinin kullanıcı deneyimini doğrudan etkilediği projeler için daha iyidir.

İkisi de ayarlandığında, PR modu geçerlidir.

PR modu, workflow izinlerinizde pull-requests: write gerektirir:

permissions:
  contents: write
  pull-requests: write

Tam yenileme zorlamak

Delta modu saklanan baseline ile karşılaştırır. Baseline ne gösterirse göstersin her şeyi yeniden çevirmek istiyorsanız delta: false ayarlayın. Bu aynı zamanda baseline'ı mevcut kaynak dosyayla eşitler, böylece sonraki delta çalıştırmaları yeni durumdan başlar.

Tam yenileme, yeni bir hedef dil eklediğinizde, yeni model sürümünde çeviri kalitesi iyileştirmelerini almak istediğinizde veya herhangi bir nedenle baseline gerçeklikten sapmışsa faydalıdır.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    locales: fr,de,es,ja,zh,ko,ar
    delta: false  # tam yenileme, baseline güncellenir
    commit: true

Sonraki adımlar için çıktılar

Üç Action da aynı çıktıları sunar, böylece sonraki workflow adımlarında kullanabilirsiniz:

- uses: UsePolyLingo/translate-action@v1
  id: translate
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es
    delta: true
    commit: true

- name: Çeviri istatistiklerini kaydet
  run: |
    echo "Locales translated: ${{ steps.translate.outputs.locales_translated }}"
    echo "Files changed: ${{ steps.translate.outputs.files_changed }}"
    echo "Tokens used: ${{ steps.translate.outputs.tokens_used }}"

Her çalıştırma ayrıca token kullanımı ve çeviri sonuçlarını loglarda aramadan görebilmeniz için GitHub Actions adım özetine bir tablo yazar.

Başlarken

Üç Action da GitHub Marketplace'te mevcuttur. PolyLingo API anahtarına ihtiyacınız olacak, ücretsiz olarak usepolylingo.com adresinden alınabilir. Ücretsiz katman ayda 50.000 token içerir. Delta modu etkinleştirildiğinde, çoğu proje rutin geliştirme pushlarında bunun çok altında kalır.

API anahtarınızı repository sırrı olarak ekleyin (POLYLINGO_API_KEY) ve ilgili Action'ı workflow'unuza ekleyin. İlk çalıştırma tam çeviri yapar ve baseline'ı ayarlar. Sonraki her çalıştırma sadece değişenleri çevirir.