Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. JavaScript

Menerjemahkan Aplikasi Stimulus dengan I18Next

by
Difficulty:IntermediateLength:LongLanguages:

Indonesian (Bahasa Indonesia) translation by Imam Firmansyah (you can also view the original English article)

Dalam artikel saya sebelumnya, saya membahas Stimulus — sebuah framework JavaScript sederhana yang dibuat oleh Basecamp. Hari ini saya akan berbicara tentang internasionalisasi aplikasi Stimulus, karena framework tidak menyediakan tools apapun I18n out of the box.  Internasionalisasi adalah langkah penting, terutama ketika aplikasi Anda digunakan oleh orang-orang dari seluruh dunia, jadi pemahaman dasar tentang cara menjalankannya mungkin menjadi lebih mudah.

Tentu saja, hal itu bergantung kepada anda untuk memutuskan solusi internasionalisasi seperti apa yang akan diterapkan, baik itu jQuery.I18nPolyglot, ataupun yang lainnya. Pada tutorial ini, saya akan menunjukan kepada anda sebuah framework I18n yang populer yang bernama I18next yang memiliki banyak fitur keren dan menyediakan banyak plugin third-party tambahan untuk menyederhanakian proses pengembangan lebih jauh.  Dengan semua fitur ini, I18next bukanlah tool yang rumit, dan Anda tidak perlu mempelajari banyak dokumentasi untuk memulai menggunakannya.

Dalam artikel ini, Anda akan belajar cara mengaktifkan dukungan I18n dalam aplikasi Stimulus dengan bantuan library I18next. Khususnya, kita akan berbicara tentang:

  • Konfigurasi I18next
  • penerjemahkan file and memuatnya secara asynchronous
  • melakukan terjemahan dan menerjemahkan seluruh halaman sekaligus
  • bekerja dengan informasi jamak dan bermacam
  • switching antara lokal dan mempertahankan lokal yang dipilih dalam parameter GET
  • pengaturan lokal berdasarkan preferensi user

Source code tutorial tersedia di GitHub repositori.

Membangun Aplikasi Stimulus

Untuk memulai, mari kita melakukan proses clone pada Stimulus Starter project dan pasang semua dependensi menggunakan Yarn package manager:

Kita akan membangun aplikasi web sederhana yang memuat informasi tentang user terdaftar. Untuk setiap user, kita akan menampilkan informasi loginnya dan sejumlah foto yang telah dia unggah sejauh ini (tidak peduli jenis apa foto-foto ini).

Begitu juga, kita akan menyajikan switcher bahasa di bagian atas halaman. Saat sebuah bahasa dipilih, interface harus diterjemahkan segera tanpa memuat ulang halaman. Selain itu, URL harus ditambahkan dengan sebuah parameter GET ?locale yang menentukan lokasi mana yang saat ini sedang digunakan. Tentu saja, jika halaman dimuat dengan parameter ini sudah tersedia, bahasa yang sesuai harus diatur secara otomatis.

Okay, mari lanjutkan untuk merender user kita. Tambahkan baris kode berikut pada file public/index.html:

Disini, kita menggunakan controller users dan menyediakan URL untuk memuat user kita. Dalam aplikasi dunia yang sebenarnya, kita mungkin memiliki skrip dari sisi server yang mengambil user dari database dan merespons dengan JSON. Namun untuk tutorial ini, mari kita hanya tempatkan semua data yang diperlukan ke file public/api/users/index.json :

Sekarang buat file src/controllers/users_controller.js :

Segera setelah controller terhubung ke DOM, secara asinkron kita load user kita dengan bantuan metode loadUsers() :

Method ini mengirim fetch request ke URL yang diberikan, kemudian menerima respons, dan terakhir merender user:

renderUsers(), pada saatnya mem-parsing JSON, membangun string baru dengan semua konten, dan terakhir menampilkan konten ini pada halaman (this.element akan mengembalikan node DOM yang sebenarnya yang terhubung ke controller, yang merupakan div pada kasus kita).

