← Kembali ke blog
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.

Anda tidak perlu menterjemah semuanya semula: bagaimana terjemahan delta berfungsi dalam CI

By Robert M

Anda tidak perlu menterjemah semula semuanya: bagaimana terjemahan delta berfungsi dalam CI

Setelah anda mengautomasikan terjemahan ke dalam saluran CI anda, satu soalan semula jadi muncul dengan cepat: adakah ini menterjemah semula keseluruhan fail lokal setiap kali seseorang membuat perubahan?

Tanpa mod delta, ya. Setiap push yang menyentuh fail lokal sumber anda menghantar keseluruhan fail ke API, setiap kunci, setiap rentetan, sama ada ia berubah atau tidak. Untuk projek kecil pada peringkat awal, itu tidak mengapa. Untuk projek matang dengan ratusan kunci terjemahan merentasi 10 atau 20 bahasa, anda membazir token pada rentetan yang tidak berubah sejak larian terakhir dan mendapat output yang sama sebagai ganjaran.

Terjemahan delta menyelesaikan masalah ini. Daripada menghantar fail penuh, Tindakan membandingkan fail sumber semasa anda dengan garis dasar yang disimpan, mengenal pasti hanya kunci yang ditambah atau diubah, dan menghantar hanya itu ke API. Output untuk kunci yang tidak berubah diambil dari fail terjemahan sedia ada. Penggunaan token menurun untuk menyesuaikan dengan kerja sebenar yang dilakukan.

Bagaimana garis dasar berfungsi

Apabila mod delta dijalankan buat kali pertama, atau apabila anda memaksa penyegaran penuh, Tindakan menterjemah fail sumber lengkap dan menyimpan representasi JSON rata sebagai fail garis dasar dalam repositori anda. Pada larian berikutnya, Tindakan memuatkan garis dasar itu, membandingkannya dengan fail sumber semasa, dan membina muatan yang mengandungi hanya kunci yang berubah.

Untuk fail lokal JSON, garis dasar disimpan sebagai .polylingo-baseline.json dalam direktori mesej anda. Untuk fail lokal YAML, ia adalah .polylingo-yaml-baseline.json dalam direktori lokal anda. Untuk fail lang PHP Laravel, ia adalah .polylingo-laravel-php-baseline.json dalam direktori lang anda.

Garis dasar dikomit bersama fail terjemahan anda supaya ia bergerak bersama repositori. Mana-mana pembangun yang mengklon repo mendapat garis dasar yang sama yang digunakan oleh saluran.

Apa yang dikira sebagai perubahan

Perbezaan beroperasi pada representasi kunci rata fail sumber anda. Struktur bersarang diratakan kepada kunci notasi titik sebelum perbandingan:

{
  "nav.home": "Laman Utama",
  "nav.about": "Tentang kami",
  "hero.title": "Selamat datang ke platform kami",
  "hero.cta": "Mulakan"
}

Satu kunci dimasukkan dalam muatan delta jika:

  • Ia wujud dalam fail sumber semasa tetapi tidak dalam garis dasar (kunci baru)
  • Ia wujud dalam kedua-duanya tetapi nilainya telah berubah (kunci diubah) Kunci yang wujud dalam garis dasar tetapi tidak dalam fail sumber semasa (kunci dipadam) dikeluarkan secara automatik dari fail output terjemahan. Kunci yang sama dalam kedua-duanya diabaikan sepenuhnya dan terjemahan sedia ada dibiarkan.

Bagaimana ini kelihatan dalam praktik

Katakan anda mempunyai projek Next.js dengan 200 kunci terjemahan dalam messages/en.json, sudah diterjemah ke dalam 12 bahasa. Seorang pembangun mengemas kini salinan bahagian hero dan menambah dua kunci baru untuk pengumuman ciri. Itu adalah 4 kunci yang berubah daripada 200.

Tanpa mod delta, saluran menghantar semua 200 kunci didarabkan dengan 12 bahasa pada setiap push. Dengan mod delta ia menghantar 4 kunci. Penggunaan token untuk larian itu adalah kira-kira 2% daripada kos terjemahan penuh. Saluran juga lebih pantas kerana kurang yang perlu dihantar dan kurang menunggu.

Sepanjang sebulan pembangunan biasa, penjimatan terkumpul dengan ketara. Kebanyakan push menyentuh beberapa rentetan sahaja. Penterjemahan semula penuh hanya berlaku apabila anda menambah bahasa baru atau secara eksplisit menetapkan semula garis dasar.

Tiga PolyLingo GitHub Actions

Mod delta tersedia dalam ketiga-tiga Tindakan terjemahan PolyLingo. Setiap satu dibina untuk jenis kandungan dan struktur projek tertentu.

translateAction — JSON dan Markdown

Tindakan asal. Mengendalikan fail lokal JSON rata dalam gaya next-intl dan i18next, dengan laluan dokumentasi Markdown pilihan melalui API kerja async untuk fail yang lebih besar.

- 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"

Garis dasar delta: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Lihat di Marketplace

translate-action-yaml — Fail lokal YAML

