Tutorial 5 Localization he

מדריך 5 · לוקליזציה (i18n)

מטרה: להבין איך LockedIn CLI מדבר 33 שפות — ולתרגל כיוון סוכן להוסיף עוד אחת. לוקליזציה היא משימת סוכן נפלאה: היא מכנית מספיק כדי להאציל, אבל יש לה אילוצים אמיתיים (מחסום בדיקות, כללי פריסה, סקירת דקדוק) שמלמדים אתכם לסקור.

← הקודם: מדריך 4 ניסוח בקשות וסקירה · חזרה אל בית

---

מה "מקומי" אומר כאן

הריצו את ה-CLI בספרדית, הינדי, יפנית, סינית מפושטת או כל שפה שנשלחת והכל משתנה — מסך הפתיחה, טבלת העזרה, הפלט של כל פקודה, סשן הצ'אט, אפילו האותיות הקטנות המשפטיות. לא רק הבדיחות: כל המשטח הנראה.

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

השפה מזוהה אוטומטית בהפעלה, נפתרת לפי סדר עדיפות:

1. הדגל --lang (--lang he, --lang=fr, -l ja)
2. משתנה הסביבה LOCKEDIN_LANG
3. הלוקייל שלכם (LC_ALL / LC_MESSAGES / LANG, ואז הלוקייל של מערכת ההפעלה/סביבת הריצה)
4. אנגלית, כברירת מחדל

normalizeLang() בדרך כלל משתמש בתת-התג הראשי של הלוקייל. זה אומר ש-de-DE בוחר de, אבל tlh לא הופך בטעות ל-tl; הכינויים האמיתיים fil ו-tgl ממופים בכוונה ל-Tagalog (tl), הנורווגיים nb ו-nn ממופים ל-no, האינדונזי הישן in ממופה ל-id, והעברי הישן iw ממופה ל-he. שני קודים אזוריים נשמרים מילה במילה במקום מקופלים לתת-התג הראשי שלהם: pt-BR/pt_BR בוחרים את הקוד האזורי הקנוני בעוד ש-pt הכללי נשאר חבילת הפורטוגזית הברזילאית התואמת לאחור (שתיהן פורטוגזית ברזילאית וחולקות את אותם pools/UI), ו-en-SG/en_SG שומרים על Singlish (en הכללי נשאר אנגלית). סינית מסורתית של הונג קונג היא אותו סוג של חריגה: zh-HK, zh_HK.UTF-8 ו-zh-Hant-HK בוחרים zh-HK, בעוד ש-zh הכללי ותגי היבשת בוחרים סינית מפושטת (zh).

מעבר תוך כדי תנועה — לוח ה-/language. ה-CLI תמיד יכול היה להתחיל בשפה אחרת (--lang, LOCKEDIN_LANG); עכשיו אתם יכולים להחליף באמצע הסשן. הקלידו /language (כינויים /lang ו-/languages) כדי לרשום את כל 33 השפות לפי קוד, כל אחת בכתב שלה; /language el מחליף לשארית הסשן. העיקר הוא פתח המילוט: לאחר החלפה הוא מצייר מחדש בשפה החדשה ואז, בשפה שהרגע עזבתם, מדפיס את הדרך המדויקת חזרה — /language en עכשיו, lockedin --lang en בפעם הבאה — כך שנחיתה בטעות ב-日本語 או ב-ಕನ್ನಡ לעולם לא תשאיר אתכם תקועים. (החליפו פעמיים והשפה ש-LOCKEDIN_LANG מציין מוצעת גם.) --lang ו-LOCKEDIN_LANG ללא שינוי. כמו /a11y, זה כלי עזר כן, לא חלק מהסאטירה.

הרעיון: חבילות שפה

כל הטקסט הניתן לתרגום חי בחבילות, אחת לכל שפה, כל אחת בצורה:

{ meta: { lang: 'he', name: 'עברית', dir: 'rtl' },
  pools: { HOOKS: [ /* ~25 */ ], LESSONS: [ /* ... */ ], /* ... */ },
  ui:    { buzzwordDensity: 'צפיפות באזוורדס: ', /* תוויות, כותרות */ } }

• pools הם מערכי התוכן (הבדיחות) שפגשתם בפרק 2.
• ui הם מחרוזות ה-chrome: תוויות, כותרות ותבניות קטנות.

אנגלית היא חבילת הייחוס בתוך src/lockedin.js; 32 מודולי החבילות האחרים חיים ב-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 ו-zh-HK (pt-BR משתמש מחדש ב-pools/UI של pt אבל רשום בנפרד). כל אחד רשום ב-BUNDLES; SUPPORTED_LANGS נוצר מאותם מפתחות, ו-renderHelp() מדפיס את רשימת הקודים הנוצרת. אף חבילת UI לא מקודדת קשיח את הרשימה.

setLang('fr');       // הפנה את השפה הפעילה לחבילה הצרפתית
// L = מאגרים פעילים, U = ממשק משתמש פעיל
pick(L.HOOKS)        // פתיח צרפתי
U.buzzwordDensity    // "Densité de jargon : "

מכיוון שכל מרנדר קורא L ו-U (לעולם לא מחרוזת מקודדת קשיח), setLang לבדו משנה את כל החוויה. זה כל הטריק.

רשת הביטחון: זהות מפתחות

הנה האינווריאנט שהופך הוספת שפה לבטוחה:

כל חבילה חייבת לחשוף בדיוק את אותם מפתחות pools ו-ui כמו אנגלית.

בדיקה אוכפת זאת בכל 33 החבילות. אם תוסיפו מחרוזת UI חדשה באנגלית ותשכחו לתרגם אותה באוקראינית, npm test הופך אדום ואומר לכם איזה מפתח חסר. אינכם יכולים בשקט לשגר שפה מתורגמת למחצה.

