← 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 menerjemahkan semuanya ulang: bagaimana terjemahan delta bekerja di CI

By Robert M

Anda tidak perlu menerjemahkan ulang semuanya: bagaimana terjemahan delta bekerja di CI

Setelah Anda menghubungkan terjemahan otomatis ke pipeline CI Anda, pertanyaan alami muncul dengan cepat: apakah ini menerjemahkan ulang seluruh file lokal setiap kali seseorang melakukan push perubahan?

Tanpa mode delta, ya. Setiap push yang menyentuh file lokal sumber Anda mengirimkan seluruh file ke API, setiap kunci, setiap string, apakah itu berubah atau tidak. Untuk proyek kecil di awal, itu tidak masalah. Untuk proyek matang dengan ratusan kunci terjemahan di 10 atau 20 bahasa, Anda membakar token pada string yang tidak berubah sejak run terakhir dan mendapatkan output identik sebagai imbalannya.

Terjemahan delta menyelesaikan ini. Alih-alih mengirim file penuh, Action membandingkan file sumber Anda saat ini dengan baseline yang disimpan, mengidentifikasi hanya kunci yang ditambahkan atau dimodifikasi, dan mengirim hanya itu ke API. Output untuk kunci yang tidak berubah diambil dari file terjemahan yang sudah ada. Penggunaan token turun sesuai dengan pekerjaan yang sebenarnya dilakukan.

Bagaimana baseline bekerja

Ketika mode delta berjalan untuk pertama kali, atau ketika Anda memaksa refresh penuh, Action menerjemahkan file sumber lengkap dan menyimpan representasi JSON datar sebagai file baseline di repositori Anda. Pada run berikutnya, Action memuat baseline itu, membandingkannya dengan file sumber saat ini, dan membangun payload yang hanya berisi kunci yang berubah.

Untuk file lokal JSON, baseline disimpan sebagai .polylingo-baseline.json di direktori pesan Anda. Untuk file lokal YAML, disimpan sebagai .polylingo-yaml-baseline.json di direktori lokal Anda. Untuk file lang PHP Laravel, disimpan sebagai .polylingo-laravel-php-baseline.json di direktori lang Anda.

Baseline dikomit bersama file terjemahan Anda sehingga ikut bersama repositori. Setiap pengembang yang mengkloning repo mendapatkan baseline yang sama yang digunakan pipeline.

Apa yang dihitung sebagai perubahan

Diff beroperasi pada representasi kunci datar dari file sumber Anda. Struktur bersarang diratakan ke kunci notasi titik sebelum perbandingan:

{
  "nav.home": "Beranda",
  "nav.about": "Tentang kami",
  "hero.title": "Selamat datang di platform kami",
  "hero.cta": "Mulai"
}

Sebuah kunci disertakan dalam payload delta jika:

  • Ada di file sumber saat ini tapi tidak di baseline (kunci baru)
  • Ada di keduanya tapi nilainya berubah (kunci dimodifikasi) Kunci yang ada di baseline tapi tidak di file sumber saat ini (kunci dihapus) secara otomatis dihapus dari file output terjemahan. Kunci yang identik di keduanya dilewati sepenuhnya dan terjemahan yang ada dibiarkan.

Bagaimana ini terlihat dalam praktik

Misalkan Anda memiliki proyek Next.js dengan 200 kunci terjemahan di messages/en.json, sudah diterjemahkan ke 12 bahasa. Seorang pengembang memperbarui salinan bagian hero dan menambahkan dua kunci baru untuk pengumuman fitur. Itu 4 kunci yang berubah dari 200.

Tanpa mode delta, pipeline mengirim semua 200 kunci dikalikan 12 bahasa setiap push. Dengan mode delta, hanya mengirim 4 kunci. Penggunaan token untuk run itu sekitar 2% dari biaya terjemahan penuh. Pipeline juga lebih cepat karena lebih sedikit yang dikirim dan lebih sedikit yang ditunggu.

Selama sebulan pengembangan rutin, penghematan ini bertambah signifikan. Sebagian besar push hanya menyentuh beberapa string. Retranslasi penuh hanya terjadi saat Anda menambahkan bahasa baru atau secara eksplisit mereset baseline.

Tiga PolyLingo GitHub Actions

Mode delta tersedia di ketiga Actions terjemahan PolyLingo. Masing-masing dibuat untuk tipe konten dan struktur proyek tertentu.

translateAction — JSON dan Markdown

Action asli. Menangani file lokal JSON datar dalam gaya next-intl dan i18next, dengan opsi dokumentasi Markdown melalui API pekerjaan async untuk file 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"

Baseline delta: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Lihat di Marketplace

