Alur kerja i18n Vue 3 untuk 500+ kunci tanpa kejutan di produksi

Apa yang salah saat mencapai 500+ kunci i18n

Setelah aplikasi Anda punya beberapa ratus string, hal pertama yang biasanya rusak bukanlah Vue I18n. Itu adalah konsistensi. Orang menambahkan kunci dengan gaya berbeda, menggandakan ide yang sama dengan nama lain, dan tak jelas lagi pesan mana yang aman dihapus.

Terjemahan yang hilang juga berhenti menjadi kejadian langka. Mereka muncul di jalur pengguna normal, terutama di layar yang jarang digunakan seperti pengaturan, status error, state kosong, dan notifikasi.

Saat terjemahan hilang, pengguna biasanya melihat salah satu dari tiga kegagalan: UI kosong (tombol tanpa label), kunci mentah (seperti checkout.pay_now), atau fallback aneh di mana sebagian halaman berganti bahasa. Tidak ada dari itu yang terasa seperti bug kecil. Mereka membuat aplikasi terlihat rusak.

Itulah mengapa alur kerja i18n untuk Vue 3 lebih penting daripada pustaka tertentu. Pustaka akan melakukan apa yang Anda minta. Pada skala besar, tim sering tidak sepakat tentang seperti apa definisi "selesai".

Contoh umum: seorang pengembang merilis flow "Invite teammate" baru dengan 40 string baru. File bahasa Inggris diperbarui, tapi file Prancis tidak. Di staging, semuanya terlihat baik karena penguji memakai bahasa Inggris. Di produksi, pengguna Prancis melihat campuran UI yang diterjemahkan dan tidak diterjemahkan, dan tim dukungan mendapat screenshot berisi kunci mentah.

Perbaikannya adalah mendefinisikan apa arti "selesai" untuk UI yang diterjemahkan. Tidak cukup hanya "string ditambahkan". Definisi selesai yang praktis biasanya mencakup: kunci mengikuti aturan penamaan, locales dibangun tanpa peringatan missing-key, plural dan variabel dirender dengan benar menggunakan data nyata, setidaknya satu locale non-default diperiksa, dan perubahan copy dilacak sehingga kunci lama tidak tertinggal.

Di 500+ kunci, Anda menang dengan memperlakukan lokalisasi seperti proses rilis, bukan edit file menit-menit terakhir.

Tetapkan beberapa aturan sebelum menambah lebih banyak string

Setelah beberapa ratus string, pekerjaan terjemahan bukan lagi bagian yang berantakan. Konsistensilah yang jadi masalah. Sekumpulan aturan kecil membuat alur kerja i18n Vue 3 Anda dapat diprediksi, meskipun banyak orang menyentuh copy setiap minggu.

Mulailah dengan memutuskan apa itu “konsep” dan menjaga satu sumber kebenaran untuk itu. Jika ide UI yang sama muncul di lima tempat (misalnya, “Save changes”), Anda ingin satu kunci, bukan lima variasi seperti save, saveChanges, save_update, dan saveBtn. Kunci duplikat berubah makna seiring waktu, dan pengguna merasakan ketidakkonsistenan itu.

Selanjutnya, tentukan di mana pemformatan berada. Tim sering membagi ini tanpa sengaja: beberapa pesan menyertakan tanda baca dan kapitalisasi, yang lain mengandalkan kode untuk menambahkannya. Pilih satu pendekatan dan patuhi.

Default praktis:

• Letakkan tata bahasa, tanda baca, dan pemformatan yang terlihat pengguna (seperti “(optional)”) di dalam pesan.
• Simpan pemformatan data murni di kode (tanggal, mata uang, satuan), lalu kirimkan hasilnya ke i18n.
• Gunakan placeholder untuk nama dan jumlah, bukan konkatenasi string.
• Perlakukan HTML dalam pesan sebagai kasus khusus dengan aturan yang jelas (diizinkan atau tidak).

Lalu tentukan kepemilikan. Putuskan siapa yang boleh menambahkan kunci baru, siapa yang meninjau copy bahasa dasar, dan siapa yang menyetujui locale lain. Tanpa ini, string ditambahkan tergesa-gesa dan tidak pernah ditinjau.