I18next

Sekarang kita akan melanjutkan untuk mengintegrasikan I18next ke dalam aplikasi kita. Tambahkan dua library ke proyek kita: I18next dan sebuah plugin untuk mengaktifkan asynchronous loading dari file terjemahan dari back end:

Kita akan menyimpan semua hal yang berkaitan dengan i18 di file src/i18n/config.js yang terpisah, jadi sekarang buat:

Jalankan langkah dari awal sampai akhir untuk memahami apa yang terjadi disini:

  • use(I18nXHR) mengizinkan plugin i18next-xhr-backend.
  • fallbackLng menentukan useran bahasa Inggris sebagai fallback language.
  • whitelist hanya menetapkan izin untuk bahasa Inggris dan Rusia. Tentu saja, Anda dapat memilih bahasa lain.
  • preload menginstruksikan file terjemahan untuk dimuat dari server, daripada memuatnya ketika bahasa yang bersangkutan dipilih.
  • ns berarti "namespace" dan menerima string atau array. Dalam contoh ini kita hanya memiliki satu namespace, tetapi untuk aplikasi yang lebih besar Anda dapat mengenalkan namespaces yang lain, seperti admincartprofile, etc.  Untuk setiap namespace, a file terjemahan terpisah harus dibuat.
  • defaultNS menetapkan users sebagai default namespace.
  • fallbackNS menonaktifkan namespace fallback.
  • debug memungkinkan informasi debug ditampilkan di konsol browser. Khususnya, mengenai file terjemahan mana yang dimuat, bahasa mana yang dipilih, dll. Anda mungkin ingin menonaktifkan pengaturan ini sebelum menerapkan aplikasi ke produksi.
  • backend menyediakan konfigurasi untuk plugin I18nXHR plugin dan menentukan dari mana terjemahan dimuat. Perhatikan bahwa path harus berisi judul lokal, sedangkan file harus dinamai sesuai namespace dan memiliki ekstensi .json.
  • function(err, t) adalah callback untuk dijalankan ketika I18next sudah siap (atau ketika error terjadi).

Selanjutnya, mari kita buat file terjemahan. Terjemahan untuk bahasa Rusia harus ditempatkan ke dalam file public/i18n/ru/users.json:

login disini adalah kunci penerjemahan, sedangkan Логин adalah nilai yang ditampilkan.

Terjemahan bahasa Inggris, pada bagiannya harus dijalankan lewat file public/i18n/en/users.json:

Untuk memastikan bahwa I18next berfungsi, Anda dapat menambahkan baris kode berikut ke callback di dalam file i18n/config.js:

Disini kita menggunakan metode yang disebut t yang berarti "translate". Metode ini menerima translation key dan mengembalikan nilai yang sesuai.

Namun, kita mungkin memiliki banyak bagian dari UI yang perlu diterjemahkan, dan menjalankannya dengan memanfaatkan metode t akan sangat membosankan. Sebaliknya, saya sarankan Anda menggunakan plugin lain yang disebut loc-i18next yang memungkinkan Anda menerjemahkan beberapa elemen sekaligus.

Menerjemahkan dengan satu kali proses

Install plugin loc-i18next:

Import diatas file src/i18n/config.js:

Sekarang berikan konfigurasi untuk plugin itu sendiri:

Ada beberapa hal yang perlu diperhatikan di sini:

  • locI18next.init(i18n) membuat instance baru dari plugin berdasarkan contoh I18next yang telah didefinisikan sebelumnya.
  • selectorAttr menentukan atribut mana yang digunakan untuk mendeteksi elemen yang membutuhkan lokalisasi. Pada dasarnya, loc-i18next akan mencari elemen-elemen tersebut dan menggunakan nilai dari atribut data-i18n sebagai translation key.
  • optionsAttr menentukan atribut mana yang berisi opsi terjemahan tambahan.
  • useOptionsAttr menginstruksikan plugin untuk menggunakan opsi tambahan.

