Lewati ke isi

Terjemahkan pesan lengkap
dengan t-string Python

gettext-tstrings menghubungkan t-string Python 3.14+ ke katalog gettext standar dan perkakas Babel. Nilai dan pemformatan tetap di kode aplikasi; penerjemah bekerja dengan pesan lengkap dan placeholder {name} yang sederhana:

import gettext

from gettext_tstrings import Translator

_ = Translator(gettext.translation("messages", localedir="locales"))
name = "Ada"
print(_(t"Hello {name}"))  # with a Japanese catalog: こんにちは Ada

Katalog memuat Hello {name}. Sebuah terjemahan boleh memindahkan atau mengulang {name}. Bila ia menghilangkan, mengganti nama, atau mengubah pemformatan placeholder itu, validasi katalog melaporkan kesalahannya. Bila sebuah entri tak sah tetap sampai ke produksi, pustaka ini mencatat sebuah peringatan dan merender pesan sumbernya alih-alih membuat aplikasi crash.

Mulai tutorial lima menit Bandingkan alternatifnya

Alpha · Python 3.14+ · katalog PO/MO standar · tanpa dependensi runtime pihak ketiga

Situs ini mempraktikkan apa yang didokumentasikannya: setiap edisi bahasa — navigasi, label, dan laporan build yang sadar bentuk jamak — dirender dari katalog PO oleh gettext-tstrings itu sendiri.

Apakah ini untuk Anda?

Cocok hari ini bila aplikasi Anda berjalan di Python 3.14 atau lebih baru; Anda sudah memakai gettext dan Babel, atau ingin mengadopsi alur kerja PO/MO mereka; dan Anda menginginkan sintaks t-string dengan placeholder bernama yang diperiksa sebelum dirender.

Belum cocok bila Anda membutuhkan Python 3.13 atau lebih lama; Anda menuntut API Python yang stabil — ini sebuah alpha, dan spesifikasinya adalah bagian yang sudah mengendap; atau hampir seluruh teks Anda yang dapat diterjemahkan berada di bahasa templat alih-alih di sumber Python.

Sudah punya katalog? Katalog itu tetap bekerja. _("Hello {name}").format(name=name) dan tr(t"Hello {name}") menghasilkan msgid yang sama, sehingga terjemahan yang ada selamat melewati peralihannya — Migrasi menempuh keseluruhan perpindahannya.

Apa yang boleh dikatakan katalog

Sebuah terjemahan tidak dapat mengubah struktur pesan yang diterjemahkannya. Itulah keseluruhan janjinya, dan selebihnya situs ini mengikuti darinya. Sebuah terjemahan boleh mengurutkan ulang atau mengulang {name}, dan boleh menulis ulang setiap kata lain di sekelilingnya. Ia tidak boleh menghilangkan placeholder-nya, mengarang yang baru, menjangkau lewat placeholder itu ke dalam objek Anda, atau menambahkan pemformatan sendiri.

Pustaka ini memeriksanya saat masuk — ketika katalog dikompilasi — dan sekali lagi saat perenderan, dan itulah bedanya antara kekeliruan yang ditemukan di peninjauan dan kekeliruan yang ditemukan oleh seorang pengguna.

Baru mengenal gettext? Seluruh alur kerjanya dalam empat kalimat

gettext adalah cara standar perangkat lunak diterjemahkan, di Python dan jauh di luarnya. Kode Anda menandai pesan yang dapat diterjemahkan; sebuah ekstraktor mengumpulkannya ke dalam berkas templat (.pot); seorang penerjemah — biasanya bukan programmer — mengisi satu berkas katalog (.po) per bahasa, yang dikompilasi menjadi .mo biner yang dimuat aplikasi Anda saat runtime. Nama konvensional untuk fungsi penerjemah adalah _, sehingga _(t"Hello {name}") terbaca sebagai "terjemahkan pesan ini". Tutorial menempuh seluruh jalurnya — tandai, ekstrak, terjemahkan, kompilasi, jalankan — dalam sekitar lima menit.

Masalah yang dipecahkannya

Sebuah f-string sudah terinterpolasi pada saat pustaka mana pun melihatnya — f"Hello {name}" telah menjadi "Hello Ada", dan menerjemahkan penggalan-penggalan di sekeliling sebuah nilai merusak tata bahasa sebagian besar bahasa. Sebuah t-string (PEP 750) menjaga teks statis, nilai yang telah dievaluasi, ekspresi sumber, konversi, dan format spec tetap terpisah — tepat pemisahan yang dibutuhkan sebuah katalog pesan. Apa yang berubah karenanya, dibandingkan dengan %(name)s, .format(), dan $-string.

