EN

Bahasa

Setiap halaman tersedia dalam bahasa Inggris dan Indonesia. Sumber berbahasa Inggris diterjemahkan saat dirakit, jadi Anda cukup menulis setiap halaman sekali.

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:

LapisanCara menerjemahkannya
Teks di HTMLSaat dirakit, dari kamus i18n/id.json.
Teks yang ditulis skripDi browser, dengan _t(text, values) dan _tn(n, one, other).
Angka, uang, tanggalDi browser, dengan pemformat bersama window.slFmt.
Data demoSetiap 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 localStorage dengan kunci sl-lang (en atau id). 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 dengan id di 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, atau kbd, 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.
i18n/id.json
{
  "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.

Angka otomatis
5,717       →  5.717
+12.4%      →  +12,4%
10:32       →  10.32
$8,800.00   →  Rp8.800
Uang tidak dikonversi

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:

JavaScript
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.js sebelum selaras.js. Perakitan membuat berkas itu dari i18n/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.

JavaScript
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'
FungsiKegunaan
money, moneyShort, bigMoneyNominal uang, nominal ringkas untuk sumbu grafik, dan nominal besar yang dipecah menjadi angka dan satuan untuk KPI.
num, int, pctAngka, bilangan bulat dengan tanda minus yang sebenarnya, dan persentase.
date, short, dayDate, monthYear, spanTanggal dari teks ISO atau Date, dengan atau tanpa tahun atau nama hari, serta rentang tanggal.
time, clock, clockRange, hourJam dan rentang jam.
parse, looseMembaca 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-orders menjadi sl-shop-orders@id — jadi perubahan di satu bahasa tidak pernah menimpa bahasa lainnya. Pakai window.slI18n.key('sl-my-app') untuk mendapatkan kunci yang tepat bagi aplikasi Anda sendiri.

Menambah atau mengubah terjemahan

  1. Tulis teks baru dalam bahasa Inggris seperti biasa: di HTML src/pages/, atau dibungkus _t('Your text') di skrip.
  2. Jalankan node build.mjs. Setiap teks yang belum punya entri Indonesia tercatat di i18n/missing-id.txt, satu per baris: teksnya, sebuah tab, lalu halaman tempat teks itu muncul.
  3. Tambahkan terjemahannya. Sunting i18n/id.json langsung, atau tulis berkas dua kolom (Inggris, tab, Indonesia) lalu tambahkan sekaligus — nilai berupa satu tanda sama dengan berarti "sama dengan teks Inggrisnya":
    Terminal
    python tools/i18n/add-translations.py my-translations.tsv
    Skrip ini tidak pernah menimpa entri yang sudah ada dengan terjemahan berbeda; bentrokannya dilaporkan. Untuk mengubah terjemahan, sunting i18n/id.json; untuk kata yang butuh dua terjemahan, pakai kunci khusus halaman atau kunci berkonteks.
  4. Rakit ulang dan periksa halaman Indonesianya.

Dua pembantu lain di tools/i18n/ (Python 3):

  • missing-keys.py mendaftar kunci yang belum ada di kamus untuk halaman dan berkas skrip yang Anda sebutkan — teks HTML dari i18n/missing-id.txt ditambah teks setiap panggilan _t(text) dan _tn(n, one, other) di skrip:
    Terminal
    python tools/i18n/missing-keys.py app-kanban kanban.js
  • wrap-strings.py membungkus teks di dalam string HTML pada berkas skrip dengan panggilan _t(text). Tanpa --write, alat ini hanya mencetak perubahannya.
Mengubah teks Inggris

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:

Terminal
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:

Terminal
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 — LANGS berisi daftar bahasa yang dirakit, sedangkan DICT dan DOCS hanya memuat kamus Indonesia. Folder keluaran id, atribut lang, tautan bahasa, dan berkas buatan assets/i18n/id.js ditulis khusus untuk bahasa Indonesia di toIndonesian, dan autoFig menulis ulang angka dalam format Indonesia. Masing-masing perlu versi untuk bahasa baru beserta folder keluarannya sendiri.
  • assets/js/selaras.js — bahasa halaman hanya dikenali sebagai en atau id, dan LOCALES menyimpan 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.html beserta penangan klik yang sesuai di selaras.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.