10 kesilapan i18n yang kerap berlaku dan cara mengelakkannya
Pelajari kesilapan i18n yang paling biasa dilakukan oleh pembangun, dan bagaimana anda membetulkannya. Tingkatkan kualiti lokalisasi aplikasi anda dengan amalan terbaik ini.
Internasionalisasi (i18n) kelihatan mudah — hingga anda sedar bahawa pengguna Jerman anda melihat butang yang dipotong, pengguna Jepun anda menerima frasa ayat yang terpotong, dan pengguna berbahasa Arab anda menghadapi paparan susun atur yang rosak sepenuhnya. Ini bukan kes-kes luar biasa. Ia adalah akibat yang dijangkakan daripada kesilapan biasa yang dilakukan oleh kebanyakan pasukan pembangunan ketika pertama kali mendekati lokalisasi. Dalam panduan ini, kita akan membincangkan 10 kesalahan i18n yang paling kerap, menjelaskan tepat mengapa mereka berlaku, dan menunjukkan langkah demi langkah bagaimana anda membaikinya satu persatu. Sama ada anda membina aplikasi baharu atau menaik taraf yang sedia ada — mengelakkan perangkap ini akan menjimatkan beberapa minggu debugging dan memberikan pengalaman yang halus untuk pengguna di seluruh dunia.
Ralat #1: Rentetan terhardcode
Penulisan string secara keras adalah ralat i18n yang paling asas. Ia berlaku kerana pembangun terlebih dahulu memberi tumpuan untuk menjayakan ciri-ciri, dan merancang untuk 'membersihkan kemudian'. Tetapi akhirnya tidak datang, dan tiba-tiba anda mempunyai ribuan string tersebar di seluruh ratusan fail.
['Sediakan i18n-kerangka kerja sebelum menulis baris UI pertama', 'Guna plug-in Linter untuk mengenal pasti rentetan hard-coded dalam templat dan komponen', 'Pastikan kunci terjemahan bersifat deskriptif dan diatur mengikut ciri atau halaman']
Sediakan rangka kerja i18n anda sebelum anda menulis baris UI pertama.
Guna plugin linter untuk mengenal pasti rentetan yang di-hardcode dalam templat dan komponen.
Kunci terjemahan hendaklah deskriptif dan diatur mengikut ciri atau halaman.
Satu senario biasa
Seorang pemaju menulis label butang secara langsung dalam JSX: <button>Submit Order</button>.
Aplikasi dihantar dalam Bahasa Inggeris dan berfungsi dengan baik. Enam bulan kemudian syarikat berkembang ke Jerman.
Pasukan lokalisasi menemui 2.000+ rentetan hard-coded. Naik taraf mengambil masa 3 minggu dan menyebabkan 47 pepijat.
Mengapa ini adalah masalah
Dalam kod sumber yang matang, rentetan yang di-hardcode boleh mencecah beribu-ribu. Membedahnya kemudian memerlukan anda mengubah setiap fail, menguji setiap komponen semula dan berisiko regresi di mana-mana.
Rentetan yang di-hardcode adalah tersisip secara langsung dalam kod sumber, templat atau komponen. Mereka tidak boleh diekstrak, diterjemahkan atau ditukar semasa berjalan tanpa mengubah kod itu sendiri.
Pengguna dalam lokal setempat yang bukan Inggeris melihat elemen UI tidak diterjemah bercampur dengan kandungan terjemahan — kesan yang kacau dan tidak profesional.
Bagaimana cara membetulkannya
Pindahkan semua rentetan yang dilihat pengguna sejak awal ke dalam fail sumber.
Rancang sebuah rangka kerja terjemahan (cth. next-intl, react-i18next, vue-i18n), sebelum anda menulis komponen pertama anda.
Cipta struktur fail sumber (cth. messages/de.json) dan referensi semua rentetan melalui kunci terjemahan seperti t('checkout.submitButton').
Tambahkan peraturan lint atau pra-commit yang menandakan literal rentetan mentah dalam komponen UI.
Ralat #10: Terjemahkan semua secara harfiah
Tidak semua kandungan perlu diterjemah. Nama jenama, nama entiti undang-undang, terma teknikal dan beberapa nama produk perlu kekal dalam bahasa asal. Penterjemahan berlebihan boleh menyebabkan masalah undang-undang, inkonsistensi jenama dan kekeliruan pengguna.
["Simpan glosari 'tidak diterjemahkan' dan kongsi dengan semua penterjemah", 'Gunakan segmen terkunci atau namespace berasingan untuk istilah jenama dan hak cipta', 'Sentiasa sediakan nota konteks untuk string yang mempunyai pelbagai tafsiran, bagi mengelakkan terjemahan yang salah']
Sediakan glosari 'tidak diterjemah' dan kongsikannya kepada semua penterjemah.
Gunakan segmen tersekat atau namespace berasingan untuk terma jenama dan undang-undang
Sediakan nota konteks untuk string yang mempunyai pelbagai maksud bagi mengelakkan terjemahan yang salah.
Satu senario contoh
Fail terjemahan mengandungi nama syarikat 'CloudForge Inc.' dan istilah teknikal 'OAuth 2.0 Token' sebagai rentetan yang boleh diterjemah seperti biasa.
Penterjemah Sepanyol menterjemah 'CloudForge' kepada 'ForjaNube' dan 'OAuth 2.0 Token' kepada 'Token OAuth 2.0'.
Hasilnya: Pengguna tidak menemui syarikat itu dengan nama sebenarnya, dan pembangun yang membaca dokumentasi berbahasa Sepanyol menjadi keliru kerana istilah teknikal yang diterjemahkan tidak dikenali.
Mengapa ini menjadi masalah
Satu nama jenama yang salah diterjemah dalam dokumen undang-undang boleh membatalkan kontrak. Memperbaiki terjemahan berlebihan memerlukan semakan setiap rentetan dalam setiap bahasa — kerja berbulan-bulan.
Jika semua rentetan dihantar ke terjemahan tanpa konteks, penterjemah mungkin akan menterjemahkan nama jenama ('Apple' → 'Apfel'), istilah undang-undang ('GmbH' → 'LLC') atau sebutan teknikal yang perlu kekal dalam bahasa Inggeris.
Pengguna tidak menemui produk di bawah jenama yang diketahui, dokumen undang-undang merujuk kepada syarikat yang salah, dan dokumentasi teknikal menjadi tidak jelas jika istilah seperti 'API Endpoint' diterjemahkan.
Cara membetulkannya
Tandakan kandungan yang tidak boleh diterjemah dengan jelas dan sediakan nota konteks untuk penterjemah.
Buat glosari 'Tidak diterjemah' yang merangkumi semua nama jenama, nama produk, entiti undang-undang, dan istilah teknikal yang perlu kekal tidak berubah.
Guna namespace berasingan atau kunci khas untuk kandungan yang tidak boleh diterjemah. Banyak alat i18n menyokong segmen 'terkunci' yang tidak boleh diedit oleh penterjemah.
Tambahkan komen/penerangan untuk penterjemah pada fail terjemahan anda yang menerangkan konteks: 'Ini adalah nama jenama — tidak diterjemah' atau 'Istilah teknikal — dibiarkan dalam bahasa Inggeris.'
Ralat #2: Penyambungan rentetan
Menggabungkan ayat daripada frasa secara bersambung kelihatan logik dalam bahasa Inggeris, tetapi tidak berfungsi dalam bahasa lain. Susunan kata, tatabahasa dan struktur ayat berbeza dengan ketara antara bahasa, menjadikan rentetan bersepadu tidak boleh diterjemahkan.
['Jangan pernah gabungkan ayat melalui penyambungan fragmen terjemahan', 'Gunakan penampal bernama ('{name}') berbanding kedudukan ({0}) untuk kejelasan', 'Sediakan komen konteks untuk penterjemah yang menerangkan apa yang terkandung dalam setiap penampal']
Jangan membina ayat dengan menyambungkan fragmen terjemahan.
Gunakan penampal bernama ('{name}') berbanding kedudukan ({0}) untuk kejelasan
Sediakan komen konteks untuk penterjemah yang menjelaskan apa yang terkandung dalam setiap pemegang tempat.
Satu contoh tipikal
Pemaju menulis: 'You have ' + count + ' items in your ' + cartType + ' cart' — berfungsi sempurna dalam bahasa Inggeris.
Penterjemah Jerman menerima tiga fragmen berasingan dan tidak dapat membentuk ayat yang gramatis kerana urutan kata perlu diubah.
Hasilnya: Pengguna Jerman melihat 'Sie haben 5 Artikel in Ihrem Warenkorb Standard' — kedengaran janggal dan tidak profesional.
Mengapa ini adalah masalah
Setiap rentetan berantai adalah bom masa yang berdetak. Dengan 20 bahasa dan 50 rentetan berantai, anda mempunyai 1,000 potensi kesilapan tatabahasa yang perlu dibetulkan secara manual.
Penyambungan rentetan seperti 'Willkommen ' + userName + ', du hast ' + count + ' neue Nachrichten' memerlukan susunan kata tertentu. Penterjemah menerima fragmen konteks-kosong yang tidak boleh diatur semula.
Pengguna melihat ayat-ayat tatabahasa yang salah. Dalam bahasa Jerman, kata kerja sering berada di akhir. Dalam bahasa Arab, seluruh struktur terbalik. Keputusannya kedengaran seperti tidak masuk akal.
Cara membetulkannya
Gunakan mesej berparameter dengan penanda tempat bernama supaya penterjemah boleh menyusun semula keseluruhan ayat.
Gantikan penyambungan dengan satu kunci mesej tunggal dengan penampal: 'cart.summary': 'Anda mempunyai {count} item dalam troli '{cartType}''.
Penterjemah menyediakan semua bentuk jamak yang diperlukan untuk bahasa mereka. Bahasa Polandia: '{count, plural, one {# plik} few {# pliki} many {# plików} other {# pliku}}'.
Penterjemah kini boleh mengubah susunan secara bebas: 'Dalam troli '{cartType}', terdapat {count} item' — bahasa Jerman yang grammatikal betul.
Ralat #3: Mengabaikan bentuk jamak
Inggeris mempunyai dua bentuk jamak: tunggal dan jamak. Pembangun sering menganggap semua bahasa berfungsi sama. Tetapi tidak. Bahasa Poland mempunyai 4 bentuk, bahasa Arab mempunyai 6, dan bahkan bahasa seperti Perancis memperlakukan nombor nol berbeza daripada Inggeris.
['Sentiasa gunakan ICU MessageFormat atau perpustakaan serupa untuk kandungan yang boleh dikira', 'Jangan pernah menulis logik jamak sendiri—percaya pada aturan CLDR', 'Uji bentuk jamak dengan nilai seperti 0, 1, 2, 5, 21 dan 100 untuk mencakup semua kategori']
Sentiasa gunakan ICU MessageFormat atau perpustakaan setara untuk kandungan yang boleh diitung.
Jangan pernah menulis logik jamak sendiri—percayalah pada aturan CLDR.
Uji bentuk jamak dengan nilai seperti 0, 1, 2, 5, 21 dan 100 untuk merangkumi semua kategori.
Satu contoh tipikal
Pembangun menulis: count + (count === 1 ? ' Datei' : ' Dateien') — menangani Jerman dengan tepat.
Penterjemah Poland memerlukan 4 bentuk: 1 plik, 2–4 pliki, 5–21 plików, 22–24 pliki. operator ternari mudah tidak dapat menggambarkan itu.
Keputusan: Pengguna Poland melihat '5 pliki' (bentuk salah) berbanding '5 plików' (bentuk betul), dan aplikasi kelihatan rosak.
Mengapa ini menjadi masalah.
Setiap kata nama boleh kira dalam aplikasi anda memerlukan perlakuan jamak. Dengan 50 string sebegini dan 20 bahasa, itu menghasilkan 1,000 peraturan jamak — mustahil untuk diuruskan secara manual.
Pemeriksaan if/else mudah (count === 1 ? 'Datei' : 'Dateien') hanya menangani Jerman/Inggeris. CLDR mendefinisikan sehingga 6 kategori jamak: zero, one, two, few, many und other. Setiap bahasa menggunakan subset.
Pengguna melihat teks tatabahasa yang salah seperti '1 mesej' atau bentuk jamak yang sama sekali salah. Dalam konteks rasmi, ini merosakkan kredibiliti.
Bagaimana cara membetulkannya.
Guna ICU MessageFormat yang menyokong semua peraturan jamak CLDR secara bawaan.
Definiere mesej dengan sintaks ICU: 'fileCount': '{count, plural, one {# Datei} other {# Dateien}}'.
Penterjemah menyediakan semua bentuk jamak yang diperlukan untuk bahasa mereka. Bahasa Polandia: '{count, plural, one {# plik} few {# pliki} many {# plików} other {# pliku}}'.
Pustaka i18n Anda secara automatik memilih bentuk yang tepat saat berjalan berdasarkan aturan CLDR untuk locale yang aktif.
Ralat #4: Lebar elemen UI yang tetap.
Pereka bentuk membentuk susun atur berasaskan piksel dalam bahasa Inggeris, dan pembangun melaksanakannya dengan lebar tetap. Tetapi teks terjemahan boleh menjadi lebih panjang atau lebih pendek secara dramatik. Teks Jerman kira-kira 30% lebih panjang daripada bahasa Inggeris, manakala teks Cina boleh menjadi 50% lebih pendek.
['Jangan pernah menggunakan lebar piksel tetap pada elemen dengan teks yang boleh diterjemah', 'Rancang untuk peningkatan teks 40% sebagai garis dasar — sesetengah bahasa berkembang lebih banyak', 'Gunakan CSS Flexbox atau Grid untuk susun atur yang menyesuaikan dengan panjang isi yang berbeza']
Jangan pernah menggunakan lebar piksel tetap pada elemen dengan teks yang boleh diterjemahkan.
Rancang peningkatan teks sebanyak 40% sebagai garis dasar — sesetengah bahasa berkembang lagi.
Gunakan CSS Flexbox atau Grid untuk susun atur yang menyesuaikan dengan panjang kandungan yang berbeza
Satu contoh senario
Pereka bentuk membuat bar navigasi dengan 5 butang, setiap tepat lebar 100px — kelihatan hebat dalam bahasa Inggeris.
Terjemahan Jerman: 'Settings' jadi 'Einstellungen' (13 berbanding 8 aksara), 'Submit' jadi 'Absenden' (8 berbanding 6). Navbar melimpah.
Hasilnya: pada perangkat mudah alih, tombol-tombol menumpuk satu sama lain atau teks terpotong, sehingga navigasi tidak dapat digunakan untuk pengguna Jerman.
Mengapa ini menjadi masalah
Setiap elemen dengan lebar tetap adalah potensi titik pecah. Aplikasi tipikal mempunyai ratusan butang, label, dan kad yang semuanya perlu menampung pertambahan teks.
Kontena dengan lebar tetap (width: 120px) dan butang berukuran tetap dipotong atau melimpah apabila teks meluap. CSS overflow: hidden menyembunyikan kandungan secara senyap, manakala overflow: visible merosakkan susun atur.
Pengguna melihat label terpotong seperti 'Einstellu...' bukannya 'Einstellungen', atau butang yang menindih elemen bersebelahan. Tindakan kritikal menjadi tidak terbaca atau tidak boleh diklik.
Begini cara mengatasinya
Rancang dan terapkan susun atur fleksibel yang menyesuaikan diri dengan panjang isi untuk semua lokal.
Gantikan lebar tetap dengan min-width, max-width dan susunan Flexbox. Gunakan CSS Grid atau Flexbox untuk membagi ruang secara dinamis.
Pastikan wadah teks dapat memecah kata: gunakan overflow-wrap: break-word dan hindari white-space: nowrap untuk konten yang dapat diterjemahkan.
Uji UI anda dengan Lokalisasi Pseudo yang memperpanjang semua rentetan sebanyak 40% untuk mensimulasikan kasus terburuk — sebelum anda menghantar string kepada penterjemah.
Ralat #5: Pemformatan tarikh dan nombor.
Data dan nombor nampak universal. Tetapi 01/02/2025 bermakna 2 Januari di AS dan 1 Februari di Eropah. Koma dan noktah menukar maksud dalam nombor: 1,000.50 (AS) vs 1.000,50 (Jerman). Melakukan ini salah akan membawa kepada kekeliruan, ralat data, dan kehilangan kepercayaan.
['Jangan memformat data atau nombor secara manual menggunakan templat string — sentiasa gunakan API Intl', 'Simpan semua data dalam ISO 8601 dan mata wang dalam unit terkecil (sen) secara dalaman', 'Uji dengan Locale yang menggunakan pemisah desimal, susunan tarikh berbeza dan sistem kalendar berbeza']
Jangan pernah memformat data atau nombor secara manual menggunakan templat rentetan — sentiasa gunakan API Intl.
Simpan semua data dalam ISO 8601 dan mata wang dalam unit terkecil (sen) secara dalaman.
Uji dengan Locale yang menggunakan pemisah desimal berbeza, urutan tarikh berbeza dan sistem kalendar berbeza.
Satu contoh senario
Pembangun memformatkan tarikh sebagai MM/DD/YYYY dan harga sebagai $1,234.50 — tepat untuk pengguna US.
Pengguna Jerman melihat tarikh 03/04/2025 dan membacanya sebagai 3. April (DD/MM/YYYY-Konvensjon). Harga $1,234.50 terlihat seolah-olah sepatutnya menjadi 1.234,50.
Hasilnya: Pengguna menempah penerbangan untuk tarikh yang salah dan mempersoalkan format harga. Tiket sokongan meningkat sebanyak 15% di pasaran Jerman.
Mengapa ini masalah
Format tarikh dan nombor berhubung dengan setiap paparan data dalam apl anda: jadual, carta, borang, invois, laporan. Pembetulan global merangkumi ratusan contoh.
Format string yang di-hardcode seperti toLocaleDateString('en-US') atau pemformatan manual dengan Template-Literals mengabaikan Locale sebenar pengguna. Bahkan Locale yang betul tetapi kalendar yang salah (Gregorian vs Hijri) menyebabkan masalah.
Pengguna membaca data salah dan memasukkan data dalam format yang salah. Seorang pengguna Eropah yang melihat 03/04/2025 mungkin menginterpretasikannya sebagai 3. April bukannya 4. Mac — pertemuan terlepas atau tempahan palsu.
Inilah cara mengatasinya
Gunakan API Intl terbina dalam atau perpustakaan pemformatan yang peka terhadap lokal untuk semua tarikh, masa, nombor, dan mata wang.
Gantikan format manual dengan Intl.DateTimeFormat(locale) untuk tarikh dan Intl.NumberFormat(locale, { style: 'currency', currency }) untuk harga.
Simpan data secara dalaman dalam format ISO 8601 (YYYY-MM-DD) dan formatkan hanya untuk paparan menggunakan lokasi pengguna.
Uji paparan tarikh dan nombor yang kritikal dengan sekurang-kurangnya 5 locale berbeza: en-US, de-DE, ja-JP, ar-SA, dan zh-CN, untuk merangkumi varian-format utama.
Ralat #6: terlupa bahasa RTL
Bahasa bertulisan kanan-kiri (RTL) seperti Arab, Ibrani dan Parsi digunakan oleh lebih daripada 500 juta orang. Walau bagaimanapun, kebanyakan aplikasi direka hanya untuk susunan kiri-ke-kanan (LTR). Sokongan RTL bukan sekadar membalik teks — antaramuka pengguna (UI) keseluruhan perlu dicerminkan.
['Gunakan sejak hari pertama sifat CSS yang logik sahaja (inline-start/end, block-start/end)', 'Uji aplikasi anda dengan dir='rtl' pada elemen HTML pada setiap tinjauan sprint', 'Sediakan senarai semak ujian RTL untuk navigasi, ikon, borang dan penunjuk kemajuan']
Mulai dari hari pertama gunakan hanya properti CSS logik (inline-start/end, block-start/end).
Uji aplikasinya dengan dir='rtl' pada elemen HTML pada setiap sprint-review.
Buat daftar cek RTL untuk navigasi, ikon, borang dan kemajuan.
Salah satu senario tipikal
Pembangun menggunakan margin-left: 16px dan text-align: left di seluruh aplikasi — amalan LTR standard.
Aplikasi dimulakan di Arab Saudi. Anak panah balik menunjukkan ke depan, bar sisi muncul pada sisi yang salah, dan nombor-nombor numerik tidak sejajar.
Keputusan: Pengguna Arab meninggalkan aplikasi selepas 30 saat. Pasukan memerlukan 4 minggu refaktor CSS kecemasan untuk membetulkan masalah ini.
Mengapa ini menjadi masalah
Sokongan RTL melibatkan setiap komponen dalam aplikasi anda. Menambah sokongan RTL kemudian biasanya memerlukan penulisan semula 30–50% daripada semua peraturan CSS dan pemeriksaan setiap ikon serta susun atur.
Sifat CSS seperti margin-left, padding-right, text-align: left dan float: left mengunci arah. Ikon dengan maksud arah (anak panah, penunjuk kemajuan) menunjukkan arah yang salah. Malah nilai border-radius juga perlu dicerminkan.
Pengguna berbahasa Arab melihat navigasi di sudut yang salah, bar kemajuan bergerak ke arah bertentangan, dan teks bertembung dengan elemen UI. Aplikasi terasa asing dan tidak senang digunakan.
Inilah cara mengatasinya
Gunakan logische CSS-Properties dan test dengan RTL-layout dari awal.
Gantikan semua sifat CSS fizikal dengan pasangan logik: margin-left → margin-inline-start, padding-right → padding-inline-end, text-align: left → text-align: start.
Tetapkan atribut dir pada elemen akar HTML anda berdasarkan Locale yang aktif. Gunakan pseudo-kelas CSS :dir(rtl) untuk override khusus RTL.
Periksa semua ikon untuk maksud arah. Ganti ikon berarah dengan versi yang dicerminkan atau guna CSS transform: scaleX(-1) untuk konteks RTL.
Ralat #7: Gambar berteks
Menanam teks dalam imej — sama ada dalam banner hero, butang, infografik atau tangkapan skrin — adalah mimpi buruk lokalisasi. Setiap imej yang mengandungi teks perlu dibuat semula untuk setiap bahasa, meningkatkan kos reka bentuk dan menunda pelepasan.
['Beri teks yang boleh diterjemah, tetapi jangan pernah meletakkannya secara langsung dalam gambar raster (PNG, JPG)', 'Gunakan overlay teks CSS pada gambar latar untuk hero-banner dan CTA', 'Automatikkan penjanaan tangkapan skrin untuk senarai App Store dan halaman pemasaran']
Jangan pernah memasukkan teks yang boleh diterjemahkan secara langsung ke dalam imej raster (PNG, JPG).
Gunakan overlay teks CSS pada latar belakang imej untuk hero banner dan CTA.
Automasikan penjanaan tangkapan skrin untuk senarai App Store dan laman pemasaran
Satu senario tipikal
Seorang pereka bentuk mencipta banner promosi dengan teks 'Start Your Free Trial' tersisip dalam gambar.
Tim lokalisasi menerjemahkan semua UI-string, tetapi banner pada halaman Jerman masih menampilkan teks berbahasa Inggris.
Hasilnya: Halaman pendaratan berbahasa Jerman mempunyai banner bahasa Inggeris yang mengganggu. Mempunyai banner yang dilokalisasikan untuk 15 bahasa mengambil masa 3 hari kerja reka bentuk dan melambatkan pelancaran.
Mengapa ini menimbulkan masalah
Sebuah halaman pemasaran tipikal mempunyai 5–10 gambar dengan teks. Dalam 15 bahasa, itu adalah 75–150 variasi gambar yang perlu dibuat, dipelihara dan dikemas kini setiap kali reka bentuk diubah.
Teks yang disisipkan dalam imej (PNG, JPG, SVG dengan teks tersirat) tidak boleh diekstrak oleh alat terjemahan. Setiap versi lokal memerlukan pereka untuk menyunting fail sumber secara manual, mengeksport dan memuat naik.
Pengguna melihat gambar dengan teks dalam bahasa asing, atau lebih buruk lagi, gabungan antara UI yang diterjemahkan dan gambar yang belum diterjemah. Ini kelihatan tidak konsisten dan merosakkan kepercayaan terhadap jenama.
Begini cara mengatasinya
Pisahkan teks daripada gambar menggunakan overlay CSS, SVG dengan elemen teks yang boleh diterjemah atau penjanaan gambar dinamik.
Guna CSS untuk meletakkan teks terjemahan di atas gambar latar: kedudukan lapisan teks secara absolut di atas bekas gambar.
Untuk infografik atau diagram, gunakan SVG dengan elemen <text> yang merujuk kepada kunci terjemahan, bukannya meletakkan string mentah.
Untuk tangkapan skrin aplikasi dalam bahan pemasaran, automatikkan penjanaan tangkapan skrin dengan alat seperti Fastlane (mobile) atau Playwright (web), yang merakam skrin dalam setiap locale.
Ralat #8: Terjemahan yang hilang tidak ditangani
Terjemahan semasa pembangunan sentiasa tidak lengkap. Ciri baharu menambah rentetan dengan lebih pantas berbanding penterjemah yang dapat menterjemahkannya. Tanpa logik fallback yang betul, terjemahan yang hilang akan menyebabkan kerosakan, elemen UI kosong, atau kunci terjemahan mentah yang dipaparkan kepada pengguna.
['Sentiasa konfigurasikan sekurang-kurangnya satu bahasa fallback dalam susunan i18n anda', 'Log kes-kes kunci terjemahan yang hilang ke sistem pemantauan anda untuk penjejakan', 'Tetapkan had liputan terjemahan minimum sebelum sesuatu Locale boleh diluncurkan']
Sentiasa konfigurasikan sekurang-kurangnya satu bahasa fallback dalam tetapan i18n anda
Logkan kunci terjemahan yang hilang ke sistem pemantauan anda untuk menjejaknya
Tetapkan tahap liputan terjemahan minimum sebelum sesuatu Locale boleh diterbitkan
Satu senario tipikal
Pembangun menambah bahagian baharu 'Premium Features' dengan 15 kunci terjemahan baharu. Versi bahasa Inggeris dihantar segera.
Terjemahan Perancis belum siap. Laman Perancis memaparkan kunci mentah: 'premium.feature1.title', 'premium.feature1.description'.
Hasilnya: Pengguna Perancis melihat halaman rosak penuh dengan nama kunci pembangun. Pasukan sokongan menerima puluhan laporan pepijat.
Mengapa itu masalah
Semakin besar aplikasi anda, semakin besar jurang antara rentetan Inggeris dan terjemahan dalam bahasa lain. Aplikasi dengan 100 bahasa dan 2.000 rentetan boleh mempunyai 10.000+ terjemahan yang hilang pada bila-bila masa.
Tanpa fallback-logik, kunci terjemahan yang hilang akan mengembalikan undefined, null, atau teks kunci mentah (contoh: 'checkout.confirmButton'). Enjin templat boleh menyebabkan kod ralat, laman crash, atau tiada apa-apa dirender.
Pengguna melihat UI yang rosak: butang kosong, label hilang atau rentetan teks seperti 'nav.settings.title' bukannya teks sebenar. Ini membingungkan dan tidak profesional.
Selesaikan dengan langkah tepat
Konfigurasikan rangkaian fallback yang kukuh dan pantau liputan terjemahan merentasi semua Lokal.
Bina rangkaian bahasa fallback dalam konfigurasi i18n anda: kekunci bahasa Perancis yang hilang (fr) akan secara automatik kembali ke Inggeris (en).
Tambahkan pengendali Missing-Key yang mencatat kunci yang belum diterjemahkan ke dalam sistem pemantauan anda (contohnya Sentry, Datadog) tanpa mengganggu pengalaman pengguna.
Buat papan pemantauan liputan terjemahan yang mengikuti tahap penyelesaian per Locale dan menyekat pelepasan jika liputan turun di bawah ambang (contohnya 95%).
Ralat #9: Masalah pengekodan aksara.
Isu pengekodan huruf adalah pembunuh senyap lokalisasi. Semuanya kelihatan betul dalam Bahasa Inggeris dan bahasa Eropah, tetapi apabila anda menambah Cina, Jepun, Korea, Arab, atau emoji, aksara yang rosak akan muncul. Bug-bug ini terkenal sukar untuk dikesan.
['Gunakan pengekodan UTF-8 di mana-mana — fail sumber, pangkalan data, jawapan API dan tag meta HTML', 'Gunakan utf8mb4 dalam MySQL (bukan utf8), untuk menyokong julat Unicode penuh termasuk emoji', 'Uji dengan kandungan sebenar dalam CJK, Arab, dan emoji untuk menangkap masalah pengekodan lebih awal']
Gunakan pengekodan UTF-8 di mana-mana — fail sumber, pangkalan data, respons API dan tag meta HTML
Gunakan utf8mb4 dalam MySQL (bukan utf8), untuk mendukung seluruh Unicode termasuk Emoji.
Uji dengan kandungan sebenar dalam CJK, Arab, dan Emoji untuk mengesan masalah pengekodan lebih awal
Satu senario biasa
Pembangun memasang pangkalan data MySQL dengan kolasi latin1 (standar lama). Kod sumber aplikasi menggunakan UTF-8.
Pengguna Jepun mendaftar dengan nama sebenar mereka. Pangkalan data menyimpan '田中太郎' sebagai bait yang rosak.
Keputusan: Profil pengguna memaparkan teks yang terpotong. Lebih buruk lagi: carian dan penyusunan untuk semua nama CJK akan rosak, melibatkan beribu-ribu pengguna.
Mengapa ini menjadi masalah
Kod pengekodan meresap ke seluruh stack anda. Collation pangkalan data yang salah boleh merosakkan jutaan rekod — pembaikan memerlukan migrasi data yang mahal.
Pengekodan tidak konsisten di seluruh stack — UTF-8 dalam fail sumber, Latin-1 dalam pangkalan data dan Windows-1252 dalam respons API — merosakkan aksara berbilang-byte. Satu lapisan yang salah konfigurasi boleh menukar '日本語' menjadi '????' atau '日本èª'.
Pengguna melihat teks yang terpotong, tanda tanya atau kotak kosong di tempat bahasa mereka seharusnya muncul. Dalam kes teruk, input borang boleh rosak secara kekal dalam pangkalan data.
Cara mengatasinya
Paksakan pengekodan UTF-8 secara konsisten di setiap lapisan stack aplikasi anda.
Tetapkan semua fail sumber kepada UTF-8 (konfigurasikan penyunting anda dan .editorconfig). Tambahkan <meta charset='UTF-8'> dalam HTML anda dan 'Content-Type: application/json; charset=utf-8' dalam respons API.
Konfigurasikan pangkalan data anda ke utf8mb4 (bukan sekadar utf8, yang merupakan subset 3-byte dalam MySQL). Tetapkan kolasi sambungan kepada utf8mb4_unicode_ci.
Pilih fon yang merangkumi sistem huruf sasaran anda: Latin, Cyrillic, CJK, Arab, Devanagari. Gunakan susun fon sistem atau Google Fonts dengan subset bahasa untuk pemuatan yang optimum.
Uji implementasi i18n anda.
Ujian peluasan panjang
Tingkatkan semua rentetan terjemahan sebanyak 30-40% untuk mensimulasikan peluasan teks yang berlaku dalam bahasa-bahasa yang panjang kata seperti Jerman, Finlandia, atau Yunani. Ini merangkumi kontena dengan lebar tetap, label yang terpotong, dan butang yang meluap sebelum anda mula menterjemah. Banyak alat lokalisasi palsu menyediakan ini sebagai ciri terbina dalam.
"Senden" → "Ṡééééñðéñ_éxpáñðéð" (40% lebih panjang)
Lokalisasi Palsu
Pseudo-lokalisasi menggantikan setiap karakter dengan aksara beraksen (misalnya 'a' → 'á') dan membungkus rentetan dengan penanda seperti [!! dan !!]. Hal ini membuat mana rentetan yang di-hardcode dan mana yang berasal dari sistem terjemahan menjadi terlihat dengan segera. Jalankan lokalisasi palsu sebagai bagian dari pipeline CI Anda untuk secara otomatis menangkap regresi.
Setiap teks pada skrin yang tidak berada dalam penanda [!! !!]-Markeringen adalah hardkodet dan perlu dialihkan. Ujian ini menangkap kira-kira 95% rentetan yang terlepas dalam kurang daripada satu minit.
"Hantar mesej" → "[!! Ñáçḥŕíçḥṫ ṡéñðéñ !!]"
Ujian Susun Atur RTL
Walau tanpa terjemahan Arab atau Ibrani, anda boleh menguji susun atur RTL dengan menambahkan dir='rtl' ke elemen root HTML anda. Ini segera mengesan pepijat CSS berarah: ikon yang tidak selaras, margin di sisi yang salah, navigasi rosak dan item flex yang disusun semula dengan salah. Jadikan ini sebagai pemeriksaan standard dalam setiap tinjauan sprint — ia hanya memerlukan 10 saat untuk menukar dan akan menangkap masalah yang biasanya memerlukan berminggu-minggu untuk diperbaiki di produksi.
Senarai semak i18n
['Alle rentetan yang boleh dilihat pengguna dalam fail sumber telah dialihkan', 'Tiada penggabungan rentetan untuk membina ayat', 'Peraturan jamak dilaksanakan dengan ICU MessageFormat atau setara', 'Penformatan tarikh, masa dan nombor menggunakan API yang sensitif terhadap lokasi', 'Layout RTL dengan kandungan Arab atau Ibrani telah diuji', 'UI yang fleksibel tanpa lebar tetap untuk elemen berteks', 'Bahasa sandaran telah dikonfigurasikan dan diuji untuk kunci yang hilang', 'Pengekodan UTF-8 konsisten merentas semua fail dan pangkalan data', 'Metadata App Store dan Play Store untuk setiap pasaran telah dilokalisasikan', 'Skrin tangkapan layar dan aset pemasaran untuk setiap bahasa telah dikemas kini']