translate-action-yaml — File lokal YAML

Untuk proyek yang menggunakan file lokal YAML bersarang: Rails i18n, Vue i18n, dan framework lain yang menggunakan format YAML. Action menangani konvensi Rails dengan kunci root lokal secara otomatis — en.yml memiliki kunci root en:, dan setiap file output mendapatkan kunci lokal target yang benar (fr:, de: dll).

Karena API PolyLingo bekerja dengan JSON secara native, Action meratakan YAML bersarang ke JSON notasi titik sebelum mengirim, menerjemahkan, lalu membangun ulang struktur bersarang dan menulis output YAML yang valid. Satu catatan v1: kunci yang mengandung titik secara alami tidak didukung karena konflik 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

Baseline delta: config/locales/.polylingo-yaml-baseline.json

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

translate-action-laravel — File lang Laravel

Untuk proyek Laravel yang menggunakan file terjemahan JSON (lang/en.json, mendukung struktur bersarang dan datar dalam gaya Laravel 9+) atau file lang array PHP (lang/en/*.php). Action mendeteksi format yang digunakan proyek Anda melalui php_format: auto — memeriksa lang/en.json terlebih dahulu dan fallback ke file array PHP jika tidak ditemukan.

Untuk file PHP, Action menjalankan CLI PHP untuk membaca file sumber dan menyerialisasi output terjemahan kembali ke sintaks array PHP yang valid dalam JavaScript, tanpa dependensi tambahan. Runner ubuntu-latest yang dihosting GitHub sudah menyertakan PHP 8.x secara default sehingga tidak perlu setup tambahan. PHP 7.4 atau lebih baru diperlukan.

Satu catatan v1: kunci yang mengandung titik tidak didukung dalam mode PHP karena 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

Baseline delta: lang/.polylingo-laravel-json-baseline.json atau lang/.polylingo-laravel-php-baseline.json tergantung format.

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

Mode PR vs mode commit

Ketiga Actions mendukung dua mode output.

Mode Commit (commit: true) menulis file terjemahan dan mengkomitnya langsung ke cabang saat ini. Setup sederhana, cocok untuk tim yang menganggap terjemahan sebagai proses otomatis tanpa perlu review.

Mode PR (open_pr: true) membuat cabang baru (polylingo/yaml-<sha>, polylingo/laravel-<sha> dll), menulis file terjemahan di sana, dan membuka pull request ke cabang dasar Anda. Lebih baik untuk tim yang ingin ada langkah review manusia sebelum konten terjemahan digabung, atau untuk proyek di mana kualitas terjemahan langsung memengaruhi pengalaman pengguna.

Jika keduanya diatur, mode PR menang.

Mode PR membutuhkan pull-requests: write di izin workflow Anda:

permissions:
  contents: write
  pull-requests: write

Memaksa refresh penuh

Mode delta membandingkan dengan baseline yang disimpan. Jika Anda ingin menerjemahkan ulang semuanya tanpa mempedulikan apa yang ditunjukkan baseline, atur delta: false. Ini juga memperbarui baseline agar sesuai dengan file sumber saat ini, sehingga run delta berikutnya mulai dari status baru.

Refresh penuh berguna saat Anda menambahkan bahasa target baru, saat ingin mengambil peningkatan kualitas terjemahan di versi model baru, atau saat baseline menyimpang dari kenyataan karena alasan 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  # refresh penuh, memperbarui baseline
    commit: true

Output untuk langkah downstream

Ketiga Actions mengekspos output yang sama sehingga Anda dapat menggunakannya di langkah workflow 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 "Locales translated: ${{ steps.translate.outputs.locales_translated }}"
    echo "Files changed: ${{ steps.translate.outputs.files_changed }}"
    echo "Tokens used: ${{ steps.translate.outputs.tokens_used }}"

Setiap run juga menulis tabel ringkasan ke ringkasan langkah GitHub Actions sehingga Anda dapat melihat penggunaan token dan hasil terjemahan tanpa harus mencari di log.

Memulai

Ketiga Actions tersedia di GitHub Marketplace. Anda memerlukan kunci API PolyLingo, tersedia gratis di usepolylingo.com. Tier gratis mencakup 50.000 token per bulan. Dengan mode delta diaktifkan, sebagian besar proyek akan tetap dalam batas itu pada push pengembangan rutin.

Tambahkan kunci API Anda sebagai secret repositori (POLYLINGO_API_KEY) dan masukkan Action yang relevan ke workflow Anda. Run pertama melakukan terjemahan penuh dan menetapkan baseline. Setiap run setelahnya hanya menerjemahkan yang berubah.