החלק הקשה: פריסת טרמינל

שפות מלחיצות את פריסת הטרמינל בדרכים שונות:

• יפנית, סינית מפושטת וסינית מסורתית של הונג קונג משתמשות בתווים East Asian Wide / Fullwidth. vw() סופר אותם כשתי עמודות, ו-wrap() שובר קשיח אסימונים ארוכים חסרי רווחים כך שטקסט CJK נשאר בתוך כרטיסים ותיבות.
• הינדי וקנאדה משתמשות בסימני צירוף ללא-מרווח/עוטפים (Mn / Me), כמו matras ו-viramas. vw() סופר אותם כאפס עמודות כך שהם לא מנפחים את הרוחב הנמדד.
• box() עוטף כל שורת גוף לפני שהוא מרפד אותה, כך שבאנר מתורגם ארוך כבר לא יכול לפרוץ דרך הגבול.
• כל חבילה מגדירה sentenceEnd ו-listSep (למשל . / 。, , / 、) כך שמשפטים שהמחולל מרכיב נקראים באופן טבעי.

כשאתם מוסיפים שפה, מחרוזות כותרת הכרטיס (cardSubtitle, cardMeta, cardFooter) חייבות עדיין להתאים ל-≤ 60 עמודות נראות. ערבית, פרסית, עברית ואורדו מגדירות meta.dir: 'rtl'. הפלט אינו מכיל בקרות דו-כיווניות כברירת מחדל, כי חלק מהטרמינלים מציגים אותן כתוויות בתיבות. LOCKEDIN_BIDI=on מפעיל מפורשות בידוד מאוזן לאחר העטיפה עבור טרמינלים הידועים כתומכים בהם, תוך שמירה על ANSI, פקודות ASCII וסדר העתקה/הדבקה לוגי. פלט נגיש תמיד מסיר את הבקרות האלה. ללא ההצטרפות המפורשת, סדר מעורב RTL/LTR עשוי להיות פחות מתוחכם; לעולם אל תגששו או תסיקו תמיכה.

החלק המתחמק: דקדוק סביב קלט משתמש גולמי

חלק מתבניות ה-UI מחברות פסקאות משתמש גולמיות עם placeholders כמו {cap}. אל תתרגמו אותן חריץ-בחריץ. המשפט חייב להישאר דקדוקי כשה-placeholder הוא ביטוי שהמשתמש הקליד, לא שם עצם מסודר.

באג אזהרה אמיתי: תבניות יפניות ששמות は ישירות אחרי {cap} יכולות להישמע לא נכון כש-{cap} הוא פסקה מלאה. התיקון אינו "לתרגם חזק יותר"; הוא לבנות מחדש את התבנית (למשל, להוסיף nominalizer או להזיז את ה-placeholder) כך שקלט משתמש שרירותי עדיין מתאים.

✅ נסו עם הסוכן שלכם — הוסיפו שפה

התרגיל הזה עדיין עובד בדיוק באותו אופן. בחרו שפה שאתם יכולים לבדוק שפיות (או בקשו מהסוכן), והובילו אותה מקצה לקצה. כתבו את המפרט קודם:

הוסיפו דנית (da). צרו את src/content/da.js כחבילת { meta, pools, ui } עם אותם מפתחות כמו אנגלית, תוך תרגום כל ערך (מאגרי תוכן ~25 כל אחד, כל מחרוזות ה-UI). רשמו את da ב-BUNDLES ב-src/lockedin.js. --lang da ולוקייל da-* חייבים לבחור אותו. שמרו על מחרוזות כותרת הכרטיס בתוך מגבלת הרוחב. npm test חייב להישאר ירוק, והוסיפו אינווריאנטים של דנית + בדיקות זיהוי המשקפות את הקיימות המקומיות.

לאחר מכן הריצו את הלולאה מפרקים 3–4:

1. תוכנית קודם. "לפני כתיבת קוד, אמור לי את הקבצים שתשנה ואיך תשמור על זהות מפתחות עם אנגלית."
2. בדיקות קודם. "הוסף בדיקות נכשלות: זיהוי da, זהות מפתחות ל-da, ואינווריאנט reflect/connect בדנית. אל תיצור עדיין את החבילה."
3. מימוש. "עכשיו צור את src/content/da.js על ידי תרגום חבילה קיימת מפתח אחר מפתח, רשום אותה, וגרום לבדיקות לעבור. רק pick/shuffle לאקראיות."
4. מחסום + סקירה. npm test, ואז lockedin --lang da post — וקראו את ה-diff: האם כל מפתח תורגם? האם גבולות הכרטיס עדיין מיושרים? האם תבניות עם {cap} שורדות פסקאות משתמש גולמיות?

תרגילי חימום קטנים יותר אם שפה שלמה זה יותר מדי:

• "הוסף עוד TAGLINE אחד לכל 33 חבילות השפה, תוך שמירה על ספירות שוות."
• "בדוק האם ה-cardFooter בקנאדה הוא ≤ 60 עמודות נראות והסבר איך סימני הצירוף נמדדו."
• "הראה לי את הבדיקה שתיכשל אם אמחק מפתח ui מ-ja.js."

---

לאן ללכת הלאה

• העיפו מבט ב-src/content/es.js — הוא עדיין תבנית ידידותית לחבילה חדשה.
• קראו שוב את docs/HANDOFF.md → "Adding a language".
• תיהנו מהבדיחות הרב-לשוניות ב-מדריך פקודות.

זהו המדריך המלא. אתם כבר יכולים לכוון סוכן AI לבנות תכונות וגם ללקלל אותן מאחורי מחסום בדיקות — ב-33 שפות ומוכן לעוד. Agree? 👇