Tutorial 5 Localization tr

Eğitim 5 · Yerelleştirme (i18n)

Amaç: LockedIn CLI'ın 33 dili nasıl konuştuğunu anlamak — ve bir ajanı başka bir dil eklemesi için yönlendirmeyi çalışmak. Yerelleştirme harika bir ajan görevidir: devretmek için yeterince mekaniktir, ama size incelemeyi öğreten gerçek kısıtlamaları vardır (bir test kapısı, düzen kuralları, dilbilgisi incelemesi).

← Önceki: Eğitim 4 Yönlendirme ve İnceleme · Ana Sayfa sayfasına dön

---

Burada "yerelleştirilmiş" ne demek

CLI'ı İspanyolca, Hintçe, Japonca, Basitleştirilmiş Çince veya gönderilen herhangi bir dilde çalıştırın ve her şey değişir — açılış ekranı, yardım tablosu, her komutun çıktısı, sohbet oturumu, hatta yasal küçük yazı. Yalnızca şakalar değil: tüm görünür yüzey.

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

Dil başlangıçta otomatik algılanır, öncelik sırasına göre çözümlenir:

1. --lang bayrağı (--lang tr, --lang=fr, -l ja)
2. LOCKEDIN_LANG ortam değişkeni
3. yerel ayarınız (LC_ALL / LC_MESSAGES / LANG, sonra OS/çalışma zamanı yerel ayarı)
4. yedek olarak İngilizce

