Tutorial 5 Localization eu

Tutorial 5 · Lokalizazioa (i18n)

Helburua: ulertu nola hitz egiten dituen LockedIn CLIak 33 hizkuntza — eta praktikatu agente bat zuzentzen beste bat gehitzeko. Lokalizazioa agente-ataza bikaina da: nahikoa mekanikoa da eskuordetzeko, baina benetako murrizketak ditu (test-langa, diseinu-arauak, gramatika-berrikuspena) berrikusten irakasten dizutenak.

← Aurrekoa: 4 Prompt-ak eta berrikuspena · Itzuli Etxea

---

Zer esan nahi duen hemen "lokalizatua"-k

Exekutatu CLIa gaztelaniaz, hindiz, japonieraz, txinera sinplifikatuz edo bidalitako edozein hizkuntzatan eta dena aldatzen da — splasha, laguntza-taula, komando bakoitzaren irteera, txat-saioa, baita lege-letra txikia ere. Ez txantxak soilik: azalera ikusgai osoa.

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

Hizkuntza abioan automatikoki hautematen da, lehentasun-ordenan ebatzita:

1. --lang bandera (--lang eu, --lang=fr, -l ja)
2. LOCKEDIN_LANG ingurune-aldagaia
3. zure localea (LC_ALL / LC_MESSAGES / LANG, gero SE/exekuzio-denborako localea)
4. ingelesa, ordezko gisa

normalizeLang()-ek normalean localearen azpietiketa nagusia erabiltzen du. Horrek esan nahi du de-DE-k de hautatzen duela, baina tlh ez dela ustekabean tl bihurtzen; benetako fil eta tgl aliasak nahita mapatzen dira tagalogera (tl), norvegierazko nb eta nn no-ra mapatzen dira, aspaldiko indonesierazko in id-ra mapatzen da, eta aspaldiko hebreerazko iw he-ra mapatzen da. Bi eskualde-kode hitzez hitz gordetzen dira beren azpietiketa nagusira tolestu beharrean: pt-BR/pt_BR-k eskualde-kode kanonikoa hautatzen dute, pt generikoa atzeranzko bateragarritasuna duen Brasilgo portugesaren paketea izaten jarraitzen duen bitartean (biak Brasilgo portugesa dira eta pool/UI berak partekatzen dituzte), eta en-SG/en_SG-k singlisha mantentzen dute (en generikoa ingelesa izaten jarraitzen du). Hong Kongeko txinera tradizionala salbuespen mota bera da: zh-HK, zh_HK.UTF-8 eta zh-Hant-HK-k zh-HK hautatzen dute, zh generikoa eta lurralde nagusiko etiketek txinera sinplifikatua (zh) hautatzen duten bitartean.

Hegaldi erdian aldatzea — /language panela. CLIa beti hasi zitekeen beste hizkuntza batean (--lang, LOCKEDIN_LANG); orain saioaren erdian aldatu dezakezu. Idatzi /language (aliasak /lang eta /languages) 33 hizkuntza guztiak kodez zerrendatzeko, bakoitza bere script-ean; /language el-ek saioaren gainerakorako aldatzen du. Gakoa ihes-eskotila da: aldaketa baten ondoren hizkuntza berrian birmarrazten du eta gero, utzi berri duzun hizkuntzan, itzultzeko bide zehatza inprimatzen du — /language en orain, lockedin --lang en hurrengoan — beraz 日本語-n edo ಕನ್ನಡ-n ustekabean lehorreratzeak ez zaitu inoiz bakartuta uzten. (Aldatu bi aldiz eta zure LOCKEDIN_LANG-ek izendatzen duen hizkuntza ere eskaintzen da.) --lang eta LOCKEDIN_LANG ez dira aldatzen. /a11y bezala, benetako baliagarritasun bat da, ez satiraren parte.

Ideia: hizkuntza-paketeak

