Tutorial 5 Localization id

Tutorial 5 · Lokalisasi (i18n)

🌎 Bahasa: Bahasa Indonesia (id) — lihat semua 33 bahasa

Tujuan: memahami cara LockedIn CLI berbicara dalam 33 bahasa dan berlatih mengarahkan agen menambah bahasa lain. Lokalisasi cocok untuk agen: cukup mekanis untuk didelegasikan, tetapi punya batasan nyata berupa gerbang tes, aturan layout, dan review tata bahasa.

← Sebelumnya: Tutorial 4 Prompt dan Review · Kembali ke Beranda

---

Arti “dilokalkan” di sini

Jalankan CLI dalam bahasa Spanyol, Hindi, Jepang, Tionghoa Sederhana, atau bahasa lain yang tersedia dan semuanya berubah: splash, tabel help, output command, sesi chat, bahkan tulisan hukum. Bukan hanya lelucon, tetapi seluruh permukaan yang terlihat.

lockedin --lang id post
LOCKEDIN_LANG=hi lockedin
lockedin --lang zh aura

Bahasa dideteksi otomatis saat startup dengan prioritas:

1. flag --lang (--lang id, --lang=fr, -l ja)
2. environment variable LOCKEDIN_LANG
3. locale (LC_ALL / LC_MESSAGES / LANG, lalu locale OS/runtime)
4. bahasa Inggris sebagai fallback

Jadi --lang selalu mengalahkan nilai LOCKEDIN_LANG.

normalizeLang() biasanya memakai subtag utama locale. de-DE memilih de, tetapi tlh tidak tanpa sengaja menjadi tl. Alias fil dan tgl memang dipetakan ke Tagalog (tl), nb/nn ke no, Indonesian lama in ke id, dan Hebrew lama iw ke he. Dua kode regional dipertahankan: pt-BR/pt_BR memilih kode regional kanonis sedangkan pt tetap bundle Portugis Brasil yang kompatibel ke belakang; en-SG/en_SG mempertahankan Singlish sedangkan en tetap Inggris. Untuk Tionghoa Tradisional Hong Kong, zh-HK, zh_HK.UTF-8, dan zh-Hant-HK memilih zh-HK; zh dan tag mainland memilih Tionghoa Sederhana.

Berganti di tengah sesi melalui panel /language. CLI selalu dapat dimulai dengan bahasa lain lewat --lang atau LOCKEDIN_LANG; kini bahasa juga dapat diganti dalam sesi. /language—alias /lang dan /languages—menampilkan 33 bahasa dengan aksara masing-masing. /language el mengganti bahasa untuk sisa sesi. Setelah pergantian, panel digambar dalam bahasa baru lalu, dalam bahasa yang baru ditinggalkan, mencetak cara kembali yang tepat: /language en sekarang atau lockedin --lang en lain kali. Karena itu pengguna tidak akan terjebak dalam aksara seperti 日本語 atau ಕನ್ನಡ yang tak dapat dibaca. Jika berganti dua kali, bahasa dari LOCKEDIN_LANG juga ditawarkan. Ini utilitas serius seperti /a11y, bukan bagian satir.

Gagasan bundle bahasa

Semua teks yang dapat diterjemahkan berada dalam satu bundle per bahasa:

{ meta: { lang: 'id', name: 'Bahasa Indonesia', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Kepadatan buzzword: ', /* label, heading */ } }

• pools adalah array konten atau lelucon dari Bab 2.
• ui berisi chrome string: label, heading, dan template kecil.

Bahasa Inggris adalah referensi di src/lockedin.js; 32 module lain berada di src/content/*.js: ar, bn, bo, de, el, en-SG, es, eu, fa, fi, fr, he, hi, id, is, it, ja, kn, ms, nl, no, pl, pt, pt-BR, ru, sv, tl, tr, uk, ur, zh, zh-HK. pt-BR memakai kembali pools/UI milik pt tetapi didaftarkan terpisah. Semua terdaftar di BUNDLES; SUPPORTED_LANGS dibuat dari key tersebut dan renderHelp() mencetak daftar hasil generate, bukan daftar hardcoded.

setLang('fr');       // arahkan bahasa aktif ke bundle Prancis
// L = pool aktif, U = UI aktif
pick(L.HOOKS)        // hook bahasa Prancis
U.buzzwordDensity    // "Densité de jargon : "

Karena setiap renderer membaca L dan U, bukan string hardcoded, setLang saja mengubah seluruh pengalaman.

Jaring pengaman: kesetaraan key

Invariant yang membuat penambahan bahasa aman adalah:

Setiap bundle harus memiliki key pools dan ui yang persis sama dengan bahasa Inggris.

Tes menerapkannya di 33 bundle. Jika string UI baru ditambah ke Inggris tetapi terjemahan Ukraina terlupa, npm test merah dan menyebut key yang hilang. Bundle setengah terjemahan tidak dapat lolos diam-diam.

Bagian sulit: layout terminal

Bahasa menguji layout dengan cara berbeda:

• Jepang, Tionghoa Sederhana, dan Tionghoa Tradisional Hong Kong memakai karakter East Asian Wide/Fullwidth. vw() menghitungnya sebagai dua kolom dan wrap() memecah token panjang tanpa spasi agar teks CJK tetap dalam kartu.
• Hindi dan Kannada memakai combining mark nonspacing/enclosing (Mn / Me), misalnya matra dan virama. vw() menghitungnya nol kolom.
• box() membungkus setiap baris body sebelum padding agar banner panjang tidak menembus border.
• Setiap bundle menentukan sentenceEnd dan listSep, misalnya . / 。 dan , / 、, agar kalimat gabungan terasa alami.

String header kartu (cardSubtitle, cardMeta, cardFooter) harus tetap ≤ 60 visible column. Arab, Persia, Ibrani, dan Urdu memakai meta.dir: 'rtl'. Secara default output tidak memiliki kontrol bidi karena sebagian terminal menampilkannya sebagai label kotak. LOCKEDIN_BIDI=on mengaktifkan isolate seimbang setelah wrapping pada terminal yang diketahui mendukungnya, sambil mempertahankan ANSI, command ASCII, dan urutan copy/paste. Output accessible selalu menghapus kontrol. Dukungan tidak boleh diprobe atau disimpulkan.

Bagian licik: tata bahasa di sekitar input mentah

Template UI tertentu menyisipkan klausa pengguna melalui placeholder seperti {cap}. Jangan menerjemahkan slot demi slot tanpa memikirkan tata bahasa. Placeholder mungkin berupa klausa panjang, bukan nomina rapi.

Bug nyata pernah muncul ketika template Jepang menaruh は langsung setelah {cap}; hasilnya janggal bila {cap} adalah klausa penuh. Solusinya bukan “menerjemahkan lebih keras”, tetapi menyusun ulang template, misalnya dengan nominalizer atau memindahkan placeholder agar input apa pun tetap cocok.

✅ Coba bersama agenmu — tambah bahasa

Pilih bahasa yang dapat kamu periksa, lalu tulis spesifikasi:

Tambahkan bahasa Denmark (da). Buat src/content/da.js sebagai bundle { meta, pools, ui } dengan key yang sama seperti Inggris dan terjemahkan setiap entri—pool sekitar 25 item dan seluruh string UI. Daftarkan da di BUNDLES dalam src/lockedin.js. --lang da dan locale da-* harus memilihnya. Jaga header kartu dalam batas lebar. npm test harus hijau dan tambahkan invariant Denmark serta tes deteksi yang meniru bahasa lain.

Kemudian jalankan loop Bab 3–4:

1. Rencana dulu. “Sebelum menulis kode, sebutkan file yang akan diubah dan cara menjaga kesetaraan key dengan Inggris.”
2. Tes dulu. “Tambahkan tes gagal untuk deteksi da, key parity da, dan invariant reflect/connect Denmark. Jangan buat bundle dulu.”
3. Implementasi. “Buat src/content/da.js dengan menerjemahkan bundle yang ada key demi key, daftarkan, dan buat tes lulus. Hanya pick/shuffle untuk randomness.”
4. Gerbang + review. Jalankan npm test, lalu lockedin --lang da post. Pastikan semua key diterjemahkan, border sejajar, dan template {cap} menerima klausa mentah.

Latihan lebih kecil:

• “Tambahkan satu TAGLINE ke semua 33 bundle dengan jumlah tetap sama.”
• “Periksa apakah cardFooter Kannada ≤ 60 visible column dan jelaskan pengukuran combining mark.”
• “Tunjukkan tes yang gagal jika key ui dihapus dari ja.js.”

---

Langkah selanjutnya

• Lihat src/content/es.js sebagai template bundle baru.
• Baca kembali docs/HANDOFF.md → “Adding a language”.
• Nikmati lelucon multibahasa di Referensi Command.

Tutorial lengkap selesai. Sekarang kamu dapat mengarahkan agen membangun fitur dan melokalkannya di balik gerbang tes, dalam 33 bahasa dan siap bertambah. Setuju? 👇