Tutorial 5 Localization pl

Samouczek 5 · Lokalizacja (i18n)

Cel: zrozumieć, jak LockedIn CLI mówi 33 językami — i przećwiczyć kierowanie agentem, aby dodał kolejny. Lokalizacja to fantastyczne zadanie dla agenta: jest na tyle mechaniczna, że można ją oddelegować, ale ma prawdziwe ograniczenia (bramka testowa, zasady układu, przegląd gramatyki), które uczą Cię recenzować.

← Poprzednio: Samouczek 4 Formułowanie promptów i recenzja · Powrót do Strona główna

---

Co „zlokalizowane” znaczy tutaj

Uruchom CLI po hiszpańsku, hindi, japońsku, w chińskim uproszczonym lub w dowolnym dostarczonym języku, a wszystko się zmienia — ekran powitalny, tabela pomocy, wyjście każdej komendy, sesja czatu, nawet prawny drobny druk. Nie tylko żarty: cała widoczna powierzchnia.

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

Język jest automatycznie wykrywany przy starcie, rozwiązywany w kolejności priorytetów:

1. flaga --lang (--lang pl, --lang=fr, -l ja)
2. zmienna środowiskowa LOCKEDIN_LANG
3. Twoje locale (LC_ALL / LC_MESSAGES / LANG, następnie locale systemu/środowiska uruchomieniowego)
4. angielski, jako fallback

normalizeLang() zwykle używa podstawowego podtagu locale. Oznacza to, że de-DE wybiera de, ale tlh nie staje się przypadkiem tl; prawdziwe aliasy fil i tgl celowo mapują na Tagalog (tl), norweskie nb i nn mapują na no, dawne indonezyjskie in mapuje na id, a dawne hebrajskie iw mapuje na he. Dwa kody regionalne są zachowywane dosłownie, a nie zwijane do podstawowego podtagu: pt-BR/pt_BR wybierają kanoniczny kod regionalny, podczas gdy ogólne pt pozostaje wstecznie zgodnym pakietem brazylijskiego portugalskiego (oba są brazylijskim portugalskim i dzielą te same pools/UI), a en-SG/en_SG zachowują Singlish (ogólne en pozostaje angielskim). Chiński tradycyjny z Hongkongu to ten sam rodzaj wyjątku: zh-HK, zh_HK.UTF-8 i zh-Hant-HK wybierają zh-HK, podczas gdy ogólne zh i tagi kontynentalne wybierają chiński uproszczony (zh).

Przełączanie w locie — panel /language. CLI zawsze mogło startować w innym języku (--lang, LOCKEDIN_LANG); teraz możesz przełączyć w trakcie sesji. Wpisz /language (aliasy /lang i /languages), aby wypisać wszystkie 33 języki po kodzie, każdy w swoim piśmie; /language el przełącza na resztę sesji. Chodzi o wyjście awaryjne: po przełączeniu przerysowuje w nowym języku, a potem, w języku, który właśnie opuściłeś, drukuje dokładną drogę powrotną — /language en teraz, lockedin --lang en następnym razem — więc przypadkowe wylądowanie w 日本語 czy ಕನ್ನಡ nigdy Cię nie osaczy. (Przełącz dwa razy, a język, który nazywa Twój LOCKEDIN_LANG, też jest oferowany.) --lang i LOCKEDIN_LANG bez zmian. Jak /a11y, to szczere narzędzie, a nie część satyry.

Pomysł: pakiety językowe

Cały tłumaczalny tekst żyje w pakietach, po jednym na język, każdy w kształcie:

{ meta: { lang: 'pl', name: 'Polski', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Gęstość buzzwordów: ', /* etykiety, nagłówki */ } }

• pools to tablice treści (żarty), które poznałeś w rozdziale 2.
• ui to stringi chrome: etykiety, nagłówki i małe szablony.

Angielski jest pakietem referencyjnym wewnątrz src/lockedin.js; pozostałe 32 moduły pakietów żyją w 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 i zh-HK (pt-BR ponownie używa pools/UI z pt, ale jest rejestrowany osobno). Każdy jest zarejestrowany w BUNDLES; SUPPORTED_LANGS jest generowane z tych kluczy, a renderHelp() drukuje tę wygenerowaną listę kodów. Żaden pakiet UI nie koduje na sztywno tej listy.

setLang('fr');       // ustaw aktywny język na pakiet francuski
// L = aktywne pule, U = aktywny interfejs
pick(L.HOOKS)        // francuski haczyk
U.buzzwordDensity    // "Densité de jargon : "

Ponieważ każdy renderer czyta L i U (nigdy stringa na sztywno), sam setLang zmienia całe doświadczenie. To cała sztuczka.

Siatka bezpieczeństwa: parzystość kluczy

Oto niezmiennik, który czyni dodawanie języka bezpiecznym:

Każdy pakiet musi udostępniać dokładnie te same klucze pools i ui co angielski.

Test egzekwuje to we wszystkich 33 pakietach. Jeśli dodasz nowy string UI po angielsku i zapomnisz przetłumaczyć go po ukraińsku, npm test staje się czerwony i mówi, którego klucza brakuje. Nie możesz po cichu wysłać na wpół przetłumaczonego języka.

Trudna część: układ terminala

Języki obciążają układ terminala na różne sposoby:

• Japoński, chiński uproszczony i chiński tradycyjny z Hongkongu używają znaków East Asian Wide / Fullwidth. vw() liczy je jako dwie kolumny, a wrap() twardo łamie długie, bezspacjowe tokeny, aby tekst CJK pozostał w kartach i ramkach.
• Hindi i kannada używają nierozdzielających/zamykających znaków łączących (Mn / Me), takich jak matry i wiramy. vw() liczy je jako zero kolumn, aby nie zawyżały mierzonej szerokości.
• box() zawija każdą linię treści przed jej dopełnieniem, więc długi przetłumaczony baner nie może już przebić się przez obramowanie.
• Każdy pakiet ustawia sentenceEnd i listSep (na przykład . / 。, , / 、), aby zdania składane przez generator czytały się naturalnie.

Gdy dodajesz język, stringi nagłówka karty (cardSubtitle, cardMeta, cardFooter) muszą nadal mieścić się w ≤ 60 widocznych kolumnach. Arabski, perski, hebrajski i urdu ustawiają meta.dir: 'rtl'. Wyjście domyślnie nie zawiera kontrolek bidi, ponieważ niektóre terminale renderują je jako etykiety w ramkach. LOCKEDIN_BIDI=on jawnie włącza zrównoważone izolaty po zawijaniu dla terminali znanych z ich obsługi, zachowując ANSI, komendy ASCII i logiczny porządek kopiowania/wklejania. Wyjście dostępne zawsze usuwa te kontrolki. Bez tej zgody mieszany porządek RTL/LTR może być mniej wyrafinowany; nigdy nie sonduj ani nie wnioskuj o obsłudze.

Podstępna część: gramatyka wokół surowego wejścia użytkownika

Niektóre szablony UI wplatają surowe frazy użytkownika za pomocą placeholderów takich jak {cap}. Nie tłumacz ich slot-po-slocie. Zdanie musi pozostać gramatyczne, gdy placeholder jest frazą, którą użytkownik wpisał, a nie schludnym rzeczownikiem.

Prawdziwy ostrzegawczy błąd: japońskie szablony, które stawiają は bezpośrednio po {cap}, mogą brzmieć źle, gdy {cap} jest pełnym zdaniem. Naprawą nie jest „tłumacz mocniej”; jest nią przebudowa szablonu (na przykład dodanie nominalizatora lub przesunięcie placeholdera), aby dowolne wejście użytkownika nadal pasowało.

✅ Wypróbuj ze swoim agentem — dodaj język

To ćwiczenie nadal działa dokładnie tak samo. Wybierz język, który potrafisz sprawdzić na chłopski rozum (albo poproś agenta), i poprowadź go od początku do końca. Napisz najpierw specyfikację:

Dodaj duński (da). Utwórz src/content/da.js jako pakiet { meta, pools, ui } z tymi samymi kluczami co angielski, tłumacząc każdy wpis (pule treści po ~25 każda, wszystkie stringi UI). Zarejestruj da w BUNDLES w src/lockedin.js. --lang da i locale da-* muszą go wybierać. Utrzymaj stringi nagłówka karty w limicie szerokości. npm test musi pozostać zielony, i dodaj niezmienniki duńskiego + testy wykrywania odzwierciedlające istniejące zlokalizowane.

Następnie uruchom pętlę z rozdziałów 3–4:

1. Najpierw plan. „Zanim napiszesz kod, powiedz mi, które pliki zmienisz i jak utrzymasz parzystość kluczy z angielskim.”
2. Najpierw testy. „Dodaj testy, które padają: wykrywanie da, parzystość kluczy dla da i niezmiennik reflect/connect po duńsku. Nie twórz jeszcze pakietu.”
3. Implementacja. „Teraz utwórz src/content/da.js, tłumacząc istniejący pakiet klucz po kluczu, zarejestruj go i spraw, aby testy przeszły. Tylko pick/shuffle do losowości.”
4. Bramka + recenzja. npm test, a potem lockedin --lang da post — i przeczytaj diff: czy każdy klucz został przetłumaczony? Czy obramowania kart nadal się układają? Czy szablony z {cap} przetrwają surowe frazy użytkownika?

Mniejsze ćwiczenia rozgrzewkowe, jeśli cały język to za dużo:

• „Dodaj jeszcze jeden TAGLINE do wszystkich 33 pakietów językowych, utrzymując równe liczby.”
• „Sprawdź, czy kannadyjski cardFooter ma ≤ 60 widocznych kolumn, i wyjaśnij, jak zmierzono znaki łączące.”
• „Pokaż mi test, który padłby, gdybym usunął klucz ui z ja.js.”

---

Dokąd dalej

• Przejrzyj src/content/es.js — nadal jest przyjaznym szablonem dla nowego pakietu.
• Przeczytaj ponownie docs/HANDOFF.md → „Adding a language”.
• Ciesz się wielojęzycznymi żartami w Podręczniku komend.

To cały samouczek. Umiesz teraz kierować agentem AI, aby budował funkcje i lokalizował je za bramką testową — w 33 językach i gotowy na więcej. Agree? 👇