User kita dimuat secara asinkron, jadi kita harus menunggu hingga operasi ini selesai dan hanya melakukan lokalisasi setelah itu. Untuk saat ini, mari kita atur timer yang harus menunggu selama dua detik sebelum memanggil metode localize() tentunya hal itu adalah siasat sementara.

Kode metode localize() itu sendiri adalah:

Seperti yang Anda lihat, kita hanya perlu mengirimkan selector ke plugin loc-i18next. Semua elemen di dalam (yang memiliki kumpulan atribut data-i18n) akan dilokalkan secara otomatis.

Sekarang, ubah metode renderUsers. Untuk saat ini, mari kita hanya menerjemahkan kata "Login":

Bagus! Muat ulang halaman, tunggu selama dua detik, dan pastikan bahwa kata "Masuk" muncul untuk setiap user.

Kata Jamak dan Jenis Kelamin

Kita telah melokalkan bagian dari interface, dengan sangat keren. Namun, setiap user memiliki dua field lagi: jumlah foto yang diunggah dan jenis kelamin.  Karena kita tidak dapat memprediksi berapa banyak foto yang akan dimiliki setiap user, kata "foto" harus pluralized dengan benar berdasarkan jumlah yang diberikan.  Untuk melakukan ini, kita akan membutuhkan atribut data-i18n-options yang dikonfigurasi sebelumnya. Untuk memberikan hitungan, data-i18n-options harus ditetapkan dengan objek berikut: { "count": YOUR_COUNT }.

Informasi jenis kelamin harus dipertimbangkan juga. Kata "upload" dalam bahasa Inggris dapat diterapkan baik untuk pria maupun wanita, tetapi dalam bahasa Rusia itu menjadi "загрузил" atau "загрузила", jadi kita memerlukan data-i18n-options lagi, yang memiliki { "context": "GENDER" } sebagai nilai. Perhatikan, bahwa Anda dapat menggunakan konteks ini untuk mencapai tugas lain, tidak hanya untuk memberikan informasi gender.

Sekarang update terjemahan bahasa Inggris:

Nothing kompleks di sini. Karena untuk bahasa Inggris kita tidak peduli dengan informasi gender (yang merupakan konteksnya), translation key uploaded secara sederhana. Untuk menyediakan terjemahan yang benar-benar terstruktur, kkitami menggunakan photos dan key photos_plural. Bagian {{count}} adalah interpolasi dan akan diganti dengan angka yang sebenarnya.

Adapun bahasa Rusia, akan lebih kompleks:

Pertama-tama, perhatikan bahwa kita memiliki key uploaded_male dan uploaded_female untuk dua konteks yang memungkinkan. Selanjutnya, aturan-aturan pluralisasi juga lebih kompleks dalam bahasa Rusia daripada dalam bahasa Inggris, jadi kita harus menyediakan tidak dua, tetapi tiga kemungkinan frasa.  I18next mendukung banyak bahasa yang out of the box, dan ini adalah sebagian kecil fasilitas yang dapat membantu Anda memahami key pluralisasi mana yang harus ditentukan untuk bahasa tertentu.

Beralih Bahasa

Kita telah selesai menerjemahkan aplikasi kita, tetapi user harus dapat melakukan switch antar-lokal. Oleh karena itu, tambahkan komponen "language switcher" baru ke file public/index.html:

Buat controller yang sesuai di dalam file src/controllers/languages_controller.js:

Di sini kita menggunakan callback initialize() untuk menampilkan daftar bahasa yang didukung. Setiap li memiliki atribut data-action attribute yang menentukan metode apa (switchLanguage, dalam hal ini) yang harus dipicu ketika elemen diklik.

Sekarang tambahkan metode switchLanguage():