Untuk projek yang menggunakan fail lokal YAML bersarang: Rails i18n, Vue i18n, dan mana-mana rangka kerja lain yang menggunakan format YAML. Tindakan mengendalikan konvensyen Rails untuk kunci lokal akar secara automatik — en.yml mempunyai kunci akar en:, dan setiap fail output mendapat kunci lokal sasaran yang betul (fr:, de: dan lain-lain).

Oleh kerana API PolyLingo berfungsi dengan JSON secara asli, Tindakan meratakan YAML bersarang kepada JSON notasi titik sebelum menghantar, menterjemah, kemudian membina semula struktur bersarang dan menulis output YAML yang sah. Satu caveat v1 yang perlu diketahui: kunci yang mengandungi titik secara semula jadi tidak disokong, kerana ia bertentangan dengan perataan notasi titik.

- 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

Garis dasar delta: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Lihat di Marketplace

translate-action-laravel — Fail lang Laravel

Untuk projek Laravel yang menggunakan sama ada fail terjemahan JSON (lang/en.json, menyokong kedua-dua struktur bersarang dan rata dalam gaya Laravel 9+) atau fail lang array PHP (lang/en/*.php). Tindakan mengesan format yang digunakan projek anda secara automatik melalui php_format: auto — ia memeriksa lang/en.json terlebih dahulu dan beralih ke fail array PHP jika tidak dijumpai.

Untuk fail PHP ia menjalankan CLI PHP untuk membaca fail sumber dan menyusun output terjemahan kembali kepada sintaks array PHP yang sah dalam JavaScript, tanpa kebergantungan tambahan. Runner ubuntu-latest yang dihoskan GitHub termasuk PHP 8.x secara lalai jadi tiada langkah persediaan tambahan diperlukan. PHP 7.4 atau lebih baru diperlukan.

Satu caveat v1: kunci yang mengandungi titik tidak disokong dalam mod PHP kerana strategi perataan notasi titik.

- 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

Garis dasar delta: lang/.polylingo-laravel-json-baseline.json atau lang/.polylingo-laravel-php-baseline.json bergantung pada format.

github.com/UsePolyLingo/translate-action-laravel — Lihat di Marketplace

Mod PR vs mod commit

Ketiga-tiga Tindakan menyokong dua mod output.

Mod commit (commit: true) menulis fail terjemahan dan mengkomitnya terus ke cawangan semasa. Persediaan mudah, sesuai untuk pasukan yang menganggap terjemahan sebagai proses automatik yang tidak memerlukan semakan.

Mod PR (open_pr: true) mencipta cawangan baru (polylingo/yaml-<sha>, polylingo/laravel-<sha> dan lain-lain), menulis fail terjemahan di sana, dan membuka permintaan tarik terhadap cawangan asas anda. Lebih baik untuk pasukan yang mahukan langkah semakan manusia sebelum kandungan terjemahan digabungkan, atau untuk projek di mana kualiti terjemahan memberi kesan langsung kepada pengalaman pengguna.

Apabila kedua-duanya ditetapkan, mod PR menang.

Mod PR memerlukan pull-requests: write dalam kebenaran aliran kerja anda:

permissions:
  contents: write
  pull-requests: write

Memaksa penyegaran penuh

Mod delta membandingkan dengan garis dasar yang disimpan. Jika anda mahu menterjemah semula semuanya tanpa mengira apa yang ditunjukkan oleh garis dasar, tetapkan delta: false. Ini juga mengemas kini garis dasar untuk sepadan dengan fail sumber semasa, jadi larian delta berikutnya bermula dari keadaan baru.

Penyegaran penuh berguna apabila anda menambah bahasa sasaran baru, apabila anda mahu mengambil peningkatan kualiti terjemahan dalam versi model baru, atau apabila garis dasar telah menyimpang dari realiti atas sebab apa pun.

- 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  # penyegaran penuh, mengemas kini garis dasar
    commit: true

Output untuk langkah hiliran

Ketiga-tiga Tindakan mendedahkan output yang sama supaya anda boleh menggunakannya dalam langkah aliran kerja berikutnya:

- 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: Log statistik terjemahan
  run: |
    echo "Bahasa diterjemah: ${{ steps.translate.outputs.locales_translated }}"
    echo "Fail berubah: ${{ steps.translate.outputs.files_changed }}"
    echo "Token digunakan: ${{ steps.translate.outputs.tokens_used }}"

Setiap larian juga menulis jadual ringkasan ke ringkasan langkah GitHub Actions supaya anda boleh melihat penggunaan token dan hasil terjemahan tanpa perlu menyemak log.

Memulakan

Ketiga-tiga Tindakan tersedia di GitHub Marketplace. Anda memerlukan kunci API PolyLingo, tersedia secara percuma di usepolylingo.com. Tahap percuma termasuk 50,000 token sebulan. Dengan mod delta diaktifkan, kebanyakan projek akan kekal dalam had itu pada push pembangunan rutin.

Tambah kunci API anda sebagai rahsia repositori (POLYLINGO_API_KEY) dan masukkan Tindakan yang relevan ke dalam aliran kerja anda. Larian pertama melakukan terjemahan penuh dan menetapkan garis dasar. Setiap larian selepas itu hanya menterjemah apa yang berubah.

Anda tidak perlu menterjemah semuanya semula: bagaimana terjemahan delta berfungsi dalam CI | PolyLingo