Tutorial 5 Localization tl

Tutorial 5 · Lokalisasyon (i18n)

🌎 Wika: Tagalog (tl) — tingnan ang lahat ng 33 wika

Layunin: maunawaan kung paano nagsasalita ang LockedIn CLI ng 33 wika — at magsanay sa pagdidirekta sa ahente upang magdagdag ng isa pa. Napakagandang gawain para sa ahente ang localization: sapat itong mekanikal upang italaga, ngunit may tunay itong mga hadlang (test gate, mga panuntunan sa layout, at pagsusuri sa gramatika) na nagtuturo sa iyong mag-review.

← Nakaraan: Tutorial 4 Prompting & Reviewing · Bumalik sa Home

---

Ano ang ibig sabihin ng "localized" dito

Patakbuhin ang CLI sa Spanish, Hindi, Japanese, Simplified Chinese, o anumang naipadalang wika at lahat ay nagbabago — ang splash, help table, bawat output ng command, ang chat session, maging ang legal na fine print. Hindi lamang ang mga biro: ang buong nakikitang ibabaw.

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

Ang wika ay autodetected sa startup, nalutas sa priority order:

1. ang --lang flag (--lang tl, --lang=fr, -l ja)
2. ang LOCKEDIN_LANG environment variable
3. ang locale mo (LC_ALL / LC_MESSAGES / LANG, pagkatapos ang OS/runtime locale)
4. English bilang fallback

Karaniwang ginagamit ng normalizeLang() ang pangunahing subtag ng locale. Ibig sabihin, pinipili ng de-DE ang de, ngunit hindi aksidenteng nagiging tl ang tlh; sadyang minamapa sa Tagalog (tl) ang mga tunay na alias na fil at tgl, sa no ang Norwegian na nb at nn, sa id ang lumang Indonesian code na in, at sa he ang lumang Hebrew code na iw. Pinananatili ang dalawang regional code sa halip na tiklupin sa pangunahing subtag: pinipili ng pt-BR/pt_BR ang canonical regional code, samantalang nananatiling backward-compatible na Brazilian Portuguese bundle ang generic na pt (parehong Brazilian Portuguese at magkapareho ang pool/UI); pinananatili naman ng en-SG/en_SG ang Singlish (habang English ang generic na en). Ganoon din ang Hong Kong Traditional Chinese: pinipili ng zh-HK, zh_HK.UTF-8, at zh-Hant-HK ang zh-HK, samantalang Simplified Chinese (zh) ang pinipili ng generic na zh at mga mainland tag.

Paglipat habang tumatakbo — ang /language panel. Noon pa man ay maaaring magsimula ang CLI sa ibang wika (--lang, LOCKEDIN_LANG); ngayon ay maaari ka ring lumipat sa gitna ng session. I-type ang /language (mga alias: /lang at /languages) upang ilista ang lahat ng 33 wika ayon sa code, bawat isa sa sarili nitong script; inililipat ng /language el ang natitirang session. Ang mahalaga ay ang escape hatch: pagkatapos lumipat, muling iginuguhit ang screen sa bagong wika at pagkatapos, sa wikang iniwan mo, ipi-print ang eksaktong paraan pabalik — /language en ngayon, lockedin --lang en sa susunod — kaya hindi ka mai-stranded kapag aksidenteng napunta sa 日本語 o ಕನ್ನಡ. (Lumipat nang dalawang beses at iaalok din ang wikang nakasaad sa LOCKEDIN_LANG.) Hindi nagbabago ang --lang at LOCKEDIN_LANG. Tulad ng /a11y, tunay itong kapaki-pakinabang at hindi bahagi ng satire.

Ang ideya: mga bundle ng wika

Ang lahat ng naisasalin na teksto ay nasa mga bundle, isa sa bawat wika, bawat isa ay may hugis:

{ meta: { lang: 'tl', name: 'Tagalog', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Densidad ng buzzwords: ', /* mga label, heading */ } }

• pools ay ang mga hanay ng nilalaman (ang mga biro) na nakilala mo sa Kabanata 2.
• ui ay ang mga chrome string: mga label, heading, at maliliit na template.

English ang reference bundle sa src/lockedin.js; nasa src/content/*.js ang iba pang 32 bundle module: 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, at zh-HK (pt-BR ay muling gumagamit ng pool/UI ng pt ngunit hiwalay na nakarehistro). Nakarehistro ang bawat isa sa BUNDLES; binubuo ang SUPPORTED_LANGS mula sa mga key na iyon, at ini-print ng renderHelp() ang nabuong listahan ng code. Walang UI bundle na nagha-hardcode ng listahan.

setLang('fr');       // ituro ang aktibong wika sa French bundle
// L = mga aktibong pool, U = aktibong UI
pick(L.HOOKS)        // isang French hook
U.buzzwordDensity    // "Densité de jargon : "

Dahil nagbabasa ang bawat nag-render L at U (hindi kailanman isang hardcoded string), setLang nag-iisa ang nagbabago sa buong karanasan. Iyan ang buong trick.

Ang safety net: key parity

Narito ang invariant na ginagawang ligtas ang pagdaragdag ng wika:

Dapat ilantad ng bawat bundle ang eksaktong parehong pools at ui key tulad ng English.

Isang pagsubok ang nagpapatupad nito sa lahat ng 33 bundle. Kung nagdagdag ka ng bagong string ng UI sa English at nakalimutan mong isalin ito sa Ukrainian, npm test Pula at sasabihin sa iyo kung aling susi ang nawawala. Hindi ka maaaring silently magpadala ng kalahating pagsasalin na wika.

Ang mahirap na bahagi: layout ng terminal

Sinusubok ng iba't ibang wika ang terminal layout sa iba't ibang paraan:

• Japanese, Simplified Chinese, at Hong Kong Traditional Chinese ay gumagamit ng East Asian Wide / Fullwidth na mga character. vw() binibilang ang mga iyon bilang dalawang hanay, at wrap() hard-break ang mahahabang spaceless token para manatili ang CJK text sa loob ng mga card at box.
• Hindi at Kannada ay gumagamit ng nonspacing/enclosing combining marks (Mn / Me), gaya ng matras at viramas. vw() binibilang ang mga iyon bilang mga zero na hanay upang hindi sila lumaki sa sinusukat na lapad.
• box() binabalot ang bawat linya ng katawan bago ito i-padding, kaya ang isang mahabang isinalin na banner ay hindi na makakalusot sa hangganan.
• Ang bawat bundle ay nagtatakda sentenceEnd at listSep (halimbawa . / 。, , / 、) kaya natural na nababasa ang mga pangungusap na binubuo ng generator.

Kapag nagdagdag ka ng wika, card header string (cardSubtitle, cardMeta, cardFooter) ay dapat magkasya pa rin ≤ 60 nakikitang column. Arabic, Persian, Hebrew, at Urdu set meta.dir: 'rtl'. Ang output ay hindi naglalaman ng mga kontrol ng bidi bilang default, dahil ang ilang mga terminal ay nagre-render sa kanila bilang mga naka-box na label. LOCKEDIN_BIDI=on tahasang nagbibigay-daan sa mga balanseng paghihiwalay pagkatapos ng pagbabalot para sa mga terminal na kilala na sumusuporta sa mga ito, na pinapanatili ang ANSI, ASCII na mga utos, at lohikal na pagkopya/pag-paste ng pagkakasunud-sunod. Palaging inaalis ng accessible na output ang mga kontrol na iyon. Kung wala ang pag-opt-in, ang pinaghalong pag-order ng RTL/LTR ay maaaring hindi gaanong sopistikado; huwag kailanman magsiyasat o maghinuha ng suporta.

Ang palihim na bahagi: grammar sa paligid ng hilaw na input ng user

Ang ilang mga template ng UI ay nag-splice sa mga raw user clause na may mga placeholder tulad ng {cap}. Huwag isalin ang mga slot-for-slot na iyon. Dapat manatiling gramatikal ang pangungusap kapag ang placeholder ay isang pariralang na-type ng user, hindi isang maayos na pangngalan.

Isang tunay na pag-iingat na bug: mga Japanese na template na naglalagay は direkta pagkatapos {cap} maaaring mali ang tunog kapag {cap} ay isang buong sugnay. Ang pag-aayos ay hindi "isalin nang mas mahirap"; ito ay ang muling pagsasaayos ng template (halimbawa, magdagdag ng nominalizer o ilipat ang placeholder) upang magkasya pa rin ang arbitrary na input ng user.

✅ Subukan ito sa iyong ahente — magdagdag ng wika

Ang ehersisyo na ito ay gumagana pa rin nang eksakto sa parehong paraan. Pumili ng isang wika na maaari mong suriin sa katinuan (o hilingin sa ahente), at himukin ito ng end-to-end. Isulat muna ang spec:

Idagdag ang Danish (da). Lumikha ng src/content/da.js bilang { meta, pools, ui } bundle na may parehong key gaya ng English, at isalin ang bawat entry (humigit-kumulang 25 item sa bawat content pool at lahat ng UI string). Irehistro ang da sa BUNDLES sa src/lockedin.js. Dapat piliin ito ng --lang da at locale na da-*. Panatilihin ang mga card header string sa loob ng width limit. Dapat manatiling berde ang npm test, at magdagdag ng Danish invariant at detection test na katulad ng mga kasalukuyang localized test.

Pagkatapos ay patakbuhin ang loop mula sa Kabanata 3–4:

1. Magplano muna. "Bago magsulat ng code, sabihin sa akin ang mga file na babaguhin mo at kung paano mo papanatilihin ang key parity sa English."
2. Mga pagsubok muna. "Magdagdag ng mga bagsak na pagsubok: da detection, key parity para sa da, at isang Danish na reflect/connect invariant. Huwag mo pang likhain ang bundle."
3. Ipatupad. "Ngayon lumikha src/content/da.js sa pamamagitan ng pagsasalin ng umiiral nang bundle key para sa susi, irehistro ito, at gawin ang mga pagsubok na pumasa. Tanging pick/shuffle para sa randomness."
4. Gate + review. Patakbuhin ang npm test, pagkatapos ang lockedin --lang da post — at basahin ang diff: naisalin ba ang bawat key? Naka-align pa rin ba ang mga border ng card? Gumagana ba ang mga template na may {cap} kapag raw user clause ang ipinasok?

Mas maliliit na pagsasanay sa pag-init kung ang isang buong wika ay masyadong marami:

• "Magdagdag ka pa ng isa TAGLINE sa lahat ng 33 bundle ng wika, pinapanatili ang mga bilang na pantay."
• "Suriin kung ang Kannada cardFooter ay ≤ 60 nakikitang column at ipaliwanag kung paano nasusukat ang pinagsamang mga marka."
• "Ipakita sa akin ang pagsubok na mabibigo kung tatanggalin ko ang a ui susi mula sa ja.js."

---

Saan susunod na pupuntahan

• Skim src/content/es.js — isa pa rin itong friendly na template para sa isang bagong bundle.
• Basahin muli docs/HANDOFF.md → "Pagdaragdag ng isang wika".
• Tangkilikin ang mga multilingguwal na biro sa Command Reference.

Iyan ang buong tutorial. Maaari mo na ngayong idirekta ang isang ahente ng AI na bumuo ng mga feature at i-localize ang mga ito sa likod ng isang test gate — sa 33 wika at handa na para sa higit pa. Sang-ayon? 👇