Cukup mengambil target dari event dan mengambil nilai dari atribut data-lang.

Saya juga ingin menambahkan getter dan setter untuk atribut currentLang:

Untuk getter sangat sederhana — kita mengambil nilai dari bahasa yang digunakan saat ini dan mengembalikannya.

Setter lebih kompleks. Pertama-tama, kita menggunakan method changeLanguage jika bahasa yang diatur saat ini tidak sama dengan yang dipilih.  Begitu juga, kita menyimpan lokal terpilih yang baru di bawah atribut data-current-lang (yang diakses di getter), melokalkan tubuh halaman HTML menggunakan plugin loc-i18next, dan terakhir menyoroti lokal yang sedang digunakan.

Mari kode highlightCurrentLang():

sini kita mengulangi lebih dari satu array switcher lokal dan membandingkan nilai-nilai atribut data-lang mereka dengan nilai dari lokal yang digunakan saat ini. Jika nilai cocok, switcher ditugaskan dengan current CSS class, jika tidak class ini dihapus.

Untuk membuat konstruksi this.switcherTargets bekerja, kita perlu menentukan target Stimulus dengan cara berikut:

Begitu juga, tambahkan atribut data-target dengan nilai switcheruntuk lis:

Hal lain yang penting untuk dipertimbangkan adalah file terjemahan mungkin memerlukan beberapa waktu untuk memuat, dan kita harus menunggu operasi ini selesai sebelum mengizinkan lokal untuk diaktifkan. Karena itu, mari kita manfaatkan loaded callback:

Terakhir, jangan lupa untuk menghapus setTimeout dari metode loadUsers():

Mempertahankan Bahasa pada URL

Setelah lokal diaktifkan, saya ingin menambahkan parameter GET ?lang GET parameter ke URL yang berisi kode bahasa yang dipilih. Menambahkan parameter GET tanpa memuat ulang halaman dapat dengan mudah dilakukan dengan bantuan History API:

Mendeteksi Bahasa

Hal terakhir yang akan kita terapkan saat ini adalah kemampuan untuk mengatur lokal berdasarkan preferensi pengguna. Sebuah plugin bernama LanguageDetector dapat membantu kita menyelesaikan tugas ini. Tambahkan paket baru Yarn:

Import LanguageDetector di dalam file i18n/config.js:

Sekarang atur konfigurasi:

Pilihan order mendaftarkan semua teknik (diurutkan berdasarkan kepentingannya) yang harus dicoba oleh plugin untuk "guess" lokal yang diinginkan:

  • querystring berarti memeriksa parameter GET yang berisi kode lokal.
  • lookupQuerystring mengatur nama parameter GET yang akan digunakan, yang mana parameter lang dalam kasus kita.
  • navigator berarti mendapatkan data lokal dari permintaan pengguna.
  • htmlTag melibatkan pengambilan lokal yang diutamakan dari atribut lang dari tag html.

Kesimpulan

Dalam artikel ini, kita telah melihat pada solusi populer I18next untuk menerjemahkan aplikasi JavaScript dengan mudah. Anda telah belajar bagaimana mengintegrasikan I18next dengan framework Stimulus, mengkonfigurasinya, dan memuat file terjemahan dengan cara asynchronous. Begitu juga, telah anda lihat bagaimana cara switch antar-lokal dan mengatur bahasa default berdasarkan preferensi user.

I18next memiliki beberapa opsi konfigurasi tambahan dan banyak plugins, plugin, jadi pastikan untuk menelusuri dokumentasi resminya untuk mempelajari lebih lanjut. Perhatikan juga bahwa Stimulus tidak memaksa Anda untuk menggunakan solusi lokalisasi tertentu, jadi Anda juga dapat mencoba menggunakan sesuatu seperti jQuery.I18n atau Polyglot.

Itu saja untuk hari ini! Terima kasih sudah membaca, dan sampai jummpa di waktu berikutnya.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.