Tutorial 5 Localization ms

Tutorial 5 · Penyetempatan (i18n)

🌎 Bahasa: Bahasa Melayu (ms) — lihat semua 33 bahasa

Matlamat: fahami caranya LockedIn CLI bercakap 33 bahasa — dan berlatih mengarahkan ejen untuk menambah satu lagi. Penyetempatan ialah tugas ejen yang hebat: ia cukup mekanikal untuk diwakilkan, tetapi ia mempunyai kekangan sebenar (pintu ujian, peraturan reka letak, semakan tatabahasa) yang mengajar anda untuk menyemak.

← Sebelum: Tutorial 4 Penggesaan & Semakan · Kembali ke Home

---

Maksud "disetempatkan" di sini

Jalankan CLI dalam bahasa Sepanyol, Hindi, Jepun, Cina Ringkas atau mana-mana bahasa yang dihantar dan semuanya berubah — percikan, jadual bantuan, setiap output arahan, sesi sembang, malah cetakan halus undang-undang. Bukan sekadar jenaka: seluruh permukaan yang boleh dilihat.

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

Bahasa ini dikesan secara automatik semasa permulaan, diselesaikan mengikut urutan keutamaan:

1. bendera --lang (--lang ms, --lang=fr, -l ja)
2. pembolehubah persekitaran LOCKEDIN_LANG
3. locale anda (LC_ALL / LC_MESSAGES / LANG, kemudian locale OS/runtime)
4. bahasa Inggeris sebagai sandaran

normalizeLang() biasanya menggunakan subtag utama locale. Ini bermakna de-DE memilih de, tetapi tlh tidak tersalah menjadi tl; alias sebenar fil dan tgl sengaja dipetakan kepada Tagalog (tl), nb dan nn kepada bahasa Norway (no), kod Indonesia lama in kepada id, dan kod Ibrani lama iw kepada he. Dua kod serantau dikekalkan dan tidak dilipat kepada subtag utama: pt-BR/pt_BR memilih kod serantau kanonik, manakala pt generik kekal sebagai bundle Portugis Brazil yang serasi ke belakang (kedua-duanya berkongsi pool/UI yang sama); en-SG/en_SG pula mengekalkan Singlish (sementara en generik kekal bahasa Inggeris). Cina Tradisional Hong Kong ialah pengecualian yang sama: zh-HK, zh_HK.UTF-8, dan zh-Hant-HK memilih zh-HK, manakala zh generik dan tag tanah besar memilih Cina Ringkas (zh).

Menukar bahasa semasa sesi — panel /language. CLI sentiasa boleh bermula dalam bahasa lain (--lang, LOCKEDIN_LANG); kini anda juga boleh bertukar di tengah sesi. Taip /language (alias /lang dan /languages) untuk menyenaraikan semua 33 bahasa mengikut kod, setiap satu dalam tulisannya sendiri; /language el menukar bahasa untuk baki sesi. Tujuannya ialah jalan keluar: selepas pertukaran, paparan dilukis semula dalam bahasa baharu dan kemudian, dalam bahasa yang baru anda tinggalkan, cara tepat untuk kembali dicetak — /language en sekarang, lockedin --lang en pada pelancaran seterusnya — supaya anda tidak terperangkap jika tersalah memilih 日本語 atau ಕನ್ನಡ. (Tukar dua kali dan bahasa yang dinamakan oleh LOCKEDIN_LANG turut ditawarkan.) --lang dan LOCKEDIN_LANG tidak berubah. Seperti /a11y, ini utiliti yang benar-benar berguna, bukan sebahagian daripada sindiran.

Idea: himpunan bahasa

Semua teks yang boleh diterjemahkan berada dalam bundle, satu bagi setiap bahasa, dan setiap satunya berbentuk seperti:

{ meta: { lang: 'ms', name: 'Bahasa Melayu', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Ketumpatan kata kunci: ', /* label, tajuk */ } }

• pools ialah susunan kandungan (lawak) yang anda temui dalam Bab 2.
• ui ialah rentetan krom: label, tajuk dan templat kecil.

Bahasa Inggeris ialah bundle rujukan dalam src/lockedin.js; 32 modul bundle lain berada dalam 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, dan zh-HK (pt-BR menggunakan semula pool/UI pt tetapi didaftarkan secara berasingan). Setiap bundle didaftarkan dalam BUNDLES; SUPPORTED_LANGS dijana daripada kunci tersebut, dan renderHelp() mencetak senarai kod yang dijana. Tiada bundle UI mengod keras senarai itu.

setLang('fr');       // halakan bahasa aktif ke pakej Perancis
// L = pool aktif, U = UI aktif
pick(L.HOOKS)        // pembuka Perancis
U.buzzwordDensity    // "Densité de jargon : "

Kerana setiap renderer membaca L dan U (tidak pernah rentetan berkod keras), setLang sahaja mengubah keseluruhan pengalaman. Itulah muslihat keseluruhannya.

Jaring keselamatan: kesetaraan kunci

Berikut ialah invarian yang menjadikan penambahan bahasa selamat:

Setiap bundle mesti menyediakan kunci pools dan ui yang sama tepat dengan bahasa Inggeris.

Ujian menguatkuasakannya merentas kesemua 33 berkas. Jika anda menambah rentetan UI baharu dalam bahasa Inggeris dan terlupa untuk menterjemahkannya dalam bahasa Ukraine, npm test menjadi merah dan memberitahu anda kunci mana yang hilang. Anda tidak boleh senyap menghantar bahasa terjemahan separuh.

Bahagian yang sukar: susun atur terminal

Bahasa yang berbeza menguji susun atur terminal dengan cara yang berbeza:

• Bahasa Jepun, Cina Ringkas dan Cina Tradisional Hong Kong menggunakan aksara Asia Timur Lebar / Lebar Penuh. vw() mengiranya sebagai dua lajur, dan wrap() memecahkan token tanpa ruang yang panjang supaya teks CJK kekal di dalam kad dan kotak.
• Hindi dan Kannada menggunakan tanda gabungan bukan jarak/lampiran (Mn / Me), seperti matras dan virama. vw() mengiranya sebagai lajur sifar supaya ia tidak mengembang lebar yang diukur.
• box() membalut setiap garisan badan sebelum mengalasnya, jadi sepanduk yang diterjemahkan panjang tidak lagi boleh menembusi sempadan.
• Setiap bundle menetapkan sentenceEnd dan listSep (contohnya . / 。, , / 、) supaya ayat yang digabungkan oleh penjana dibaca secara semula jadi.

Apabila anda menambah bahasa, rentetan pengepala kad (cardSubtitle, cardMeta, cardFooter) mesti masih muat ≤ 60 lajur kelihatan. Set Arab, Parsi, Ibrani dan Urdu meta.dir: 'rtl'. Output tidak mengandungi kawalan bidi secara lalai, kerana sesetengah terminal menjadikannya sebagai label berkotak. LOCKEDIN_BIDI=on secara eksplisit membolehkan pengasingan seimbang selepas membalut terminal yang diketahui menyokongnya, mengekalkan ANSI, arahan ASCII dan susunan salin/tampal logik. Output yang boleh diakses sentiasa mengalih keluar kawalan tersebut. Tanpa ikut serta, pesanan campuran RTL/LTR mungkin kurang sofistikated; jangan sekali-kali menyiasat atau membuat kesimpulan sokongan.

Bahagian licik: tatabahasa sekitar input pengguna mentah

Sesetengah templat UI bercantum dalam klausa pengguna mentah dengan ruang letak seperti {cap}. Jangan terjemahkan slot-untuk-slot tersebut. Ayat mesti kekal gramatis apabila pemegang tempat ialah frasa yang ditaip pengguna, bukan kata nama yang kemas.

Pepijat amaran sebenar: templat Jepun yang meletakkan は langsung selepas {cap} boleh salah bunyi bila {cap} ialah klausa penuh. Pembaikan bukan "terjemah lebih keras"; ia adalah untuk menstruktur semula templat (contohnya, menambah penama atau mengalihkan pemegang tempat) supaya input pengguna sewenang-wenangnya masih sesuai.

✅ Cuba dengan ejen anda — tambahkan bahasa

Latihan ini masih berfungsi dengan cara yang sama. Pilih bahasa yang anda boleh semak kewarasan (atau minta ejen) dan pandunya dari hujung ke hujung. Tulis spec dahulu:

Tambah bahasa Denmark (da). Buat src/content/da.js sebagai bundle { meta, pools, ui } dengan kunci yang sama seperti bahasa Inggeris, dan terjemahkan setiap entri (kira-kira 25 item bagi setiap pool kandungan serta semua rentetan UI). Daftarkan da dalam BUNDLES di src/lockedin.js. --lang da dan locale da-* mesti memilihnya. Pastikan rentetan pengepala kad mematuhi had lebar. npm test mesti kekal hijau, dan tambah invarian bahasa Denmark serta ujian pengesanan yang meniru ujian bahasa sedia ada.

Kemudian jalankan gelung dari Bab 3–4:

1. Rancang dahulu. "Sebelum menulis kod, beritahu saya fail yang akan anda ubah dan cara anda mengekalkan pariti utama dengan bahasa Inggeris."
2. Ujian dahulu. "Tambah ujian yang gagal: da pengesanan, pariti utama untuk da, dan invarian pantulan/sambung Denmark. Jangan buat berkas itu lagi."
3. Laksanakan. "Sekarang buat src/content/da.js dengan menterjemah kunci himpunan sedia ada untuk kunci, daftarkannya dan buat ujian lulus. Sahaja pick/shuffle secara rawak."
4. Pintu + semakan. Jalankan npm test, kemudian lockedin --lang da post — dan baca perbezaannya: adakah setiap kunci diterjemahkan? Adakah sempadan kad masih sejajar? Adakah templat dengan {cap} menerima klausa pengguna mentah?

Latihan memanaskan badan yang lebih kecil jika keseluruhan bahasa terlalu banyak:

• "Tambah satu lagi TAGLINE kepada kesemua 33 himpunan bahasa, mengekalkan kiraan yang sama."
• "Periksa sama ada Kannada cardFooter ialah ≤ 60 lajur yang boleh dilihat dan terangkan cara penggabungan markah diukur."
• "Tunjukkan saya ujian yang akan gagal jika saya memadamkan a ui kunci daripada ja.js."

---

Ke mana hendak pergi seterusnya

• Skim src/content/es.js — ia masih merupakan templat mesra untuk berkas baharu.
• Baca semula docs/HANDOFF.md → "Menambah bahasa".
• Nikmati jenaka berbilang bahasa dalam Rujukan Perintah.

Itu tutorial penuh. Anda kini boleh mengarahkan ejen AI untuk membina ciri dan menyetempatkannya di belakang pintu ujian — dalam 33 bahasa dan bersedia untuk lebih banyak lagi. Setuju? 👇