normalizeLang() normalde yerel ayarın birincil alt etiketini kullanır. Bu, de-DE'nin de'yi seçtiği anlamına gelir, ama tlh yanlışlıkla tl olmaz; gerçek takma adlar fil ve tgl kasıtlı olarak Tagalog'a (tl) eşlenir, Norveççe nb ve nn no'ya eşlenir, eski Endonezce in id'ye eşlenir ve eski İbranice iw he'ye eşlenir. İki bölgesel kod, birincil alt etiketlerine katlanmak yerine harfi harfine korunur: pt-BR/pt_BR kanonik bölgesel kodu seçerken genel pt geriye dönük uyumlu Brezilya Portekizcesi paketi olarak kalır (ikisi de Brezilya Portekizcesidir ve aynı pools/UI'yi paylaşır) ve en-SG/en_SG Singlish'i korur (genel en İngilizce olarak kalır). Hong Kong Geleneksel Çincesi aynı türden bir istisnadır: zh-HK, zh_HK.UTF-8 ve zh-Hant-HK zh-HK'yi seçerken genel zh ve anakara etiketleri Basitleştirilmiş Çince'yi (zh) seçer.

Uçuş sırasında değiştirme — /language paneli. CLI her zaman başka bir dilde başlayabiliyordu (--lang, LOCKEDIN_LANG); artık oturum ortasında değiştirebilirsiniz. Tüm 33 dili koda göre, her biri kendi yazısında listelemek için /language (takma adlar /lang ve /languages) yazın; /language el oturumun geri kalanı için değiştirir. Mesele kaçış kapısıdır: bir değişiklikten sonra yeni dilde yeniden çizer ve ardından, az önce ayrıldığınız dilde, tam dönüş yolunu yazdırır — şimdi /language en, gelecek sefer lockedin --lang en — böylece yanlışlıkla 日本語 veya ಕನ್ನಡ içine düşmek sizi asla mahsur bırakmaz. (İki kez değiştirin ve LOCKEDIN_LANG'ınızın adlandırdığı dil de sunulur.) --lang ve LOCKEDIN_LANG değişmez. /a11y gibi, bu içten bir yardımcıdır, hicvin bir parçası değil.

Fikir: dil paketleri

Tüm çevrilebilir metin paketlerde yaşar, dil başına bir tane, her biri şu biçimde:

{ meta: { lang: 'tr', name: 'Türkçe', dir: 'ltr' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'Buzzword yoğunluğu: ', /* etiketler, başlıklar */ } }

• pools, 2. bölümde tanıştığınız içerik dizileridir (şakalar).
• ui, chrome dizeleridir: etiketler, başlıklar ve küçük şablonlar.

İngilizce, src/lockedin.js içindeki referans paketidir; diğer 32 paket modülü src/content/*.js'te yaşar: 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 ve zh-HK (pt-BR, pt'nin pools/UI'sini yeniden kullanır ama ayrı kaydedilir). Her biri BUNDLES'ta kayıtlıdır; SUPPORTED_LANGS o anahtarlardan üretilir ve renderHelp() o üretilen kod listesini yazdırır. Hiçbir UI paketi listeyi sabit kodlamaz.

setLang('fr');       // etkin dili Fransızca pakete yönelt
// L = etkin havuzlar, U = etkin arayüz
pick(L.HOOKS)        // Fransızca bir açılış
U.buzzwordDensity    // "Densité de jargon : "

Her renderer L ve U'yu okuduğu için (asla sabit kodlanmış bir dize değil), tek başına setLang tüm deneyimi değiştirir. Tüm numara budur.

Güvenlik ağı: anahtar eşliği

İşte bir dil eklemeyi güvenli kılan değişmez:

Her paket, İngilizce ile tam olarak aynı pools ve ui anahtarlarını açığa çıkarmalıdır.

Bir test bunu 33 paketin tümünde zorunlu kılar. İngilizce'de yeni bir UI dizesi ekler ve onu Ukraynaca'da çevirmeyi unutursanız, npm test kırmızıya döner ve hangi anahtarın eksik olduğunu söyler. Yarı çevrilmiş bir dili sessizce gönderemezsiniz.

Zor kısım: terminal düzeni

Diller terminal düzenini farklı şekillerde zorlar:

• Japonca, Basitleştirilmiş Çince ve Hong Kong Geleneksel Çincesi Doğu Asya Geniş / Tam genişlikli karakterler kullanır. vw() bunları iki sütun olarak sayar ve wrap(), CJK metninin kartların ve kutuların içinde kalması için uzun boşluksuz belirteçleri sert kırar.
• Hintçe ve Kannada, matra ve virama gibi boşluksuz/çevreleyici birleştirici işaretler (Mn / Me) kullanır. vw() bunları sıfır sütun olarak sayar, böylece ölçülen genişliği şişirmezler.
• box() her gövde satırını doldurmadan önce sarar, böylece uzun çevrilmiş bir başlık artık kenarlığı delip geçemez.
• Her paket sentenceEnd ve listSep ayarlar (örneğin . / 。, , / 、) böylece üreticinin oluşturduğu cümleler doğal okunur.

Bir dil eklediğinizde, kart başlık dizeleri (cardSubtitle, cardMeta, cardFooter) yine ≤ 60 görünür sütun içinde sığmalıdır. Arapça, Farsça, İbranice ve Urduca meta.dir: 'rtl' ayarlar. Çıktı varsayılan olarak hiçbir bidi kontrolü içermez, çünkü bazı terminaller onları kutulu etiketler olarak render eder. LOCKEDIN_BIDI=on, sarmadan sonra dengeli izolatları, onları desteklediği bilinen terminaller için açıkça etkinleştirir, ANSI'yi, ASCII komutlarını ve mantıksal kopyala/yapıştır sırasını koruyarak. Erişilebilir çıktı bu kontrolleri her zaman kaldırır. Bu tercih olmadan, karışık RTL/LTR sıralaması daha az gelişmiş olabilir; asla desteği yoklamayın veya çıkarımlamayın.

Sinsi kısım: ham kullanıcı girdisi etrafındaki dilbilgisi

Bazı UI şablonları, {cap} gibi placeholder'larla ham kullanıcı ifadelerini birleştirir. Onları slot slot çevirmeyin. Placeholder, kullanıcının yazdığı bir ifade olduğunda — düzgün bir isim değil — cümle dilbilgisel kalmalıdır.

Gerçek bir uyarı hatası: {cap}'ten hemen sonra は koyan Japonca şablonlar, {cap} tam bir cümle olduğunda yanlış gelebilir. Düzeltme "daha çok çevir" değildir; düzeltme, keyfi kullanıcı girdisinin yine sığması için şablonu yeniden yapılandırmaktır (örneğin, bir nominalizör ekleyin veya placeholder'ı taşıyın).

✅ Ajanınızla deneyin — bir dil ekleyin

Bu alıştırma yine tam olarak aynı şekilde çalışır. Aklıselimle kontrol edebileceğiniz bir dil seçin (veya ajandan isteyin) ve onu uçtan uca yönetin. Önce spesifikasyonu yazın:

Danca (da) ekleyin. src/content/da.js'i, İngilizce ile aynı anahtarlara sahip bir { meta, pools, ui } paketi olarak oluşturun, her girdiyi çevirerek (içerik havuzları her biri ~25, tüm UI dizeleri). da'yı src/lockedin.js'teki BUNDLES'a kaydedin. --lang da ve bir da-* yerel ayarı onu seçmelidir. Kart başlık dizelerini genişlik sınırı içinde tutun. npm test yeşil kalmalı ve mevcut yerelleştirilmiş olanları yansıtan Danca değişmezleri + algılama testleri ekleyin.

Ardından 3–4. bölümlerdeki döngüyü çalıştırın:

1. Önce plan. "Kod yazmadan önce, hangi dosyaları değiştireceğini ve İngilizce ile anahtar eşliğini nasıl koruyacağını söyle."
2. Önce test. "Başarısız olan testler ekle: da algılama, da için anahtar eşliği ve bir Danca reflect/connect değişmezi. Paketi henüz oluşturma."
3. Uygula. "Şimdi mevcut bir paketi anahtar anahtar çevirerek src/content/da.js'i oluştur, kaydet ve testleri geçir. Rastgelelik için yalnızca pick/shuffle."
4. Kapı + inceleme. npm test, sonra lockedin --lang da post — ve diff'i okuyun: her anahtar çevrildi mi? Kart kenarlıkları hâlâ hizalanıyor mu? {cap} içeren şablonlar ham kullanıcı ifadelerinden sağ çıkıyor mu?

Tüm bir dil çok fazlaysa daha küçük ısınma alıştırmaları:

• "33 dil paketinin tümüne bir TAGLINE daha ekle, sayıları eşit tutarak."
• "Kannada cardFooter'ının ≤ 60 görünür sütun olup olmadığını kontrol et ve birleştirici işaretlerin nasıl ölçüldüğünü açıkla."
• "ja.js'ten bir ui anahtarını silsem başarısız olacak testi göster."

---

Sırada nereye

• src/content/es.js'i tarayın — yeni bir paket için hâlâ dost canlısı bir şablondur.
• docs/HANDOFF.md → "Adding a language"'i yeniden okuyun.
• Komut Referansı'ndaki çok dilli şakaların tadını çıkarın.

Tüm eğitim bu kadar. Artık bir AI ajanını, özellikler geliştirmesi ve onları bir test kapısının arkasında yerelleştirmesi için yönlendirebilirsiniz — 33 dilde ve dahası için hazır. Agree? 👇