Tutorial 5 Localization no

Tutorial 5 · Lokalisering (i18n)

Mål: forstå hvordan LockedIn CLI snakker 33 språk — og øve på å dirigere en agent til å legge til enda ett. Lokalisering er en fantastisk agentoppgave: den er mekanisk nok til å delegere, men har ekte begrensninger (en testport, oppsettregler, grammatikkgjennomgang) som lærer deg å gjennomgå.

← Forrige: Tutorial 4 Prompting og gjennomgang · Tilbake til Home

---

Hva "lokalisert" betyr her

Kjør CLI-en på spansk, hindi, japansk, forenklet kinesisk, eller et hvilket som helst levert språk, og alt endrer seg — splashen, hjelpetabellen, utdataen til hver kommando, chat-økten, til og med den juridiske finskriften. Ikke bare vitsene: hele den synlige overflaten.

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

Språket autodetekteres ved oppstart, løst i prioritert rekkefølge:

1. --lang-flagget (--lang no, --lang=fr, -l ja)
2. LOCKEDIN_LANG-miljøvariabelen
3. localen din (LC_ALL / LC_MESSAGES / LANG, deretter OS/kjøretids-localen)
4. engelsk, som fallback

normalizeLang() bruker normalt localens primære subtag. Det betyr at de-DE velger de, men tlh blir ikke ved et uhell til tl; de ekte aliasene fil og tgl kartlegges bevisst til tagalog (tl), norsk nb og nn kartlegges til no, det historiske indonesiske in kartlegges til id, og det historiske hebraiske iw kartlegges til he. To regionale koder bevares ordrett i stedet for å foldes til sin primære subtag: pt-BR/pt_BR velger den kanoniske regionale koden mens generisk pt forblir den bakoverkompatible brasiliansk-portugisiske pakken (begge er brasiliansk portugisisk og deler de samme poolene/UI-en), og en-SG/en_SG beholder singlish (generisk en forblir engelsk). Hongkong tradisjonell kinesisk er samme type unntak: zh-HK, zh_HK.UTF-8, og zh-Hant-HK velger zh-HK, mens generisk zh og fastlandstagger velger forenklet kinesisk (zh).

Bytte midtveis — /language-panelet. CLI-en kunne alltid starte på et annet språk (--lang, LOCKEDIN_LANG); nå kan du bytte midt i økten. Skriv /language (aliaser /lang og /languages) for å liste alle 33 språkene etter kode, hver i sin egen skrift; /language el bytter for resten av økten. Poenget er nødutgangen: etter et bytte tegner den seg på nytt på det nye språket og skriver deretter, på språket du nettopp forlot, den eksakte veien tilbake — /language en nå, lockedin --lang en neste gang — slik at det å ved et uhell havne i 日本語 eller ಕನ್ನಡ aldri strander deg. (Bytt to ganger, så tilbys også språket din LOCKEDIN_LANG navngir.) --lang og LOCKEDIN_LANG er uendret. Som /a11y er dette et oppriktig verktøy, ikke en del av satiren.

Ideen: språkpakker

All oversettbar tekst bor i pakker, én per språk, hver formet slik:

{ meta: { lang: 'no', name: 'Norsk', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Buzzword-tetthet: ', /* etiketter, overskrifter */ } }

• pools er innholdstabellene (vitsene) du møtte i kapittel 2.
• ui er grensesnittstrengene: etiketter, overskrifter, og små maler.

Engelsk er referansepakken inne i src/lockedin.js; de andre 32 pakkemodulene bor i 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, og zh-HK (pt-BR gjenbruker pts pooler/UI men er registrert separat). Hver er registrert i BUNDLES; SUPPORTED_LANGS genereres fra disse nøklene, og renderHelp() skriver ut den genererte kodelisten. Ingen UI-pakke hardkoder listen.

setLang('fr');       // pek det aktive språket til den franske pakken
// L = aktive pooler, U = aktiv ui
pick(L.HOOKS)        // en fransk krok
U.buzzwordDensity    // "Densité de jargon : "

Fordi hver renderer leser L og U (aldri en hardkodet streng), endrer setLang alene hele opplevelsen. Det er hele trikset.

Sikkerhetsnettet: nøkkelparitet

Her er invarianten som gjør det trygt å legge til et språk:

Hver pakke må eksponere nøyaktig de samme pools- og ui-nøklene som engelsk.

En test håndhever dette på tvers av alle 33 pakkene. Hvis du legger til en ny UI-streng på engelsk og glemmer å oversette den på ukrainsk, går npm test rødt og forteller deg hvilken nøkkel som mangler. Du kan ikke stille sende et halvt oversatt språk.

Den vanskelige delen: terminaloppsett

Språk belaster terminaloppsettet på forskjellige måter:

• Japansk, forenklet kinesisk, og Hongkong tradisjonell kinesisk bruker East Asian Wide / Fullwidth-tegn. vw() teller disse som to kolonner, og wrap() hard-bryter lange mellomromsløse tokens slik at CJK-tekst holder seg innenfor kort og bokser.
• Hindi og kannada bruker ikke-mellomrom-/omsluttende kombinasjonsmerker (Mn / Me), som matraer og viramaer. vw() teller disse som null kolonner slik at de ikke blåser opp målt bredde.
• box() bryter hver kroppslinje før den padder den, slik at et langt oversatt banner ikke lenger kan bryte gjennom rammen.
• Hver pakke setter sentenceEnd og listSep (for eksempel . / 。, , / 、) slik at generator-komponerte setninger leses naturlig.

Når du legger til et språk, må kortoverskriftstrenger (cardSubtitle, cardMeta, cardFooter) fortsatt passe innenfor ≤ 60 synlige kolonner. Arabisk, persisk, hebraisk og urdu setter meta.dir: 'rtl'. Utdata inneholder ingen bidi-kontroller som standard, fordi noen terminaler rendrer dem som boksede etiketter. LOCKEDIN_BIDI=on aktiverer eksplisitt balanserte isolater etter bryting for terminaler kjent for å støtte dem, og bevarer ANSI, ASCII-kommandoer og logisk kopier/lim-inn-rekkefølge. Tilgjengelig utdata fjerner alltid disse kontrollene. Uten dette valget kan blandet RTL/LTR-rekkefølge være mindre sofistikert; støtte sonderes eller utledes aldri.

Den lure delen: grammatikk rundt rå brukerinndata

Noen UI-maler splitter inn rå brukersetninger med plassholdere som {cap}. Ikke oversett dem plass for plass. Setningen må forbli grammatisk når plassholderen er en frase brukeren skrev, ikke et pent substantiv.

En ekte advarende feil: japanske maler som setter は rett etter {cap} kan høres galt ut når {cap} er en full setning. Fiksen er ikke "oversett hardere"; det er å restrukturere malen (for eksempel legge til en nominalisering eller flytte plassholderen) slik at vilkårlig brukerinndata fortsatt passer.

✅ Prøv det med agenten din — legg til et språk

Denne øvelsen fungerer fortsatt på nøyaktig samme måte. Velg et språk du kan sjekke (eller be agenten om det), og kjør det fra ende til annen. Skriv spesifikasjonen først:

Legg til dansk (da). Opprett src/content/da.js som en { meta, pools, ui }-pakke med de samme nøklene som engelsk, ved å oversette hver oppføring (innholdspooler på ~25 hver, alle UI-strenger). Registrer da i BUNDLES i src/lockedin.js. --lang da og en da-*-locale må velge den. Hold kortoverskrifter innenfor breddegrensen. npm test må forbli grønn, og legg til danske invariant- og deteksjonstester som speiler de eksisterende lokaliserte.

Kjør deretter sløyfen fra kapittel 3–4:

1. Plan først. "Før du skriver kode, fortell meg hvilke filer du vil endre og hvordan du vil beholde nøkkelparitet med engelsk."
2. Tester først. "Legg til feilende tester: da-deteksjon, nøkkelparitet for da, og en dansk reflect/connect-invariant. Ikke opprett pakken ennå."
3. Implementer. "Opprett nå src/content/da.js ved å oversette en eksisterende pakke nøkkel for nøkkel, registrer den, og få testene til å bestå. Bare pick/shuffle for tilfeldighet."
4. Port + gjennomgang. npm test, deretter lockedin --lang da post — og les diffen: ble hver nøkkel oversatt? Er kortrammene fortsatt på linje? Overlever maler med {cap} rå brukersetninger?

Mindre oppvarmingsøvelser hvis et helt språk er for mye:

• "Legg til én til TAGLINE i alle 33 språkpakkene, og hold antallet likt."
• "Sjekk om den kannadiske cardFooter er ≤ 60 synlige kolonner og forklar hvordan kombinasjonsmerkene ble målt."
• "Vis meg testen som ville feile hvis jeg slettet en ui-nøkkel fra ja.js."

---

Hvor du går videre

• Bla gjennom src/content/es.js — den er fortsatt en vennlig mal for en ny pakke.
• Les på nytt docs/HANDOFF.md → "Adding a language".
• Nyt de flerspråklige vitsene i Command Reference.

Det er hele veiledningen. Du kan nå dirigere en AI-agent til å bygge funksjoner og lokalisere dem bak en testport — på 33 språk og klar for flere. Enig? 👇