CI/CD İşlem Hattınızda .po Çevirisini Otomatikleştirme

Ekibiniz günde on dört kez main dalına birleştirmeler yapar. Bu birleştirmelerin her biri, yeni bir kullanıcıya yönelik dize (bir düğme etiketi, bir hata mesajı, bir araç ipucu) ekleyebilir. Ve bu dizelerin her biri yalnızca İngilizce olarak başlar. Yayın sürecinizin bir yerinde, bir insan yeni dizeleri fark etmeli, dışa aktarmalı, çevirtmeli, geri yapıştırmalı ve yeniden derlemelidir. Bu insan bir darboğazdır ve hızlı ürün çıkaran bir ekipte bu darboğaz, Alman kullanıcılarınızın iki sprint boyunca İngilizce yer tutucular görmesi anlamına gelir.

Çözüm, CI/CD işlem hattınızda çeviriyi otomatikleştirmektir, böylece yeni dizeler onları tanıtan birleştirmeyle aynı anda çevrilir – rutin durumlarda kritik yolda hiçbir insan olmaz. Bu bugün tamamen başarılabilir, ancak çoğu ekibin düştüğü tuzağa düşmezseniz: %s yer tutucularınızı ve .po yapınızı sessizce bozan, elle yazılmış ham LLM çağrılarından kaçınırsanız. Bu rehber, gerçekçi bir CI işlem hattı modelini, çalışan bir GitHub Actions taslağını ve yardımcı olan bir işlem hattını bozuk derlemeler gönderen bir işlem hattından ayıran tasarım kararlarını (idarilik, yalnızca-yeni-çevirme, inceleme kapıları) ele almaktadır.

Manuel Çeviri Neden Bir Yayın Darboğazıdır

"Neden her yayınlamadan önce çevirmiyorsunuz ki" sorusunun cevabı, zamanlamanın asla uyuşmamasıdır. Dizeler geliştiriciler tarafından sürekli olarak eklenir, ancak çeviri farklı bir kişi tarafından farklı bir programda toplu olarak yapılır. Bu iki ritim arasındaki boşluk, yerelleştirme borcunuzun biriktiği yerdir.

İki Ritim Sorunu

Manuel akışı hayal edin. Bir geliştirici __( 'Export to CSV', 'mytextdomain' ) ekler ve birleştirir. Kimse .pot dosyasını yeniden oluşturmaz. İki hafta sonra birisi wp i18n make-pot komutunu çalıştırır, kırk yeni çevrilmemiş dize fark eder (bazıları tatile çıkan geliştiricilerden kalmıştır), yarısının amacını tahmin eder ve bir .po dosyasını bir çevirmene gönderir. Çeviri geri gelir, yapıştırılır ve yer tutucular belki korunur belki korunmaz. Bu arada, bu dizeler İngilizce olarak üç yayınla birlikte gönderilmiştir.

Buradaki her adım manuel, toplu ve hataya açıktır. CI/CD otomasyonunun amacı, bunu birleştirmede otomatik olarak çalışan, yalnızca gerçekten değişenleri çeviren ve bir şeyler yanlış göründüğünde yüksek sesle başarısız olan bir şeye dönüştürmektir – çeviriyi periyodik bir görevden işlem hattının görünmez bir parçası haline getirmektir.

İşlem Hattı Modeli: Çıkar, Farkı Bul, Çevir, Kaydet

Üst düzeyde, otomatik bir çeviri işi main dalına birleştirmede dört adım çalıştırır: şablonu yeniden oluştur, yeni olanı tespit et, yalnızca bu dizeleri çevir ve sonuçları geri kaydet. Tüm süreç idareli olmalıdır – hiçbir dize değişikliği olmayan bir birleştirmede çalıştırmak sıfır fark ve sıfır gürültü üretmelidir.

Çıkar ve Farkı Bul

Birinci adım çıkarmadır. Kod tabanındaki her dizeyi yansıtması için .pot dosyasını mevcut kaynaktan yeniden oluşturun:

wp i18n make-pot . languages/myplugin.pot

İkinci adım farkı bulmadır. Bu, tüm işlem hattındaki en önemli tasarım kararıdır. Her birleştirmede her dizeyi yeniden çevirmek istemezsiniz – bu, API çağrılarını boşa harcar, bir insanın zaten düzelttiği dizeleri yeniden çevirme riskini taşır ve büyük inceleme farkları üretir. Bunun yerine, yeni .pot dosyasını her mevcut .po dosyasına birleştirin ve yalnızca şimdi boş olan girdileri (gerçekten yeni dizeleri) çevirin:

# Merge new template into each locale, preserving existing translations.
# Newly-added strings appear with empty msgstr; --backup=none keeps the tree clean.
for po in languages/*.po; do
    msgmerge --update --backup=none "$po" languages/myplugin.pot
done

msgmerge işleminden sonra, yalnızca yepyeni dizelerin boş bir msgstr'si olur. Daha önce çevrilmiş her şey dokunulmadan kalır. Bu özellik, işlem hattını idareli yapan ve inceleme farklarınızı küçük ve gözden geçirilebilir tutan şeydir.

Çevir ve Kaydet

Üçüncü adım, yalnızca bu boş girdileri bir çeviri adımına gönderir. Dördüncü adım, güncellenmiş .po dosyasını kaydeder, .mo dosyasını derler ve herhangi bir JSON'u yeniden oluşturur. Tüm bunları bir sonraki aşamada GitHub Actions'a bağlayacağız.

Bir GitHub Actions Taslağı

"Bir iş akışı dosyasında bu aslında nasıl görünür" sorusunun cevabı şudur: main dalına yapılan bir push işleminde tetiklenen, çıkarma-fark-çevirme-kaydetme döngüsünü çalıştıran ve doğrudan main dalına kaydetmek yerine sonuçlarla birlikte bir pull request açan bir iş.

İş Akışı Dosyası

name: Translate on merge

on:
  push:
    branches: [ main ]

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

      - name: Install WP-CLI and gettext
        run: |
          sudo apt-get update && sudo apt-get install -y gettext
          curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
          sudo mv wp-cli.phar /usr/local/bin/wp && sudo chmod +x /usr/local/bin/wp

      - name: Regenerate template and merge into locales
        run: |
          wp i18n make-pot . languages/myplugin.pot
          for po in languages/*.po; do
            msgmerge --update --backup=none "$po" languages/myplugin.pot
          done

      - name: Translate only new (empty) strings
        env:
          TRANSLATE_API_KEY: ${{ secrets.TRANSLATE_API_KEY }}
        run: ./scripts/translate-new-strings.sh languages/

      - name: Compile .mo and JSON
        run: |
          wp i18n make-mo languages/
          wp i18n make-json languages/ --no-purge

      - name: Open pull request with translations
        uses: peter-evans/create-pull-request@v6
        with:
          branch: chore/auto-translations
          title: "chore: auto-translate new strings"
          commit-message: "chore: auto-translate new strings"

Asıl İşin Saklandığı Yer

translate-new-strings.sh adımı, asıl çevirinin gerçekleştiği yerdir. Bu betiğin basit sürümü, her boş girdiyi okur, bir LLM API'sine tek tek dizeler halinde gönderir ve yanıtı geri yapıştırır. Bu basit sürüm tam da bir tuzaktır ve nedenini açıkça belirtmekte fayda var.

Elle Yazılmış LLM Çağrıları Neden Dosyalarınızı Bozar

Kısa cevap: Ham LLM çağrıları .po dizelerinizi düzyazı olarak ele alır ve .po dizeleriniz düzyazı değildir; bunlar, bir sohbet tamamlama çağrısının kolayca yok edebileceği yer tutucular, çoğul biçimler ve bağlam içeren yapılandırılmış verilerdir.

Testlerde Göremeyeceğiniz Yer Tutucu Bozulması

Deleted %d of %s files metnini genel bir sohbet uç noktasına gönderin ve Supprimé %d des %s fichiers (iyi) veya Supprimé %d de % s fichiers (yer tutucuya bir boşluk sızmış ve şimdi sprintf() çalışma zamanında hata veriyor) yanıtını alabilirsiniz. Çoğul bir girdi gönderin ve model iki formu tek bir forma daraltabilir, bu da ikiden fazla çoğul kategoriye sahip dilleri bozabilir. <a href="%s"> içeren bir dize gönderin ve model URL'yi çevirebilir veya etiketi düşürebilir. Bu hataların hiçbiri, her yerel ayarda oluşturulan çıktıyı özel olarak test etmediğiniz sürece testlerinizde görünmez – bunları, hata raporlarını okuyamadığınız kullanıcılar için üretimde çalışma zamanı hataları olarak görürsünüz.

Bakım Tuzağı

Buna karşı prompt mühendisliği ve regex sonrası işlem ile savunmaya çalışabilirsiniz ve birçok ekip bunu yapar. Sorun şu ki, artık kırılgan bir çeviri motorunu yan proje olarak sürdürüyor, Gettext ekosisteminin zaten çözdüğü her yer tutucu uç durumunu yeniden keşfediyorsunuz. Değişkenlerin bozulmasının belirli yollarını ve bunları nasıl önleyeceğinizi kod değişkenlerini bozmadan PO dosyalarını çevirme makalesinde katalogluyoruz. Buradaki ders doğrudan geçerlidir: model kalitesi nadiren sorundur; sorun, etrafındaki yapısal işlemedir.

API Tabanlı Bir Bulut Çevirmenini CI'ya Entegre Etme

İşte burada API tabanlı bir çeviri hizmeti, translate-new-strings.sh tahmininizi değiştirir. Elle LLM çağrıları yazmak ve regex sonrası işlem yapmak yerine, CI adımınız değiştirilmiş .po dosyasını Gettext yapısını zaten anlayan ve temiz çıktı döndüren bir hizmete yükler. İşlem hattı şekli aynı kalır – çıkar, farkı bul, çevir, kaydet – ancak kırılgan orta adım tek bir API çağrısı haline gelir.

Betiğinizi Değiştiren API Çağrısı

SimplePoTranslate tam da bunun için geliştirilmiştir. Otomasyon ve CI'ya uygun bir bulut API'si sunar, böylece iş akışınızın çeviri adımı, .po dosyasını teslim eden ve çevrilmiş bir dosya alan bir istek haline gelir, dize başına döngü olmaz. Sözdizimi Kilitleme özelliği %s, %1$s, {count}, HTML ve kod belirteçlerini otomatik olarak yerinde tutar – önceki bölümdeki tüm hata sınıfı, sizin sürdürdüğünüz regex yerine motor tarafından ele alınır. Tam Gettext çoğul ve msgctxt desteği ile, çoğul biçimler ve bağlam gidiş-dönüş yolculuğunu atlatır, ki bir sohbet tamamlama çağrısı bunu garanti edemez.

İdarelik ve İnceleme Kapısı Sizde Kalır

Hangi motoru kullanırsanız kullanın, iki tasarım kararı hala size aittir. Birincisi, idarelik: msgmerge işleminden sonra yalnızca boş girdileri çevirmeye devam edin, böylece etkisiz birleştirmeler fark üretmez. İkincisi, bir inceleme kapısı: işin doğrudan main dalına kaydetmek yerine, yukarıdaki taslağın yaptığı gibi bir pull request açmasını sağlayın. Makine çevirisi, dizeleri hızlı bir şekilde canlıya almak için mükemmeldir, ancak birleştirmeden önce insan gözü nadir bağlam hatalarını yakalar – ve bir PR, yaygın durumu engellemeden size bu bakışı sağlar. Birçok yerel ayar veya birçok müşteri sitesiyle uğraşan ekipler, bu şekli ajanslar için ideal yerelleştirme iş akışı makalesinden tanıyacaktır; burada aynı otomatikleştirmeli-incelemeli model düzinelerce projeye ölçeklenir.

Sonuç

Bozuk derlemeler göndermeden CI/CD'de çeviriyi otomatikleştirmek için model tutarlıdır: birleştirmede .pot dosyasını yeniden oluşturun, yalnızca yeni dizeleri yüzeye çıkarmak için her yerel ayara msgmerge yapın, yalnızca bu dizeleri çevirin ve sonucu bir pull request inceleme kapısının arkasına kaydedin. İdarelik, farklarınızı temiz tutar; inceleme kapısı ise nadir görülen kötü çevirilerin üretime geçmesini engeller.

Doğru yapılması gereken kısım, çeviri adımının kendisidir. Elle yazılmış LLM çağrıları, testlerinizin yakalayamayacağı şekillerde yer tutucuları ve çoğul biçimleri bozacaktır ve hizmet ettiği özellik kodundan daha çok çeviri yapıştırıcısını sürdürmekle zaman harcayacaksınız. Sözdizimi Kilitleme özelliğine sahip API tabanlı bir motor, bu tüm hata modunu ortadan kaldırır, böylece işlem hattınız yeni dizeleri onları tanıtan birleştirmede çevirir – ve İngilizce olmayan kullanıcılarınız İngilizce yer tutucular görmeyi bırakır.

Yer tutucuları bozmadan işlem hattınızda çeviriyi otomatikleştirmeye hazır mısınız? SimplePoTranslate'i ücretsiz deneyin — kredi kartı gerekmez. Ücretsiz katmanda başlayın, API'yi kendi .po dosyalarınızla doğrulayın ve hazır olduğunuzda CI'ya bağlayın.