Tutorial 5 Localization sv

Tutorial 5 · Lokalisering (i18n)

Mål: förstå hur LockedIn CLI talar 33 språk — och öva på att dirigera en agent att lägga till ytterligare ett. Lokalisering är en fantastisk agentuppgift: den är tillräckligt mekanisk för att delegera, men har riktiga begränsningar (en testgrind, layoutregler, grammatikgranskning) som lär dig att granska.

← Föregående: Tutorial 4 Prompta och granska · Tillbaka till Home

---

Vad "lokaliserad" betyder här

Kör CLI:n på spanska, hindi, japanska, förenklad kinesiska, eller något annat levererat språk, och allt förändras — splashen, hjälptabellen, utdatan för varje kommando, chattsessionen, till och med det juridiska finstilta. Inte bara skämten: hela den synliga ytan.

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

Språket autodetekteras vid start, avgjort i prioritetsordning:

1. --lang-flaggan (--lang sv, --lang=fr, -l ja)
2. LOCKEDIN_LANG-miljövariabeln
3. din locale (LC_ALL / LC_MESSAGES / LANG, sedan operativsystemets/körtidens locale)
4. engelska, som reserv

normalizeLang() använder normalt localens primära subtagg. Det betyder att de-DE väljer de, men tlh blir inte av misstag tl; de riktiga aliasen fil och tgl mappas avsiktligt till tagalog (tl), norska nb och nn mappas till no, den historiska indonesiska koden in mappas till id, och den historiska hebreiska koden iw mappas till he. Två regionala koder bevaras ordagrant istället för att vikas till sin primära subtagg: pt-BR/pt_BR väljer den kanoniska regionala koden medan generisk pt förblir det bakåtkompatibla brasilianska portugisiska paketet (båda är brasiliansk portugisiska och delar samma pooler/UI), och en-SG/en_SG behåller singlish (generisk en förblir engelska). Hongkongs traditionella kinesiska är samma sorts undantag: zh-HK, zh_HK.UTF-8, och zh-Hant-HK väljer zh-HK, medan generisk zh och fastlandstaggar väljer förenklad kinesiska (zh).

Att byta mitt i flykten — /language-panelen. CLI:n kunde alltid starta på ett annat språk (--lang, LOCKEDIN_LANG); nu kan du byta mitt i sessionen. Skriv /language (alias /lang och /languages) för att lista alla 33 språken efter kod, vart och ett i sitt eget skriftsystem; /language el byter för resten av sessionen. Poängen är nödutgången: efter ett byte ritas det om på det nya språket och skriver sedan, på språket du precis lämnade, den exakta vägen tillbaka — /language en nu, lockedin --lang en nästa gång — så att man av misstag hamna i 日本語 eller ಕನ್ನಡ aldrig strandar dig. (Byt två gånger, så erbjuds även språket din LOCKEDIN_LANG namnger.) --lang och LOCKEDIN_LANG är oförändrade. Precis som /a11y är det här ett uppriktigt verktyg, inte en del av satiren.

Idén: språkpaket

All översättningsbar text bor i paket, ett per språk, var och en formad så här:

{ meta: { lang: 'sv', name: 'Svenska', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Buzzword-täthet: ', /* etiketter, rubriker */ } }

• pools är innehållsarrayerna (skämten) du mötte i kapitel 2.
• ui är gränssnittssträngarna: etiketter, rubriker, och små mallar.

Engelska är referenspaketet inuti src/lockedin.js; de andra 32 paketmodulerna 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, och zh-HK (pt-BR återanvänder pts pooler/UI men är registrerad separat). Varje är registrerad i BUNDLES; SUPPORTED_LANGS genereras från dessa nycklar, och renderHelp() skriver ut den genererade kodlistan. Inget UI-paket hårdkodar listan.

setLang('fr');       // peka det aktiva språket mot det franska paketet
// L = aktiva pooler, U = aktiv ui
pick(L.HOOKS)        // en fransk krok
U.buzzwordDensity    // "Densité de jargon : "

Eftersom varje renderare läser L och U (aldrig en hårdkodad sträng), ändrar setLang ensamt hela upplevelsen. Det är hela tricket.

Skyddsnätet: nyckelparitet

Här är invarianten som gör det säkert att lägga till ett språk:

Varje paket måste exponera exakt samma pools- och ui-nycklar som engelska.

Ett test upprätthåller det här över alla 33 paketen. Om du lägger till en ny UI-sträng på engelska och glömmer att översätta den på ukrainska, går npm test rött och berättar vilken nyckel som saknas. Du kan inte tyst leverera ett halvöversatt språk.

Den svåra delen: terminallayout

Språk belastar terminallayouten på olika sätt:

• Japanska, förenklad kinesiska, och Hongkongs traditionella kinesiska använder East Asian Wide / Fullwidth-tecken. vw() räknar dessa som två kolumner, och wrap() hård-bryter långa mellanslagslösa tokens så att CJK-text stannar innanför kort och rutor.
• Hindi och kannada använder icke-mellanslags-/omslutande kombinationsmärken (Mn / Me), som matror och viramas. vw() räknar dessa som noll kolumner så att de inte blåser upp uppmätt bredd.
• box() bryter varje kroppsrad innan den polstrar den, så att en lång översatt banderoll inte längre kan bryta igenom kanten.
• Varje paket sätter sentenceEnd och listSep (till exempel . / 。, , / 、) så att generatorkomponerade meningar låter naturliga.

När du lägger till ett språk måste kortrubrikssträngar (cardSubtitle, cardMeta, cardFooter) fortfarande passa inom ≤ 60 synliga kolumner. Arabiska, persiska, hebreiska och urdu sätter meta.dir: 'rtl'. Utdata innehåller inga bidi-kontroller som standard, eftersom vissa terminaler renderar dem som inramade etiketter. LOCKEDIN_BIDI=on aktiverar explicit balanserade isolat efter radbrytning för terminaler kända för att stödja dem, och bevarar ANSI, ASCII-kommandon och logisk kopiera/klistra-in-ordning. Tillgänglig utdata tar alltid bort dessa kontroller. Utan detta val kan blandad RTL/LTR-ordning vara mindre sofistikerad; stöd sonderas eller härleds aldrig.

Den lömska delen: grammatik runt rå användarindata

Vissa UI-mallar splitsar in råa användarsatser med platshållare som {cap}. Översätt dem inte plats för plats. Meningen måste förbli grammatisk när platshållaren är en fras användaren skrev, inte ett prydligt substantiv.

En riktig varnande bugg: japanska mallar som sätter は direkt efter {cap} kan låta fel när {cap} är en fullständig sats. Fixet är inte "översätt hårdare"; det är att omstrukturera mallen (till exempel lägga till en nominalisering eller flytta platshållaren) så att godtycklig användarindata fortfarande passar.

✅ Testa det med din agent — lägg till ett språk

Den här övningen fungerar fortfarande på exakt samma sätt. Välj ett språk du kan kontrollera (eller be agenten göra det), och kör det från början till slut. Skriv specifikationen först:

Lägg till danska (da). Skapa src/content/da.js som ett { meta, pools, ui }-paket med samma nycklar som engelska, genom att översätta varje post (innehållspooler på ~25 vardera, alla UI-strängar). Registrera da i BUNDLES i src/lockedin.js. --lang da och en da-*-locale måste välja den. Håll kortrubrikerna inom breddgränsen. npm test måste förbli grönt, och lägg till danska invariant- och detekteringstester som speglar de befintliga lokaliserade.

Kör sedan slingan från kapitel 3–4:

1. Plan först. "Innan du skriver kod, berätta vilka filer du kommer ändra och hur du kommer behålla nyckelparitet med engelska."
2. Tester först. "Lägg till misslyckade tester: da-detektering, nyckelparitet för da, och en dansk reflect/connect-invariant. Skapa inte paketet än."
3. Implementera. "Skapa nu src/content/da.js genom att översätta ett befintligt paket nyckel för nyckel, registrera det, och få testerna att passera. Endast pick/shuffle för slumpmässighet."
4. Grind + granskning. npm test, sedan lockedin --lang da post — och läs diffen: översattes varje nyckel? Är kortkanterna fortfarande i linje? Överlever mallar med {cap} råa användarsatser?

Mindre uppvärmningsövningar om ett helt språk är för mycket:

• "Lägg till en till TAGLINE i alla 33 språkpaket, och håll antalet lika."
• "Kontrollera om kannadans cardFooter är ≤ 60 synliga kolumner och förklara hur kombinationsmärkena mättes."
• "Visa mig testet som skulle misslyckas om jag tog bort en ui-nyckel från ja.js."

---

Vart du ska gå härnäst

• Bläddra genom src/content/es.js — det är fortfarande en vänlig mall för ett nytt paket.
• Läs om docs/HANDOFF.md → "Adding a language".
• Njut av de flerspråkiga skämten i Command Reference.

Det är hela handledningen. Du kan nu dirigera en AI-agent att bygga funktioner och lokalisera dem bakom en testgrind — på 33 språk och redo för fler. Håller du med? 👇