Akhirnya, pilih dan dokumentasikan strategi fallback. Jika sebuah kunci hilang, apa yang harus dilihat pengguna: nama kunci, teks default-locale, atau pesan umum yang aman? Di produksi, banyak tim memilih fallback ke default locale plus logging, sehingga pengguna tak terblokir sementara Anda tetap mendapat sinyal bahwa ada yang salah.

Jika Anda membangun aplikasi Vue 3 dengan generator seperti AppMaster (Vue3 web UI plus real backend code), aturan ini tetap berlaku. Perlakukan terjemahan seperti konten produk, bukan “cuma teks dev”, dan Anda akan menghindari sebagian besar kejutan mendadak.

Konvensi penamaan kunci yang tetap dapat dibaca

Setelah beberapa ratus string, konsistensi adalah pengali terbesar. Pilih satu gaya kunci (kebanyakan tim memakai dot paths seperti billing.invoice.title) dan jadikan itu aturan. Mencampur titik, slash, snake_case, dan kapitalisasi acak membuat pencarian dan review jadi lambat.

Gunakan kunci stabil yang bertahan saat copy berubah. Kunci seperti "Please enter your email" akan rusak saat marketing mengubah kalimat. Lebih baik pakai nama yang berbasis tujuan seperti auth.email.required atau auth.email.invalid.

Kelompokkan kunci berdasarkan area produk atau permukaan UI terlebih dahulu, lalu berdasarkan tujuan. Pikirkan dalam bucket yang sudah ada di aplikasi Anda: auth, billing, settings, support, dashboard. Ini membuat file locale lebih mudah dipindai dan mengurangi duplikat ketika dua layar membutuhkan ide yang sama.

Di dalam setiap area, pertahankan pola kecil untuk bagian UI umum:

• Tombol: *.actions.save, *.actions.cancel
• Label: *.fields.email.label, *.fields.password.label
• Hint/teks bantuan: *.fields.email.hint
• Error/validasi: *.errors.required, *.errors.invalidFormat
• Notifikasi/toast: *.notices.saved, *.notices.failed

Pesan dinamis harus menyatakan apa yang berubah, bukan bagaimana. Namai pesan berdasarkan tujuan dan gunakan parameter untuk bagian yang variabel. Misalnya, billing.invoice.dueInDays dengan {days} lebih jelas daripada billing.invoice.dueIn3Days.

Contoh (cocok untuk alur kerja i18n Vue 3): orders.summary.itemsCount dengan {count} untuk jumlah, dan orders.summary.total dengan {amount} untuk uang. Saat seseorang melihat kunci di kode, mereka harus tahu tempat dan tujuannya, meskipun copy akhir berubah nanti.

Aturan plural dan pemformatan pesan tanpa kejutan

Teks plural rusak diam-diam ketika Anda menganggap setiap bahasa seperti Bahasa Inggris. Putuskan sejak awal kapan Anda akan menggunakan sintaks ICU dan kapan placeholder sederhana cukup.

Gunakan penggantian sederhana untuk label dan teks UI pendek yang tidak berubah berdasarkan jumlah (misalnya, "Welcome, {name}"). Beralihlah ke ICU untuk apa pun yang berbasis hitungan, karena itu menyimpan semua bentuk di satu tempat dan membuat aturan menjadi eksplisit.

{
  "notifications.count": "{count, plural, =0 {No notifications} one {# notification} other {# notifications}}"
}

