Tutorial 5 Localization fi

Tutorial 5 · Lokalisointi (i18n)

Tavoite: ymmärtää, kuinka LockedIn CLI puhuu 33 kieltä — ja harjoitella agentin ohjaamista lisäämään vielä yksi. Lokalisointi on erinomainen agenttitehtävä: se on tarpeeksi mekaaninen delegoitavaksi, mutta sillä on todellisia rajoitteita (testiportti, asettelusäännöt, kielioppitarkistus), jotka opettavat sinua arvioimaan.

← Edellinen: Tutorial 4 Promptaus ja arviointi · Takaisin Home

---

Mitä "lokalisoitu" tarkoittaa täällä

Aja CLI espanjaksi, hindiksi, japaniksi, yksinkertaistetuksi kiinaksi tai millä tahansa toimitetulla kielellä, ja kaikki muuttuu — splash, ohjetaulukko, jokaisen komennon tuloste, keskustelusessio, jopa oikeudellinen pieni präntti. Ei vain läpät: koko näkyvä pinta.

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

Kieli tunnistetaan automaattisesti käynnistyksessä, ratkaistuna prioriteettijärjestyksessä:

1. --lang-lippu (--lang fi, --lang=fr, -l ja)
2. LOCKEDIN_LANG-ympäristömuuttuja
3. localesi (LC_ALL / LC_MESSAGES / LANG, sitten käyttöjärjestelmän/ ajoympäristön locale)
4. englanti, varajärjestelmänä

normalizeLang() käyttää normaalisti localen ensisijaista alitunnistetta. Se tarkoittaa, että de-DE valitsee de:n, mutta tlh ei vahingossa muutu tl:ksi; oikeat aliakset fil ja tgl kartoitetaan tarkoituksella tagalogiin (tl), norjan nb ja nn kartoitetaan no:hon, vanha indonesian koodi in kartoitetaan id:hen, ja vanha heprean koodi iw kartoitetaan he:hen. Kaksi alueellista koodia säilytetään sellaisenaan sen sijaan, että ne taitettaisiin ensisijaiseen alitunnisteeseensa: pt-BR/pt_BR valitsevat kanonisen alueellisen koodin, kun taas yleinen pt pysyy taaksepäin yhteensopivana brasilianportugalin pakettina (molemmat ovat brasilianportugalia ja jakavat samat poolit/UI:n), ja en-SG/en_SG säilyttävät singlishin (yleinen en pysyy englantina). Hongkongin perinteinen kiina on samanlainen poikkeus: zh-HK, zh_HK.UTF-8 ja zh-Hant-HK valitsevat zh-HK:n, kun taas yleinen zh ja mannerkiinan tagit valitsevat yksinkertaistetun kiinan (zh).

Vaihtaminen kesken lennon — /language-paneeli. CLI pystyi aina käynnistymään toisella kielellä (--lang, LOCKEDIN_LANG); nyt voit vaihtaa kesken session. Kirjoita /language (aliakset /lang ja /languages) listataksesi kaikki 33 kieltä koodin mukaan, kukin omalla kirjoitusjärjestelmällään; /language el vaihtaa lopuksi sessioksi. Pointti on hätäuloskäynti: vaihdon jälkeen se piirtää uudelleen uudella kielellä ja sitten, kielellä, jonka juuri jätit, tulostaa tarkan tien takaisin — /language en nyt, lockedin --lang en seuraavalla kerralla — joten vahingossa 日本語:iin tai ಕನ್ನಡ:aan päätyminen ei koskaan jätä sinua jumiin. (Vaihda kahdesti, niin myös LOCKEDIN_LANG:si nimeämä kieli tarjotaan.) --lang ja LOCKEDIN_LANG pysyvät muuttumattomina. Kuten /a11y, tämä on vilpitön apuväline, ei osa satiiria.

Idea: kielipaketit

Kaikki käännettävä teksti asuu paketeissa, yksi kieltä kohden, kukin tämän muotoisena:

{ meta: { lang: 'fi', name: 'Suomi', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Muotisanatiheys: ', /* etiketit, otsikot */ } }

• pools ovat sisältötaulukot (läpät), jotka näit luvussa 2.
• ui ovat käyttöliittymätekstit: etiketit, otsikot ja pienet mallit.

Englanti on referenssipaketti src/lockedin.js:n sisällä; muut 32 pakettimoduulia asuvat src/content/*.js:ssä: 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 ja zh-HK (pt-BR käyttää uudelleen pt:n pooleja/UI:ta mutta rekisteröidään erikseen). Jokainen rekisteröidään BUNDLES:iin; SUPPORTED_LANGS generoidaan noista avaimista, ja renderHelp() tulostaa tuon generoidun koodilistan. Mikään UI-paketti ei koodaa listaa kiinteästi.

setLang('fr');       // osoita aktiivinen kieli ranskalaiseen pakettiin
// L = aktiiviset poolit, U = aktiivinen ui
pick(L.HOOKS)        // ranskalainen koukku
U.buzzwordDensity    // "Densité de jargon : "

Koska jokainen renderöijä lukee L:n ja U:n (ei koskaan kovakoodattua merkkijonoa), pelkkä setLang muuttaa koko kokemuksen. Se on koko temppu.

Turvaverkko: avainpariteetti

Tässä on invariantti, joka tekee kielen lisäämisestä turvallista:

Jokaisen paketin täytyy paljastaa täsmälleen samat pools- ja ui-avaimet kuin englannin.

Testi pakottaa tämän kaikissa 33 paketissa. Jos lisäät uuden UI-merkkijonon englanniksi ja unohdat kääntää sen ukrainaksi, npm test menee punaiseksi ja kertoo, mikä avain puuttuu. Et voi hiljaa julkaista puoliksi käännettyä kieltä.

Vaikea osa: terminaaliasettelu

Kielet rasittavat terminaaliasettelua eri tavoin:

• Japani, yksinkertaistettu kiina ja Hongkongin perinteinen kiina käyttävät East Asian Wide / Fullwidth -merkkejä. vw() laskee ne kahdeksi sarakkeeksi, ja wrap() katkaisee pitkät välilyönnittömät tokenit pakotetusti, jotta CJK-teksti pysyy korttien ja laatikoiden sisällä.
• Hindi ja kannada käyttävät ei-välilyönnillisiä/ympäröiviä yhdistäviä merkkejä (Mn / Me), kuten matroja ja viramoja. vw() laskee ne nollaksi sarakkeeksi, jotta ne eivät kasvata mitattua leveyttä.
• box() rivittää jokaisen leipätekstirivin ennen sen pehmustamista, joten pitkä käännetty banneri ei voi enää puhkaista reunusta.
• Jokainen paketti asettaa sentenceEnd- ja listSep-arvot (esimerkiksi . / 。, , / 、), jotta generaattorin kokoamat lauseet kuulostavat luonnollisilta.

Kun lisäät kielen, korttiotsikkomerkkijonojen (cardSubtitle, cardMeta, cardFooter) täytyy edelleen mahtua ≤ 60 näkyvään sarakkeeseen. Arabia, persia, heprea ja urdu asettavat meta.dir: 'rtl'. Tuloste ei sisällä bidi-ohjausmerkkejä oletuksena, koska jotkin terminaalit renderöivät ne laatikoituina etiketteinä. LOCKEDIN_BIDI=on ottaa nimenomaisesti käyttöön tasapainotetut eristeet rivityksen jälkeen terminaaleille, joiden tiedetään tukevan niitä, säilyttäen ANSI:n, ASCII-komennot ja loogisen kopioi/liitä-järjestyksen. Saavutettava tuloste poistaa ne aina. Ilman tätä valintaa sekoitettu RTL/LTR-järjestys voi olla vähemmän hienostunut; tukea ei koskaan tunnisteta tai pääteltynä.

Vilpillinen osa: kielioppi raa'an käyttäjäsyötteen ympärillä

Jotkin UI-mallit liittävät raakoja käyttäjälausekkeita paikanpitäjillä kuten {cap}. Älä käännä niitä paikka paikalta. Lauseen täytyy pysyä kieliopillisesti oikeana, kun paikanpitäjä on käyttäjän kirjoittama lauseke, ei siisti substantiivi.

Todellinen varoittava bugi: japanilaiset mallit, jotka laittavat は suoraan {cap}:n jälkeen, voivat kuulostaa väärältä, kun {cap} on täysi lauseke. Korjaus ei ole "käännä kovemmin"; se on mallin uudelleenrakentaminen (esimerkiksi lisäämällä substantivoija tai siirtämällä paikanpitäjä), jotta mielivaltainen käyttäjäsyöte silti sopii.

✅ Kokeile agenttisi kanssa — lisää kieli

Tämä harjoitus toimii täsmälleen samalla tavalla. Valitse kieli, jonka voit tarkistaa (tai pyydä agenttia tekemään niin), ja vie se läpi päästä päähän. Kirjoita spesifikaatio ensin:

Lisää tanska (da). Luo src/content/da.js { meta, pools, ui } -pakettina, jossa on samat avaimet kuin englannissa, kääntäen jokaisen merkinnän (sisältöpoolit ~25 kappaletta kutakin, kaikki UI-merkkijonot). Rekisteröi da BUNDLES:iin src/lockedin.js:ssä. --lang da:n ja da-*-localen täytyy valita se. Pidä korttiotsikot leveysrajan sisällä. npm test:n täytyy pysyä vihreänä, ja lisää tanskalaiset invariantti- ja tunnistustestit peilaten olemassa olevia lokalisoituja sellaisia.

Aja sitten silmukka luvuista 3–4:

1. Suunnitelma ensin. "Ennen koodin kirjoittamista, kerro mitkä tiedostot muutat ja miten pidät avainpariteetin englannin kanssa."
2. Testit ensin. "Lisää epäonnistuvat testit: da-tunnistus, avainpariteetti da:lle, ja tanskalainen reflect/connect-invariantti. Älä vielä luo pakettia."
3. Toteuta. "Luo nyt src/content/da.js kääntämällä olemassa oleva paketti avain avaimelta, rekisteröi se, ja saa testit läpäisemään. Vain pick/shuffle satunnaisuudelle."
4. Portti + arviointi. npm test, sitten lockedin --lang da post — ja lue diffi: käännettiinkö jokainen avain? Ovatko korttien reunat yhä linjassa? Selviävätkö {cap}:n sisältävät mallit raaoista käyttäjälausekkeista?

Pienempiä lämmittelyharjoituksia, jos koko kieli on liikaa:

• "Lisää yksi TAGLINE lisää kaikkiin 33 kielipakettiin, pitäen määrät samana."
• "Tarkista, onko kannadan cardFooter ≤ 60 näkyvää saraketta, ja selitä, miten yhdistävät merkit mitattiin."
• "Näytä minulle testi, joka epäonnistuisi, jos poistaisin ui-avaimen ja.js:stä."

---

Mihin mennä seuraavaksi

• Silmäile src/content/es.js — se on yhä ystävällinen malli uudelle paketille.
• Lue uudelleen docs/HANDOFF.md → "Adding a language".
• Nauti monikielisistä läpistä sivulla Command Reference.

Se on koko opetusohjelma. Voit nyt ohjata tekoälyagenttia rakentamaan ominaisuuksia ja lokalisoimaan niitä testiportin takana — 33 kielellä ja valmiina lisää varten. Samaa mieltä? 👇