Namun tidak ada apa pun dalam gettext atau Babel yang menetapkan bagaimana sebuah t-string menjadi sebuah pesan. Pustaka ini mengambil pilihan itu, menuliskannya sebagai spesifikasi berversi, dan menyertakan suite konformans untuk memeriksanya.

Aturan desainnya

  • Menerjemahkan pesan secara utuh, tidak pernah penggalan kalimat.
  • Hanya menerima nama variabel sederhana seperti {name}.
  • Menjaga !r dan :.2f di bawah kendali aplikasi, di luar katalog.
  • Mengizinkan terjemahan mengurutkan ulang dan mengulang placeholder yang dikenal, sekaligus mencegahnya menjangkau atribut atau menambahkan pemformatan.
  • Menggunakan kembali berkas POT, PO, dan MO biasa, serta perkakas yang sudah membacanya.

Dan daftar penyandingnya, apa yang sengaja tidak disentuhnya: ia tidak melokalkan angka, mata uang, atau tanggal — format semua itu lebih dulu dengan Babel; ia tidak meng-escape keluaran yang dirender untuk HTML, shell, atau terminal; dan ia tidak dapat menilai apakah sebuah terjemahan benar, hanya apakah placeholder-nya utuh.

Instalasi

python -m pip install gettext-tstrings

Python 3.14 atau lebih baru. Rendering tidak memiliki dependensi — ia menggunakan gettext dari pustaka standar dan tidak yang lain.

Ekstraksi dan validasi katalog berjalan melalui Babel, jadi pasang extra itu di mana pun pybabel berjalan, yang biasanya lingkungan pengembangan atau CI dan bukan image produksi:

python -m pip install "gettext-tstrings[babel]"

Ke mana selanjutnya

Mulai di sini — tanpa mengandaikan pengalaman gettext:

  • Tutorial — dari direktori kosong ke terjemahan bahasa Jepang yang berjalan dalam lima langkah, setiap perintah ditampilkan dengan keluarannya.
  • Mengapa t-string — pesan yang sama ditulis empat cara, dan apa yang %(name)s, .format(), serta $-string masing-masing serahkan ke katalog.

Menggunakannya — referensi kerjanya:

  • Panduan — API runtime: titik masuk mana yang dipakai, bentuk jamak, bahasa per permintaan, string tertunda, dan apa yang terjadi ketika sebuah katalog salah.
  • Ekstraksi — referensi pybabel: konfigurasi, nama fungsi kustom, dan bagaimana perkakas yang sudah ada memvalidasi katalog ini secara cuma-cuma.
  • Dalam produksi — putaran itu sebagaimana dijalankan sebuah tim: siklus pembaruan, entri fuzzy, gerbang CI, platform penerjemahan, dan pengiriman.
  • Migrasi — mengadopsi ini di proyek yang sudah punya katalog, satu tempat pemanggilan pada satu waktu.
  • Untuk penerjemah — satu halaman untuk diserahkan kepada siapa pun yang menyunting berkas .po.

Memahaminya — dari sejarah hingga implementasi:

  • Latar belakang — mengapa pustaka ini ada: tiga puluh tahun gettext, dua PEP, dan diskusi stdlib yang ditutup tanpa jawaban.
  • Jebakan umum — apa yang benar-benar rusak ketika situs ini diterjemahkan ke tiga puluh lima bahasa, dan separuh mana yang dapat ditangkap sebuah perkakas.
  • Cara kerjanya — dari objek template PEP 750 hingga string yang dirender, dan cache yang membuat pemeriksaannya murah.

Referensi — kontraknya:

  • API — semua yang diekspor paket ini, dalam satu halaman.
  • Spesifikasi — konvensi t-string ↔ msgid sebagai kontrak yang stabil dan berversi, dengan suite konformans yang terbaca mesin.

Status
Versi paket 0.1.0a8
Stabilitas API alpha — API Python-nya masih mungkin berubah
Spesifikasi v1, dengan suite konformans
Python 3.14 dan yang lebih baru; diuji pada 3.14, 3.14t (free-threaded), dan 3.15
Babel 2.18 atau yang lebih baru, dan hanya di tempat pybabel dijalankan
Dependensi runtime tidak ada — gettext dari pustaka standar
Format katalog POT, PO, dan MO biasa
Perubahan CHANGELOG

Sebuah alpha. Kontraknya sengaja dibuat kecil dan spesifikasi adalah bagiannya yang stabil; API Python-nya masih mungkin bergerak. Sebelum rilis stabil, proyek ini membutuhkan fixture bahasa yang lebih luas, pelacakan performa berkelanjutan, tinjauan API dari orang-orang yang menggunakan gettext dan Babel secara serius, serta pengujian kompatibilitas di setiap rilis Python dan Babel yang didukung.

Issue dan pull request disambut baik — alpha justru saat antarmuka masih layak diperdebatkan.

Bergabung dengan komunitas