Tulis pesan jumlah sehingga mudah diterjemahkan. Lebih suka kalimat penuh dan letakkan placeholder angka (#) dekat dengan kata benda. Hindari trik seperti menggunakan kembali kunci yang sama untuk "1 item" dan "2 items" di kode. Penerjemah perlu melihat pesan lengkap, bukan menebak bagaimana ia akan disambung.

Rencanakan untuk =0, one, dan other minimalnya, dan dokumentasikan apa yang Anda harapkan untuk 0. Beberapa produk ingin “0 items”, yang lain ingin “No items”. Pilih satu gaya dan patuhi agar UI terasa konsisten.

Juga perhatikan bahasa yang memiliki kategori plural lebih banyak dari yang Anda kira. Banyak bahasa tidak mengikuti pola “one vs many”. Jika Anda menambahkan locale baru nanti, pesan yang hanya punya one dan other bisa jadi salah secara tata bahasa meskipun bisa dirender.

Sebelum rilis, uji plural dengan hitungan nyata di UI, bukan hanya melihat JSON. Pemeriksaan cepat yang menangkap sebagian besar masalah adalah 0, 1, 2, 5, dan 21.

Jika Anda membangun aplikasi Vue3 web (misalnya, di dalam AppMaster), lakukan tes ini di layar tempat teks itu muncul. Masalah tata letak, teks terpotong, dan frasa canggung muncul di situ lebih dulu.

Mengorganisir file locale untuk pertumbuhan

Setelah beberapa ratus string, satu en.json besar jadi hambatan. Orang menyentuh file yang sama, konflik merge meningkat, dan Anda kehilangan jejak di mana copy berada. Struktur yang baik menjaga alur kerja i18n Vue 3 Anda stabil meski produk terus berubah.

Struktur yang disarankan

Untuk 2 sampai 5 locale, memecah berdasarkan fitur biasanya cukup. Jaga tata letak file yang sama di setiap locale supaya menambah kunci menjadi edit yang dapat diprediksi.

• locales/en/common.json, locales/en/auth.json, locales/en/billing.json
• locales/es/common.json, locales/es/auth.json, locales/es/billing.json
• locales/index.ts (memuat dan menggabungkan messages)

Untuk 20+ locale, skala ide yang sama tapi buat lebih sulit untuk menyimpang. Perlakukan Inggris sebagai sumber kebenaran dan pastikan setiap locale mencerminkan struktur folder dan nama file yang sama. Jika domain baru muncul (misalnya, notifications), ia harus ada untuk setiap locale meskipun teksnya bersifat sementara.

Memecah berdasarkan domain mengurangi konflik merge karena dua orang dapat menambahkan string ke file berbeda tanpa saling bertumpuk. Domain harus sesuai dengan bagaimana aplikasi Anda dibangun: common, navigation, errors, settings, reports, plus folder fitur untuk area yang lebih besar.

Menjaga konsistensi kunci

Dalam setiap file, pertahankan bentuk kunci yang sama di seluruh locale: nesting sama, nama kunci sama, hanya teks yang berbeda. Hindari kunci “kreatif” per bahasa, meskipun sebuah frasa sulit diterjemahkan. Jika Inggris perlu billing.invoice.status.paid, setiap locale harus punya kunci yang persis sama.

Sentralisasikan hanya apa yang benar-benar berulang di mana-mana: label tombol, error validasi generik, dan navigasi global. Simpan copy spesifik fitur dekat dengan domain fiturnya, meski terasa bisa dipakai ulang. “Save” masuk di common. “Save payment method” masuk di billing.

Konten panjang

Teks bantuan panjang, langkah onboarding, dan template email cepat berantakan. Beberapa aturan membantu:

• Letakkan string panjang di domain tersendiri (misalnya, help atau onboarding) dan hindari nesting dalam-dalam.
• Lebih suka paragraf pendek daripada satu string besar, supaya penerjemah dapat bekerja dengan aman.
• Jika marketing atau support sering mengedit teks, simpan pesan itu di file khusus untuk mengurangi churn di tempat lain.
• Untuk email, simpan subject dan body terpisah dan jaga placeholder konsisten (nama, tanggal, jumlah).

Setup ini memudahkan review perubahan, menerjemahkan secara bertahap, dan menghindari gap mendadak tepat sebelum rilis.

Langkah demi langkah untuk menambah dan mengirimkan string

Alur kerja i18n Vue 3 yang stabil lebih soal kebiasaan ketimbang alat. Teks UI baru tidak boleh sampai produksi tanpa kunci, pesan default, dan status terjemahan yang jelas.

Mulailah dengan menambahkan kunci ke base locale (seringkali en). Tulis teks default seperti copy nyata, bukan placeholder. Ini memberi produk dan QA sesuatu yang bisa ditinjau, dan mencegah "string misterius" nanti.

Saat menggunakan kunci di komponen, sertakan param dan logika plural sejak hari pertama supaya penerjemah melihat bentuk penuh pesan.

// simple param
$t('billing.invoiceDue', { date: formattedDate })

// plural
$t('files.selected', count, { count })

Jika terjemahan belum siap, jangan biarkan kunci hilang. Tambahkan terjemahan placeholder di locale lain atau tandai sebagai pending dengan cara yang konsisten (misalnya, beri awalan TODO: pada value). Yang penting aplikasi merender dengan prediktabel dan reviewer dapat melihat copy yang belum selesai.

Sebelum merge, jalankan pemeriksaan otomatis singkat. Buat mereka membosankan dan ketat: missing keys di seluruh locale, unused keys, ketidakcocokan placeholder (hilang {count}, {date}, atau kurung kurawal yang salah), bentuk plural yang tidak valid untuk bahasa yang didukung, dan override tidak sengaja.

Akhirnya, lakukan pemeriksaan UI singkat di setidaknya satu locale non-base. Pilih bahasa dengan kata-kata lebih panjang (seringnya Jerman atau Prancis) untuk menangkap overflow, tombol terpotong, dan baris yang canggung. Jika UI Vue 3 Anda digenerasi atau dipelihara bersama bagian produk lain (misalnya, aplikasi web Vue3 yang dibuat oleh AppMaster), langkah ini tetap penting karena tata letak berubah saat fitur berkembang.

Perlakukan langkah-langkah ini sebagai definisi selesai untuk fitur apa pun yang menambah teks.

Kesalahan umum yang terus diulang tim

Cara tercepat membuat lokalisasi merepotkan adalah memperlakukan kunci i18n seperti "cuma string." Setelah beberapa ratus kunci, kebiasaan kecil berubah menjadi bug produksi.

Kunci yang bergeser, bertabrakan, atau menipu

Typo dan perbedaan kapitalisasi adalah penyebab klasik teks hilang: checkout.title di satu tempat, Checkout.title di tempat lain. Terlihat baik di code review, lalu bahasa fallback diam-diam terkirim.

Masalah lain adalah menggunakan satu kunci untuk makna berbeda. “Open” bisa berarti “Open ticket” di layar support dan “Open now” di halaman toko. Jika Anda pakai satu kunci, salah satu layar akan salah di bahasa lain, dan penerjemah akan menebak.

Aturan sederhana membantu: satu kunci sama dengan satu makna. Jika makna berubah, buat kunci baru meski teks Inggrisnya sama.

Bug tata letak yang disebabkan oleh asumsi bentuk-string

Tim sering meng-hardcode tanda baca, spasi, atau potongan HTML ke dalam terjemahan. Itu berfungsi sampai sebuah bahasa butuh tanda baca berbeda, atau UI Anda meng-escape atau merender markup berbeda. Simpan keputusan markup di template, dan biarkan pesan fokus pada teks.

Mobile adalah tempat masalah bersembunyi. Label yang pas di Inggris bisa membungkus menjadi tiga baris di Jerman, atau meluap di Thai. Jika Anda hanya menguji satu ukuran layar, Anda akan melewatkannya.

Perhatikan pelanggar berulang: mengasumsikan susunan kata Inggris saat memasukkan variabel (nama, jumlah, tanggal), membangun pesan dengan menggabungkan potongan-potongan alih-alih satu pesan utuh, lupa menguji nilai panjang (nama produk, alamat, detail error), merilis dengan silent fallback aktif sehingga kunci hilang terlihat “baik” dalam bahasa Inggris, dan copy-paste kunci sambil hanya mengedit nilai bahasa Inggris.

Jika Anda ingin alur kerja i18n Vue 3 yang tenang di 500+ kunci, perlakukan kunci sebagai bagian dari API Anda: stabil, spesifik, dan diuji seperti hal lain.

Langkah QA yang menangkap terjemahan hilang lebih awal

Terjemahan hilang mudah terlewat karena aplikasi masih “berfungsi.” Hanya saja ia fallback ke kunci, locale yang salah, atau string kosong. Perlakukan cakupan terjemahan seperti tes: Anda ingin umpan balik cepat sebelum sesuatu sampai ke produksi.

Pemeriksaan otomatis (dijalankan di setiap PR)

Mulailah dengan pemeriksaan yang membuat build gagal, bukan peringatan yang tidak dibaca siapa pun.

• Pindai codebase untuk penggunaan $t('...') dan t('...'), lalu verifikasi setiap kunci yang dipakai ada di base locale.
• Bandingkan set kunci antar locale dan gagalkan jika ada locale yang kehilangan kunci (kecuali kunci itu ada di daftar pengecualian kecil yang ditinjau, seperti catatan legal khusus en).
• Tandai orphan keys yang ada di file locale tapi tak pernah dipakai.
• Validasi sintaks pesan (placeholder, blok ICU/plural). Satu pesan rusak dapat membuat halaman crash saat runtime.
• Perlakukan duplikat kunci atau kapitalisasi tidak konsisten sebagai error.

Jaga daftar pengecualian singkat dan dimiliki oleh tim, bukan "apa pun yang lolos CI."

Pemeriksaan runtime dan visual (staging)

Bahkan dengan CI, Anda tetap butuh jaring di staging karena jalur pengguna nyata memicu string yang Anda lupa dinamis.

Aktifkan logging missing-translation di staging dan sertakan konteks cukup untuk memperbaiki cepat: locale, route, nama komponen (jika tersedia), dan kunci yang hilang. Buat itu berisik. Jika mudah diabaikan, ia akan diabaikan.

Tambahkan pseudo-locale dan gunakan untuk pemeriksaan UI cepat. Satu pendekatan sederhana adalah mengubah setiap string (membuatnya lebih panjang dan menambah penanda) sehingga masalah tata letak langsung terlihat, misalnya: [!!! 𝗧𝗲𝘅𝘁 𝗲𝘅𝗽𝗮𝗻𝗱𝗲𝗱 !!!]. Ini menangkap tombol yang terpotong, header tabel rusak, dan spasi yang hilang sebelum Anda kirim.

Akhirnya, lakukan spot check pra-rilis pada flows bernilai tinggi di 2-3 locale: sign-in, checkout/payment, pengaturan inti, dan fitur baru yang Anda rilis. Di sinilah Anda menangkap bug "sudah diterjemahkan tapi placeholder salah".

Menangani bahasa baru dan perubahan copy berkelanjutan

Menambah bahasa baru jadi berantakan saat Anda memperlakukannya sebagai "pekerjaan copy" bukan rilis produk kecil. Cara termudah menjaga alur kerja i18n Vue 3 stabil adalah membuat aplikasi tetap build meski locale belum lengkap, sambil tetap membuat celah terlihat jelas sebelum pengguna melihatnya.

Saat menambah locale baru, mulai dengan menghasilkan bentuk file yang sama seperti source locale (sering en). Jangan terjemahkan dulu, struktur dulu.

• Buat folder/file locale baru dengan set kunci penuh yang disalin dari source.
• Tandai nilai sebagai placeholder TODO supaya string yang hilang terlihat di QA.
• Tambahkan locale ke language switcher hanya setelah hal dasar terpenuhi.
• Jalankan pemeriksaan layar demi layar untuk menangkap masalah tata letak (kata lebih panjang, wrapping).

Terjemahan sering datang terlambat, jadi putuskan sejak awal apa arti “parsial” untuk produk Anda. Jika fitur menghadap pelanggan, pertimbangkan feature flag agar fitur dan string-nya rilis bersama. Jika Anda harus merilis tanpa terjemahan penuh, lebih baik fallback jelas (misalnya Inggris) daripada label kosong, tetapi buat itu terdengar di staging.

Perubahan copy adalah tempat tim sering memecah kunci. Jika Anda mengubah kata-kata, pertahankan kunci stabil. Kunci harus mendeskripsikan tujuan, bukan kalimat tepat. Simpan penggantian nama kunci untuk saat makna berubah, dan bahkan saat itu, lakukan migrasi terkontrol.

Untuk menghindari "zombie strings", deprecate kunci dengan sengaja: tandai kunci sebagai deprecated dengan tanggal dan pengganti, pertahankan selama satu siklus rilis, lalu hapus hanya setelah Anda memastikan tidak ada referensi tersisa.

Simpan catatan terjemahan dekat dengan kunci. Jika format JSON Anda tidak bisa menampung komentar, simpan catatan di dokumen pendamping kecil atau file metadata bersebelahan (misalnya, "dipakai di layar sukses checkout"). Ini sangat membantu saat aplikasi web Vue 3 Anda digenerasi dari alat seperti AppMaster dan banyak orang menyentuh copy dan UI.

Contoh: mengirim fitur dengan 60 string baru

Suatu sprint, tim Anda merilis tiga hal sekaligus: halaman Settings baru, layar Billing, dan tiga template email (receipt, payment failed, trial ending). Itu sekitar 60 string baru, dan di sinilah i18n biasanya mulai berantakan.

Tim sepakat mengelompokkan kunci berdasarkan fitur, lalu berdasarkan permukaan. File baru dibuat untuk setiap fitur, dan kunci mengikuti pola yang sama: feature.area.element.

// settings
"settings.profile.title": "Profile",
"settings.security.mfa.enable": "Enable two-factor authentication",

// billing
"billing.plan.current": "Current plan",
"billing.invoice.count": "{count} invoice | {count} invoices",

// email
"email.receipt.subject": "Your receipt",
"email.payment_failed.cta": "Update payment method"

Sebelum pekerjaan terjemahan dimulai, string plural dites dengan nilai nyata, bukan tebakan. Untuk billing.invoice.count, QA memeriksa 0, 1, 2, dan 5 menggunakan data seed (atau toggle dev sederhana). Ini menangkap kasus canggung awal, seperti "0 invoice".

QA kemudian menjalankan flow fokus yang cenderung mengungkap kunci hilang: buka Settings dan Billing dan klik setiap tab sekali, trigger setiap template email di staging dengan akun tes, jalankan app dengan locale non-default aktif, dan gagalkan build jika ada peringatan missing-translation di log.

Di sprint ini, QA menemukan dua kunci hilang: satu label di layar Billing dan satu subject email. Tim memperbaikinya sebelum rilis.

Saat memutuskan apakah harus memblokir rilis atau mengizinkan fallback, mereka menggunakan aturan sederhana: layar yang menghadap pengguna dan email transaksional memblokir rilis; teks admin berisiko rendah bisa sementara fallback ke bahasa default, tapi hanya dengan tiket dan tenggat jelas.

Langkah selanjutnya dan daftar periksa rilis sederhana

Alur kerja i18n Vue 3 tetap stabil ketika Anda memperlakukan terjemahan seperti kode: tambahkan dengan cara yang sama setiap kali, uji, dan catat hasilnya.

Daftar periksa rilis (5 menit sebelum merge)

• Kunci: ikuti pola penamaan Anda, dan jaga ruang lingkup jelas (halaman, fitur, komponen).
• Plural: konfirmasi bentuk plural dirender benar di setidaknya satu bahasa dengan aturan plural berbeda.
• Placeholder: verifikasi variabel hadir, bernama sama di mana-mana, dan terlihat benar dengan data nyata.
• Fallbacks: pastikan perilaku missing-key sesuai kebijakan saat ini.
• Layar: spot-check beberapa layar yang paling mungkin rusak (tabel, toast, modal, state kosong).

Putuskan apa yang diukur (supaya masalah terlihat cepat)

Pilih beberapa angka sederhana dan tinjau secara berkala: tingkat missing-key di run test Anda, jumlah string yang belum diterjemahkan di locale non-default, dan jumlah unused key (string yang tak lagi muncul di mana pun). Lacak per rilis jika bisa, supaya Anda melihat tren bukan kegagalan satu kali.

Tulis langkah tepat untuk menambah string, memperbarui terjemahan, dan memverifikasi hasil. Buat singkat, dan sertakan contoh nama kunci dan penggunaan plural. Kontributor baru harus bisa mengikutinya tanpa bertanya.

Jika Anda membangun alat internal, AppMaster (appmaster.io) bisa menjadi cara praktis menjaga copy UI dan kunci terjemahan konsisten di seluruh aplikasi web Vue3 dan aplikasi mobile pendamping, karena semuanya dikelola di satu tempat.

Jadwalkan satu tugas kesehatan i18n kecil setiap sprint: hapus kunci mati, perbaiki placeholder yang tidak konsisten, dan tinjau miss terbaru. Pembersihan kecil mengalahkan pengejaran terjemahan darurat di produksi.