Itzul daitekeen testu guztia paketeetan bizi da, bat hizkuntzako, bakoitza honela osatua:

{ meta: { lang: 'eu', name: 'Euskara', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Buzzword dentsitatea: ', /* etiketak, izenburuak */ } }

• pools 2. kapituluan ezagutu zenituen eduki-arrayak dira (txantxak).
• ui kromo-stringak dira: etiketak, izenburuak eta txantiloi txikiak.

Ingelesa src/lockedin.js-en barruko erreferentzia-paketea da; beste 32 pakete-moduluak src/content/*.js-en bizi dira: 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 eta zh-HK (pt-BR-k pt-ren pool/UI berrerabiltzen ditu baina bereizita erregistratzen da). Bakoitza BUNDLES-en erregistratzen da; SUPPORTED_LANGS gako horietatik sortzen da, eta renderHelp()-ek sortutako kode-zerrenda hori inprimatzen du. Ez dago UI-paketerik zerrenda kodean txertatzen duenik.

setLang('fr');       // seinalatu hizkuntza aktiboa frantsesaren paketera
// L = pool aktiboak, U = ui aktiboa
pick(L.HOOKS)        // frantsesezko hook bat
U.buzzwordDensity    // "Densité de jargon : "

Errenderizatzaile bakoitzak L eta U irakurtzen dituenez (inoiz ez kodean txertatutako string bat), setLang-ek berak esperientzia osoa aldatzen du. Hori da trikimailu osoa.

Segurtasun-sarea: gako-paritatea

Hona hizkuntza bat gehitzea segurua egiten duen aldaezina:

Pakete bakoitzak ingelesaren pools eta ui gako berberak azaldu behar ditu.

Proba batek 33 paketeetan betearazten du. UI-string berri bat ingelesez gehitzen baduzu eta ukraineraz itzultzea ahazten bazaizu, npm test gorri jartzen da eta zein gako falta den esaten dizu. Ezin duzu isilean erdi itzulitako hizkuntza bat argitaratu.

Zati zaila: terminal-diseinua

Hizkuntzek terminal-diseinua modu desberdinetan estutzen dute:

• Japonierak, txinera sinplifikatuak eta Hong Kongeko txinera tradizionalak East Asian Wide / Fullwidth karaktereak erabiltzen dituzte. vw()-k horiek bi zutabe gisa zenbatzen ditu, eta wrap()-ek espaziorik gabeko token luzeak gogor hausten ditu CJK testua txartel eta kaxen barruan gera dadin.
• Hindiak eta kannadak espaziorik gabeko/inguratzaile marka konbinatzaileak erabiltzen dituzte (Mn / Me), matra eta virama bezalakoak. vw()-k horiek zero zutabe gisa zenbatzen ditu neurtutako zabalera ez puzteko.
• box()-ek gorputz-lerro bakoitza biltzen du bete aurretik, beraz itzulitako banner luze batek ezin du dagoeneko ertza zulatu.
• Pakete bakoitzak sentenceEnd eta listSep ezartzen ditu (adibidez . / 。, , / 、) sortzaileek osatutako esaldiak modu naturalean irakur daitezen.

Hizkuntza bat gehitzen duzunean, txartel-goiburuko stringak (cardSubtitle, cardMeta, cardFooter) ≤ 60 zutabe ikusgaitan kabitu behar dute oraindik. Arabierak, persierak, hebreerak eta urduerak meta.dir: 'rtl' ezartzen dute. Irteerak ez du bidi-kontrolik izaten modu lehenetsian, terminal batzuek kaxa-etiketa gisa errenderizatzen baitituzte. LOCKEDIN_BIDI=on-ek isolatzaile orekatuak esplizituki gaitzen ditu biltze ondoren, horiek onartzen dituztela dakiten terminaletarako, ANSI, ASCII komandoak eta kopiatze/itsaste ordena logikoa gordez. Irteera irisgarriak beti kentzen ditu kontrol horiek. Aukeraketarik gabe, RTL/LTR nahasketaren ordena sofistikatu gutxiagokoa izan liteke; inoiz ez zundatu edo ondorioztatu euskarririk.

Zati maltzurra: gramatika erabiltzailearen sarrera gordinaren inguruan

UI-txantiloi batzuek erabiltzailearen esaldi gordinak txertatzen dituzte {cap} bezalako leku-markekin. Ez itzuli horiek hutsunez hutsune. Esaldiak gramatikal izaten jarraitu behar du leku-marka erabiltzaileak idatzitako esaldi bat denean, ez izen txukun bat.

Benetako bug ohartarazle bat: は {cap}-en ostean zuzenean jartzen duten japonierazko txantiloiek gaizki soinu dezakete {cap} esaldi oso bat denean. Konponketa ez da "gogorrago itzuli"; txantiloia berregituratzea da (adibidez, nominalizatzaile bat gehitu edo leku-marka mugitu) edozein erabiltzaile-sarrera oraindik kabitu dadin.

✅ Probatu zure agentearekin — gehitu hizkuntza bat

Ariketa honek modu berean funtzionatzen du oraindik. Aukeratu egiazta dezakezun hizkuntza bat (edo eskatu agenteari), eta eraman hasieratik amaierara. Idatzi espezifikazioa lehenik:

Gehitu daniera (da). Sortu src/content/da.js { meta, pools, ui } pakete gisa ingelesaren gako berberekin, sarrera bakoitza itzuliz (eduki-poolak ~25 bakoitzeko, UI-string guztiak). Erregistratu da BUNDLES-en src/lockedin.js-en. --lang da-k eta da-* locale batek hautatu behar dute. Mantendu txartel-goiburuko stringak zabalera-mugaren barruan. npm test berde mantendu behar da, eta gehitu danierazko aldaezinak + hautemate-probak existitzen diren lokalizatuak islatuz.

Ondoren, exekutatu 3–4 kapituluetako begizta:

1. Plana lehenik. "Kodea idatzi aurretik, esan zein fitxategi aldatuko dituzun eta nola mantenduko duzun gako-paritatea ingelesarekin."
2. Probak lehenik. "Gehitu huts egiten duten probak: da hautematea, da-rentzako gako-paritatea, eta danierazko reflect/connect aldaezin bat. Ez sortu paketea oraindik."
3. Inplementatu. "Orain sortu src/content/da.js existitzen den pakete bat gakoz gako itzuliz, erregistratu, eta egin probak gainditu. pick/shuffle soilik ausazkotasunerako."
4. Langa + berrikuspena. npm test, gero lockedin --lang da post — eta irakurri diff-a: gako guztiak itzuli al dira? Txartel-ertzak oraindik lerrokatzen al dira? {cap} duten txantiloiek erabiltzailearen esaldi gordinak gainditzen al dituzte?

Berotze-ariketa txikiagoak hizkuntza oso bat gehiegi bada:

• "Gehitu TAGLINE bat gehiago 33 hizkuntza-pakete guztiei, kopuruak berdin mantenduz."
• "Egiaztatu kannadaren cardFooter ≤ 60 zutabe ikusgai den eta azaldu nola neurtu ziren marka konbinatzaileak."
• "Erakutsi ja.js-etik ui gako bat ezabatuko banu huts egingo lukeen proba."

---

Nora joan hurrena

• Begiratu src/content/es.js — oraindik pakete berri baterako txantiloi lagunkoia da.
• Berrirakurri docs/HANDOFF.md → "Adding a language".
• Gozatu txantxa eleaniztunekin Komando-erreferentzia-n.

Hori da tutorial osoa. Orain AI agente bat zuzendu dezakezu funtzionalitateak eraiki eta test-langa baten atzean lokalizatzeko — 33 hizkuntzatan eta gehiagorako prest. Ados? 👇