Dua bahasa
Perakitan menulis setiap halaman dua kali: halaman Inggris di sebelah folder assets (index.html) dan kembarannya yang berbahasa Indonesia di folder id/ (id/index.html). Keduanya memakai CSS, skrip, dan gambar yang sama.
Ada empat lapisan yang ikut diterjemahkan:
| Lapisan | Cara menerjemahkannya |
|---|---|
| Teks di HTML | Saat dirakit, dari kamus i18n/id.json. |
| Teks yang ditulis skrip | Di browser, dengan _t(text, values) dan _tn(n, one, other). |
| Angka, uang, tanggal | Di browser, dengan pemformat bersama window.slFmt. |
| Data demo | Setiap aplikasi punya data contoh berbahasa Indonesia sendiri dan menyimpannya terpisah. |
Tombol bahasa
Tombol ID di bilah atas (EN di halaman Indonesia) membuka halaman yang sama dalam bahasa lain dan tetap membawa query string serta #hash, jadi daftar yang sedang disaring atau tab yang sedang terbuka tetap di tempatnya.
- Tombol ini bagian dari tata letak admin: dasbor, aplikasi, halaman UI Kit, dan dokumentasi ini. Halaman tanpa bilah atas admin — halaman masuk, halaman galat, dan etalase toko — tidak punya tombol ini; buka versi
id/-nya secara langsung. - Setiap klik juga menyimpan bahasa yang dipilih di
localStoragedengan kuncisl-lang(enatauid). Template sendiri tidak membaca nilai ini — nilai itu disediakan untuk kode Anda, misalnya halaman awal yang mengarahkan pengunjung lama ke bahasanya. - Skrip mengetahui bahasa halaman dari
<html lang="…">. Perakitan mengisinya denganiddi halaman Indonesia.
Cara teks halaman diterjemahkan
Anda menulis halaman di src/pages/ dalam bahasa Inggris saja. Saat Anda menjalankan node build.mjs, perakitan mencari setiap potong teks yang terlihat — dan atribut seperti placeholder, title, alt, dan aria-label — di i18n/id.json, lalu menulis halaman Indonesia dengan terjemahannya.
- Kuncinya adalah teks Inggris itu sendiri, persis seperti yang tampil di halaman; spasi berderet dihitung satu. Tidak ada nama kunci yang perlu dikarang.
- Elemen sebaris tetap di dalam kalimat. Bila sebuah kalimat memuat tag sebaris seperti
strong,em,code, ataukbd, seluruh kalimat menjadi satu kunci dan setiap elemen sebaris menjadi penanda bernomor, sehingga terjemahannya boleh menaruhnya dalam urutan lain. Elemen sebaris tanpa huruf, seperti ikon atau angka saja, justru memecah kalimat menjadi beberapa kunci. - Satu halaman boleh berbeda. Kunci yang diawali
@page-name|(nama berkas tanpa.html) hanya berlaku di halaman itu dan mengalahkan entri bersama. - Teks sama di kedua bahasa. Entri yang nilainya sama dengan kuncinya (nama produk, merek) menandai teks yang dibiarkan apa adanya.
- Contoh kode tidak diubah, kecuali teks yang persis sama dengan kunci kamus, supaya contoh kode tetap cocok dengan contoh hidup di atasnya.
{
"Close shift": "Tutup shift",
"Drag cards, or use {0}Alt{/0} + arrow keys": "Seret kartu, atau pakai {0}Alt{/0} + tombol panah",
"Delivery": "Antar",
"@ecommerce-order|Delivery": "Pengiriman",
"Kanban": "Kanban"
} Angka tanpa huruf tidak perlu entri: perakitan menulis ulang angka itu dengan format angka Indonesia.
5,717 → 5.717
+12.4% → +12,4%
10:32 → 10.32
$8,800.00 → Rp8.800 Penulisan ulang otomatis hanya mengganti pemisah dan simbol mata uang — dolar tidak dikonversi ke rupiah. Untuk nominal tetap yang ditulis di HTML, tambahkan entri kamus dengan nilai rupiah yang wajar.
Teks yang ditulis skrip
Teks yang dipasang skrip ke halaman melewati window.slI18n. Skrip halaman biasanya diawali dua alias pendek:
var _t = window.slI18n.t, _tn = window.slI18n.tn;
// a sentence with a value: {name} is filled in after translating
el.textContent = _t('Viewed by {name}', { name: 'Dewi' });
// a count: English needs two forms, the dictionary maps both to one Indonesian form
label.textContent = _tn(count, '{n} invoice', '{n} invoices');
// a word with two meanings: the prefix before | is a context, English shows only the text after it
chip.textContent = _t('status|Void'); - Di halaman Inggris,
_t(text, values)mengembalikan teks Inggrisnya dengan nilai yang sudah diisi, jadi perilaku versi Inggris tidak pernah bergantung pada kamus. - Halaman Indonesia memuat
assets/i18n/id.jssebelumselaras.js. Perakitan membuat berkas itu darii18n/id.json— sunting JSON-nya, jangan berkas buatan perakitan itu. - Kunci berkonteks (
status|Void,cat|Home) dipakai untuk teks di skrip. Di HTML, pakai kunci khusus halaman.
Angka, uang, dan tanggal
Semua pemformatan melewati window.slFmt, yang membaca bahasa halaman. Halaman Inggris menampilkan dolar dengan sen dan format jam 12 jam; halaman Indonesia menampilkan rupiah tanpa desimal dan format 24 jam.
var F = window.slFmt;
F.money(1250); // '$1,250.00' Indonesian: 'Rp1.250'
F.num(5717); // '5,717' Indonesian: '5.717'
F.pct(12.4, 1); // '12.4%' Indonesian: '12,4%'
F.date('2026-09-23'); // 'Sep 23, 2026' Indonesian: '23 Sep 2026'
F.clock('2026-09-23T14:00'); // '2:00 PM' Indonesian: '14.00'
F.parse('25,000'); // 25000 — on Indonesian pages type '25.000' | Fungsi | Kegunaan |
|---|---|
money, moneyShort, bigMoney | Nominal uang, nominal ringkas untuk sumbu grafik, dan nominal besar yang dipecah menjadi angka dan satuan untuk KPI. |
num, int, pct | Angka, bilangan bulat dengan tanda minus yang sebenarnya, dan persentase. |
date, short, dayDate, monthYear, span | Tanggal dari teks ISO atau Date, dengan atau tanpa tahun atau nama hari, serta rentang tanggal. |
time, clock, clockRange, hour | Jam dan rentang jam. |
parse, loose | Membaca nominal yang diketik kembali menjadi angka. parse mengembalikan null untuk isian kosong dan NaN untuk teks yang bukan nominal. |
Pustaka bawaan juga mengikuti bahasa halaman: skrip halaman memberi grafik, kalender, pemilih tanggal, dan pustaka UI Kit lainnya nama bulan, label, dan format angka Indonesia.
Data demo dan data tersimpan
- Demo Indonesia punya data contoh sendiri. Nominalnya disesuaikan menjadi harga rupiah yang wajar, bukan dikonversi dengan kurs, dan bila cocok aplikasinya memakai nama dan alamat pelanggan Indonesia, kurir lokal, serta PPN 11%.
- Data tersimpan dipisah per bahasa. Di halaman Indonesia, kunci simpanan diberi akhiran
@id—sl-shop-ordersmenjadisl-shop-orders@id— jadi perubahan di satu bahasa tidak pernah menimpa bahasa lainnya. Pakaiwindow.slI18n.key('sl-my-app')untuk mendapatkan kunci yang tepat bagi aplikasi Anda sendiri.
Menambah atau mengubah terjemahan
- Tulis teks baru dalam bahasa Inggris seperti biasa: di HTML
src/pages/, atau dibungkus_t('Your text')di skrip. - Jalankan
node build.mjs. Setiap teks yang belum punya entri Indonesia tercatat dii18n/missing-id.txt, satu per baris: teksnya, sebuah tab, lalu halaman tempat teks itu muncul. - Tambahkan terjemahannya. Sunting
i18n/id.jsonlangsung, atau tulis berkas dua kolom (Inggris, tab, Indonesia) lalu tambahkan sekaligus — nilai berupa satu tanda sama dengan berarti "sama dengan teks Inggrisnya":Skrip ini tidak pernah menimpa entri yang sudah ada dengan terjemahan berbeda; bentrokannya dilaporkan. Untuk mengubah terjemahan, suntingpython tools/i18n/add-translations.py my-translations.tsvi18n/id.json; untuk kata yang butuh dua terjemahan, pakai kunci khusus halaman atau kunci berkonteks. - Rakit ulang dan periksa halaman Indonesianya.
Dua pembantu lain di tools/i18n/ (Python 3):
missing-keys.pymendaftar kunci yang belum ada di kamus untuk halaman dan berkas skrip yang Anda sebutkan — teks HTML darii18n/missing-id.txtditambah teks setiap panggilan_t(text)dan_tn(n, one, other)di skrip:python tools/i18n/missing-keys.py app-kanban kanban.jswrap-strings.pymembungkus teks di dalam string HTML pada berkas skrip dengan panggilan_t(text). Tanpa--write, alat ini hanya mencetak perubahannya.
Teks Inggris adalah kuncinya, jadi menyunting sebuah kalimat di sumber membuat terjemahan lamanya tidak terpakai. Kalimat barunya muncul di i18n/missing-id.txt sampai Anda menambahkan terjemahannya.
Hanya satu bahasa
Rakit satu bahasa saja dengan opsi --lang:
node build.mjs --lang en Perintah ini hanya menulis halaman Inggris dan melewati kamus. Perakitan tidak menghapus halaman yang dirakit sebelumnya, jadi hapus sendiri folder id/ bila tidak ikut dikirim, dan buang tautan bahasa (elemen ber-data-sl-lang-switch) dari bilah atas di src/layout.html.
Kamus khusus dokumentasi
Halaman dokumentasi ini diterjemahkan dengan cara yang sama, dari kamus terpisah: i18n/docs-id.json. Di halaman docs-*, perakitan mencari di sana dulu, baru kemudian di i18n/id.json. Karena dipisah, teks panjang ini tidak ikut dimuat di setiap halaman aplikasi lewat assets/i18n/id.js.
Untuk menambah terjemahan dokumentasi dari berkas, sertakan --docs:
python tools/i18n/add-translations.py --docs my-docs-translations.tsv Bila dokumentasi tidak ikut dikirim, hapus berkas docs-*.html dari src/pages/ dan dari folder hasil rakitan, lalu buang tautan Pusat bantuan di src/layout.html.
Menambah bahasa ketiga
Selaras dibuat untuk tepat dua bahasa, Inggris dan Indonesia. Bahasa ketiga bisa ditambahkan, tetapi itu berarti mengubah kode di beberapa tempat, bukan sekadar mengganti pengaturan:
build.mjs—LANGSberisi daftar bahasa yang dirakit, sedangkanDICTdanDOCShanya memuat kamus Indonesia. Folder keluaranid, atributlang, tautan bahasa, dan berkas buatanassets/i18n/id.jsditulis khusus untuk bahasa Indonesia ditoIndonesian, danautoFigmenulis ulang angka dalam format Indonesia. Masing-masing perlu versi untuk bahasa baru beserta folder keluarannya sendiri.assets/js/selaras.js— bahasa halaman hanya dikenali sebagaienatauid, danLOCALESmenyimpan nama bulan dan hari, mata uang, jumlah desimal, serta urutan tanggal untuk keduanya. Tambahkan locale untuk bahasa baru dan perluas pengenalannya.- Tombol bahasa berpindah di antara dua folder. Dengan tiga bahasa, tombol ini perlu menjadi menu di
src/layout.htmlbeserta penangan klik yang sesuai diselaras.js. - Skrip halaman — data demo dan pengaturan pustaka (grafik, kalender, pemilih) memeriksa apakah halamannya berbahasa Indonesia. Bahasa baru akan memakai data dan pengaturan Inggris sampai Anda menambahkan miliknya sendiri.