Teks UI tetap konsisten kalau setiap string yang terlihat oleh pengguna ada di satu katalog di repo, dirujuk lewat kunci, dan hanya berubah melalui diff yang sudah direview. Itu disiplin yang sama dengan yang sudah kamu terapkan pada logika, hanya diterapkan pada redaksi. Semua yang ada di halaman ini adalah praktik yang membuat disiplin itu bertahan.
Ini panduan operasional. Arsitektur di baliknya, beserta argumen mengapa codebase harus menjadi sumber kebenaran untuk teks produk, ada di teks produk berbasis kode. Baca itu kalau kamu ingin tahu alasannya. Lanjutkan di sini kalau kamu ingin tahu caranya.
Di mana teks UI sebaiknya disimpan?
Di satu file katalog per bahasa sumber, di dalam repositori, bersebelahan dengan kode yang merendernya. Bukan di spreadsheet, bukan di file desain, bukan di halaman wiki yang masih akurat pada bulan Maret. Katalog adalah tempat yang dibuka developer, reviewer, penerjemah, dan agen coding ketika ingin tahu apa isi sebuah layar.
Aturan praktis yang mengikutinya:
- Satu katalog, satu bahasa sumber. Satu
en.json(atau.po,.ftl,.strings, sesuai format yang dibaca library i18n-mu) menjadi catatan resmi teks. Kalau kamu punya beberapa aplikasi dalam monorepo, setiap aplikasi punya satu katalog, dan string yang dipakai bersama masuk ke katalog bersama yang diimpor keduanya. Yang perlu dihindari adalah dua file yang bisa menyimpan pesan yang sama. - Kelompokkan per layar atau fitur, bukan per komponen. Kunci seperti
checkout.summary.totallebih awet daripadaSummaryCard.totalLabel, karena komponen sering diganti nama dan dipecah, sedangkan layar dan pesannya tetap. - Beri nama kunci sesuai pesannya, bukan redaksinya.
checkout.submittetap relevan setelah “Place order” diubah menjadi “Buy now”.checkout.placeOrderButtontidak, dan ketidakcocokan antara kunci dan teks membuat reviewer di kemudian hari mengira keduanya string yang berbeda. - Simpan katalog dalam PR yang sama dengan kode yang memakainya. String yang ditambahkan di satu PR dan komponennya di PR lain adalah string yang akan terlewat, terlupakan, atau terduplikasi.
Kalau string-mu masih berupa literal di dalam komponen, katalog adalah hal pertama yang perlu dibuat. Mengerjakannya manual adalah proyek tersendiri, dan itulah alasan untuk menghubungkan repositori dan membiarkan konversi otomatis yang mengerjakannya, seperti dibahas di bagian bawah.
Mengapa merujuk lewat kunci lebih baik daripada mencari literalnya?
Karena sebuah kunci hanya bisa mengarah ke satu string, sedangkan literal bisa diketik dengan cara yang sebanyak jumlah developernya. “Sign in”, “Sign In”, “Log in”, dan “Login” adalah empat string bagi tool pencarian, tetapi satu maksud bagi pengguna. Ketika setiap komponen memanggil t("auth.signIn"), pertanyaan tentang redaksi mana yang benar dijawab sekali, di satu tempat, dan jawabannya berlaku di semua tempat kunci itu dipakai.
Dua kebiasaan menjaga pola ini tetap berjalan:
- Pakai ulang sebelum menambah. Sebelum membuat kunci, cari dulu pesannya di katalog. Kalau
common.cancelsudah ada,dialog.cancelButtonbaru dengan teks yang sama adalah awal dari drift, bukan duplikat yang tidak berbahaya. Keduanya akan diedit sendiri-sendiri begitu salah satunya diubah. - Jangan menggabungkan string.
t("cart.items") + " " + countmenghasilkan teks yang tidak tercantum di baris katalog mana pun. Gunakan interpolasi dan bentuk plural dari library-mu supaya seluruh kalimat menjadi satu unit yang bisa direview.
Pengecualian yang sering dipakai adalah “string ini hanya muncul sekali, jadi literal tidak masalah”. Hari ini memang hanya sekali. Nanti komponennya disalin, layarnya punya layar saudara, dan literal itu ikut terbawa lalu berbeda sendiri.
Bagaimana cara mereview perubahan teks di pull request?
Perlakukan baris katalog yang berubah seperti signature fungsi yang berubah: sesuatu yang dibaca, dipertanyakan, dan disetujui reviewer. Praktik inilah yang mengubah konsistensi dari masalah ingatan menjadi masalah review, dan review adalah satu-satunya momen ketika orang dapat diandalkan benar-benar memperhatikan.
Yang membuat review katalog efektif:
- Perubahan redaksi menjadi barisnya sendiri di diff. Ini hanya berlaku kalau string ada di katalog. Perubahan redaksi di dalam komponen memang juga muncul di diff, tetapi tersembunyi di antara perubahan logika dan dilewati sebagai “cuma teks”.
- Arahkan perubahan katalog ke pemilik teks. Entri
CODEOWNERSpada path katalog berarti siapa pun yang memegang redaksi, baik orang produk, content designer, maupun developer yang paling peduli, otomatis diminta mereview setiap perubahan. Bagian lain di PR tetap melalui review biasa. - Ajukan tiga pertanyaan untuk setiap baris yang berubah. Apakah ini istilah yang disetujui untuk hal ini? Apakah nada dan huruf kapitalnya cocok dengan string di sekitarnya? Apakah nama kunci masih menggambarkan pesannya? Reviewer yang menanyakan ketiganya akan menangkap sebagian besar masalah yang hendak dicegah oleh panduan gaya.
- Tolak penggantian nama yang diam-diam. PR yang mengubah
auth.signIndari “Sign in” menjadi “Log in” tanpa penjelasan adalah keputusan teks yang diambil oleh siapa pun yang kebetulan sedang mengedit. PR itu perlu satu kalimat di deskripsi yang menjelaskan alasannya, atau harus di-revert.
Masalah yang dicegah ini punya nama. Copy drift adalah teks yang terlihat pengguna menyimpang dari sumber resminya di berbagai tampilan dan seiring waktu, tanpa satu sumber kebenaran sebagai acuan. Apa itu copy drift membahas penyebabnya; review katalog di diff adalah praktik yang menghentikan sebagian besar masalah tersebut.
Bagaimana cara mencegah string hardcode baru masuk?
Buat literal baru menggagalkan build. Aturan dan review menangkap hal yang diingat orang untuk dicari. Aturan lint menangkap sisanya, di setiap pull request, tanpa perlu ada yang mengingat.
Pengaturannya kecil saja:
- Aktifkan aturan no-literal-string.
eslint-plugin-i18nextmenyediakannya untuk proyek JavaScript dan TypeScript. Batasi cakupannya ke teks JSX dan atribut yang tampil ke pengguna seperti petunjuk input,title,aria-label, danalt, lalu kecualikan file test dan Storybook story supaya aturannya tetap kredibel. - Jalankan di tempat merge terjadi. Pre-commit hook memang praktis; langkah di CI yang paling menentukan, karena berjalan di pull request terlepas dari apakah editor penulisnya sudah dikonfigurasi.
- Tambahkan pengecekan kunci yang tidak terpakai dan yang hilang. Sebagian besar library i18n punya tool pendamping yang mendaftar kunci yang dirujuk di kode tetapi tidak ada di katalog, dan kunci di katalog yang tidak dirujuk di mana pun. Jalankan juga di CI. Kunci yang tidak terpakai adalah tempat redaksi usang bersembunyi.
- Mulai dengan ketat, lalu izinkan pengecualian lewat komentar. Aturan yang dinonaktifkan untuk seluruh folder
components/bukan lagi aturan. Aturan yang dinonaktifkan pada satu baris beserta alasannya adalah dokumentasi.
Tim yang membangun dengan tool coding AI lebih sering mengalami ini, karena tool tersebut meregenerasi komponen dari konteks lokal dan membawa literal kembali. Mengapa Cursor AI terus menambahkan string hardcode membahas aturan lint ini secara rinci, termasuk pengaturan tiga lapis berupa file aturan, linter, dan CI.
Apa yang perlu ada di panduan gaya teks untuk developer?
File pendek di repositori yang muat dalam satu layar, menjelaskan gaya bahasa, menetapkan istilah, dan menyebutkan di mana string disimpan. Panduan gaya yang panjang tinggal di wiki dan hanya dibaca sekali. Yang pendek tinggal di samping kode dan dibaca orang maupun tool setiap kali ada string baru.
COPY.md yang berfungsi (atau satu bagian di panduan kontributor yang sudah ada) mencakup:
- Gaya bahasa, dalam tiga kalimat. Produk terdengar seperti siapa, seberapa formal, dan apakah menyebut “kamu” atau “pengguna”. Cukup untuk menyelesaikan sebagian besar perdebatan.
- Istilah yang tidak pernah berubah. Nama produk untuk setiap fitur, kata kerja untuk aksi inti (apakah “Simpan” atau “Perbarui”? “Hapus” atau “Buang”?), dan kata-kata yang diputuskan untuk tidak dipakai.
- Aturan huruf kapital dan tanda baca. Sentence case atau title case pada tombol dan heading, memakai titik di tooltip atau tidak, serta cara penulisan angka dan tanggal.
- Di mana string disimpan dan bagaimana kunci dinamai. Path katalog, aturan pengelompokan, aturan penamaan kunci, dan “cari dulu sebelum menambah”.
- Apa yang dilakukan kalau ragu. Siapa yang ditanya, atau kunci mana yang dipakai ulang untuk sementara.
Simpan di repositori supaya file aturan bisa menunjuk ke sana, reviewer bisa menautkannya di komentar, dan agen coding bisa membacanya sebelum menulis label.
Bagaimana cara menjaga agen coding AI agar tidak merusak konsistensi?
Beri agen sumber kebenaran untuk dibaca dan pemeriksaan yang menangkapnya saat ia tidak mengikutinya. Agen yang membuat form dengan senang hati menulis “Submit” di satu layar dan “Send” di layar berikutnya, karena masing-masing adalah kata yang paling mungkin secara lokal. Ia tidak ceroboh; ia hanya tidak punya acuan untuk menjaga konsistensi.
Dua langkah menyelesaikan sebagian besar masalahnya. Pertama, file aturan (AGENTS.md, .cursor/rules, CLAUDE.md, sesuai yang dibaca tool-mu) yang menyatakan: teks yang terlihat pengguna masuk ke katalog, pakai ulang kunci yang ada, dan baca COPY.md sebelum menulis label. Kedua, aturan lint dari bagian di atas, karena file aturan mengurangi tebak-tebakan dan aturan lint menangkap tebakan yang lolos.
Hanya itu yang perlu dibahas halaman ini soal agen. Masalah spesifik ketika agen menulis ulang string yang sudah ada, dan cara membuat perubahan itu terlihat alih-alih diam-diam, adalah topik tersendiri: cara menghentikan agen coding AI menulis ulang teks UI-mu.
Di mana posisi lokalisasi?
Konsistensi dan lokalisasi bergantung pada hal yang sama, yaitu sumber yang disepakati, sehingga katalog yang memberimu yang satu juga memberimu yang lain. Tim yang tidak bisa menyebutkan mana dari tiga redaksi yang disetujui juga tidak akan bisa menerjemahkan satu pun dengan benar. Perbaiki sumbernya, dan terjemahan menjadi artefak turunan dari katalog, bukan proyek terpisah dengan versi kebenarannya sendiri.
Dalam praktiknya, katalog yang kamu bangun demi konsistensi sudah menjadi file yang dikerjakan penerjemah atau tool terjemahan. Setiap kunci mendapat padanannya di setiap bahasa target, nama kunci yang sama berlaku, dan perubahan redaksi di katalog sumber terlihat sebagai perubahan yang harus diikuti terjemahan. Kalau terjemahan dibiarkan tertinggal dari sumbernya, kamu menghadapi masalah seperti yang dijelaskan di mengapa file terjemahan tidak sinkron, dan solusinya tetap disiplin yang sama: satu katalog, kunci, perubahan di diff.
Posisi globalize.now
globalize.now adalah sistem manajemen teks berbasis kode dengan lokalisasi bawaan, dan setiap praktik di halaman ini adalah asumsinya tentang repositorimu. Kamu menghubungkan repositori GitHub atau GitLab di aplikasi. Pemindaian mencari tahu apa saja yang ada. Kalau string berupa literal di dalam komponen, konversi satu kali memindahkannya ke katalog dengan kunci dan menambahkan setup i18n kalau belum ada. Kalau kamu sudah memakai next-intl, react-i18next, i18next, atau Lingui, globalize.now bekerja dengan yang sudah kamu punya. Hasilnya datang sebagai pull request di branch tersendiri, sehingga katalog pertama melewati review persis seperti yang dijelaskan di atas. Setelah itu, string sumber baru yang kamu tambahkan diterjemahkan oleh push job yang membuka pull request berisi hasilnya. Repositori tetap menjadi satu-satunya sumber kebenaran.
Kami sedang membangun ke arah disiplin yang sama berlaku di situs marketing, landing page, dan produk dari satu sumber, sehingga sebuah fitur dijelaskan dengan cara yang sama di mana pun pengguna menemuinya. Itu arah yang kami tuju, bukan sesuatu yang bisa dibeli hari ini. Harga ada di halaman harga.
Daftar periksa yang bisa kamu terapkan minggu ini
- Buat satu katalog per bahasa sumber di repositori, dan tentukan aturan penamaan kunci.
- Pindahkan string dari layar yang paling sering kamu sentuh ke dalamnya; rujuk lewat kunci.
- Aktifkan aturan lint no-literal-string, dibatasi ke teks yang tampil ke pengguna, dan jalankan di CI.
- Tambahkan baris
CODEOWNERSpada path katalog. - Tulis
COPY.md: gaya bahasa, istilah tetap, aturan huruf kapital, dan tempat penyimpanan string. Satu layar. - Arahkan file aturan agen ke katalog dan ke
COPY.md. - Tolak setiap perubahan redaksi di review yang tidak punya alasan di deskripsi PR.
Kalau langkah kedua terlihat seperti pekerjaan sebulan, hubungkan repositori, baca rencana yang diusulkan, dan review pull request yang dibukanya.
globalize.now mengubah teks hardcode di aplikasimu menjadi file locale yang siap diterjemahkan, lalu menjaganya tetap diperbarui setiap kali kamu rilis.
Coba globalize.now gratis