תרגומי תוסף WordPress לא מופיעים? כך תתקנו תרגומים חסרים

תרגומים חסרים לאחר הרצה של PTC? ארבע בדיקות יאתרו כמעט כל גורם אפשרי. בדקו שהמחרוזת הגיעה אל PTC, ששם הקובץ .mo תואם למה ש־WordPress מצפה, וש־text domain עקבי בכל הקוד שלכם. מדריך זה עובר על כל בדיקה לפי הסדר שבו יש לבצע אותן.

אותו סדר בדיקות עובד בין אם תרגמתם בעזרת PTC (Private Translation Cloud), ב־GlotPress או בכל כלי אחר המבוסס על gettext. מצבי הכשל טבועים בתהליך ה־i18n של WordPress, ולא בכלי תרגום מסוים.

ודאו שהמחרוזת הגיעה אל PTC

השאלה הראשונה היא האם המחרוזת נמצאת בפרויקט ה־PTC שלכם. אם מחרוזת לא חולצה אל קובץ ה־.pot שלכם, PTC מעולם לא ראתה אותה. לקובץ .po אין תרגום עבורה. התוסף שרץ מציג את חלופת שפת המקור.

איך לבדוק:

1. פתחו את המחרוזת המושפעת בתוסף שרץ והעתיקו את הטקסט המדויק שלה.
2. היכנסו אל לוח הבקרה של PTC, פתחו את הלשונית Translations וחפשו את המחרוזת.
3. אם היא אינה שם, PTC מעולם לא קיבלה אותה.

להלן שלושה גורמים נפוצים.

גורם 1: המחרוזת חסרה בקובץ ה־POT שלכם

wp i18n make-pot מחלץ רק מחרוזות שנמצאות בתוך פונקציות i18n מוכרות. כלומר __(), _e(), _n(), _x() והגרסאות שעברו escaping, עם ה־text domain הנכון. מחרוזות בתוך ה־domain השגוי ידולגו. מחרוזות מוטמעות בקוד (hardcoded) מחוץ לפונקציית i18n ידולגו.

הריצו מחדש את החילוץ וודאו שהמחרוזת נמצאת כעת ב־.pot:

wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
grep "Save Changes" languages/my-plugin.pot

אם grep מחזיר את המחרוזת יחד עם msgid, החילוץ עובד. העלו מחדש את קובץ ה־.pot החדש אל PTC ותרגמו שוב. אם grep לא מחזיר דבר, המחרוזת היא hardcoded ואינה עטופה ב־__(). זהו הבאג שלכם. עטפו את המחרוזת וחלצו מחדש.

גורם 2: הטקסט אינו עטוף בפונקציית gettext

כל מחרוזת לתרגום בקוד שלכם דורשת wrapper. השתמשו ב־__(), esc_html__(), _e(), _n() או _x() עם ה־text domain הנכון:

__( 'Hello, world!', 'your-plugin' );

גורם 3: מחרוזות JavaScript לא סומנו כמיועדות לתרגום

אם התוסף שלכם כולל טקסט לתרגום ב־JavaScript:

1. בלוח הבקרה של PTC, נווטו אל Settings > Monitored Files (הגדרות > קבצים במעקב).
2. ערכו את קובץ המשאבים הרלוונטי והפעילו את האפשרות “Is this a WordPress project with localizable JavaScript?” (האם זהו פרויקט WordPress עם JavaScript המיועד ללוקליזציה?).

פעולה זו מורה ל־PTC לסרוק קובצי JavaScript לאיתור מחרוזות לתרגום. PTC מייצרת מחדש את התרגומים ופותחת merge request חדשה עם הקבצים המעודכנים.

לאחר מכן ודאו ש־WordPress יודעת מהיכן לטעון את קובצי התרגום .json ש־PTC יצרה. קראו ל־wp_set_script_translations() עם הנתיב הנכון:

// For plugins
wp_set_script_translations(
    'script-handle',
    'text-domain',
    plugin_dir_path( __FILE__ ) . 'languages'
);

// For themes
wp_set_script_translations(
    'script-handle',
    'text-domain',
    get_template_directory() . '/languages'
);

קריאה זו מורה ל־WordPress לטעון את קובצי .json מתיקיית התוסף או התבנית שלכם.

ודאו ש־WordPress טוענת את קובץ ה־.mo שלכם

אם המחרוזת נמצאת ב־PTC וקובץ .mo קיים בתיקיית languages/ של התוסף שלכם, אך התוסף המרונדר עדיין מציג אנגלית, WordPress נכשלת בטעינת קובץ ה־.mo.

בדיקה 1: האם ה־locale של האתר מוגדר נכון? נווטו אל הגדרות > כללי > שפת האתר ב־wp-admin וודאו שהיא תואמת לשפת היעד שלכם. לדוגמה, הגדירו אותה כ־”Español“ כדי לבדוק ספרדית. אם האתר באנגלית, קובץ ה־.mo הספרדי שלכם לעולם לא ייטען. זהו אינו באג.

בדיקה 2: האם load_plugin_textdomain() אכן רצה? הוסיפו שורת דיבאג זמנית:

add_action( 'init', function() {
    $loaded = load_plugin_textdomain(
        'my-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
    error_log( 'my-plugin textdomain loaded: ' . var_export( $loaded, true ) );
} );

טענו מחדש עמוד ובדקו את יומן השגיאות של PHP. loaded: true משמעותו ש־WordPress מצאה וטענה קובץ .mo עבור ה־locale הנוכחי. loaded: false משמעותו שהיא לא עשתה זאת. הגורם לכך הוא לרוב חוסר התאמה בשם הקובץ (ראו את הסעיף הבא) או נתיב תיקייה שגוי.

בדיקה 3: האם תזמון ה־hook נכון? load_plugin_textdomain() חייבת לרוץ על ה־hook init. זהו ה־hook הקנוני שבו תרגומים מוחלים על מחרוזות המודפסות (echoed) במהלך עיבוד בקשה רגיל.

בדיקה 4: האם תרגומי קהילה דורסים את הקבצים המצורפים שלכם? כברירת מחדל, WordPress נותנת עדיפות לקובצי תרגום המאוחסנים ב־/wp-content/languages/. אם לתוסף או לתבנית שלכם יש תרגומים שסופקו על ידי הקהילה ב־WordPress.org, קבצים אלו עשויים לדרוס את קובצי ה־.mo המצורפים (bundled) לפרויקט שלכם. כדי למנוע זאת, השתמשו ב־filter load_textdomain_mofile כדי לכפות טעינה של נתיב הקבצים המצורפים שלכם לפני ש־WordPress בודקת את התיקייה הגלובלית. פרויקטים מרובי text-domain (תוסף שמטמיע בתוכו תוסף אחר) דורשים טעינה נפרדת של כל domain. כל domain דורש קריאה משלו ל־load_plugin_textdomain() או ל־load_theme_textdomain().

ודאו ששם קובץ ה־MO תואם לתבנית החיפוש של WordPress

חיפוש קובצי .mo של WordPress פועל לפי מוסכמת שמות קפדנית. טעות של תו אחד בלבד ו־WordPress תחזור בשקט לחלופת האנגלית.

המוסכמה תלויה במיקום שבו אתם מציבים את הקובץ:

כמה דוגמאות מעשיות:

• my-plugin-es_ES.mo עבור ספרדית (ספרד)
• my-plugin-fr_FR.mo עבור צרפתית (צרפת)
• my-plugin-pt_BR.mo עבור פורטוגזית (ברזיל)
• my-plugin-zh_CN.mo עבור סינית מפושטת
• my-plugin-ja.mo עבור יפנית (לחלק מה־locales אין סיומת אזור)

טעויות נפוצות:

• קידומת text-domain שגויה. אם כותרת ה־Text Domain של התוסף שלכם היא my-plugin אך קובץ ה־.mo נקרא myplugin-es_ES.mo (ללא מקף), WordPress לא תמצא אותו. הקידומת חייבת להיות תואמת במדויק לערך ב־Text Domain.
• קוד locale שגוי. es.mo במקום es_ES.mo. WordPress משתמשת בקודי locale אזוריים. es_ES, es_MX ו־es_AR הם קבצים שונים. קוד שפה בלבד יעבוד רק כאשר לא קיים קובץ אזורי.
• מקף לעומת קו תחתון. קודי locale משתמשים בקו תחתון (es_ES), לעולם לא במקף (es-ES). זה מכשיל מפתחים שמעתיקים קודי locale מתוך כותרות Accept-Language בדפדפן או ממקורות BCP 47, שבהם מקף הוא התקן.
• תיקייה שגויה. כותרת ה־Domain Path חייבת להצביע על התיקייה שמכילה את קובצי ה־.mo שלכם. אם Domain Path הוא /languages וקובצי ה־.mo שלכם נמצאים ב־/lang/, WordPress לא תמצא אותם.

בדקו זאת על ידי השוואת רשימת הקבצים ש־PTC הפיקה מול ה־locale שבו האתר שלכם משתמש:

ls plugins/my-plugin/languages/
# my-plugin-es_ES.mo
# my-plugin-es_ES.po
# my-plugin-fr_FR.mo
# my-plugin-fr_FR.po

אם השמות נראים נכונים אך התרגומים עדיין לא נטענים, הריצו את בדיקת load_plugin_textdomain() שלעיל כדי לאשר ש־WordPress מוצאת את התיקייה.

בדקו שה־text domain שלכם עקבי בכל הקוד

זהו הרוצח השקט. כל קריאה ל־__(), _e(), _n(), _x() בקוד שלכם מעבירה text domain כארגומנט האחרון שלה. אם אפילו קריאה אחת מעבירה domain שגוי, אותה מחרוזת בודדת לא תתורגם. כל שאר המחרוזות בתוסף יעבדו היטב.

// Correct - matches the plugin's Text Domain
$correct = __( 'Save Changes', 'my-plugin' );

// Wrong - text domain typo; this string is never translated
$wrong = __( 'Save Changes', 'myplugin' );  // missing hyphen

// Wrong - copy-pasted from another plugin
$wrong = __( 'Save Changes', 'other-plugin' );

// Wrong - WordPress core domain; works for core strings but not yours
$wrong = __( 'Save Changes', 'default' );

מצאו חוסר עקביות על ידי שימוש ב־grep על בסיס הקוד שלכם:

grep -rE "__\(|_e\(|_n\(|_x\(" --include="*.php" .

התבוננו בארגומנט האחרון של כל התאמה. כולם צריכים להיות ה־text domain של התוסף שלכם. אם תמצאו שגיאות הקלדה או טעויות העתק־הדבק, תקנו אותן והריצו מחדש את wp i18n make-pot כדי לרענן את קובץ ה־.pot.

עבור קוד JavaScript המשתמש ב־@wordpress/i18n, חל אותו הכלל. wp_set_script_translations() ב־PHP חייבת גם היא להעביר את ה־domain התואם:

wp_set_script_translations( 'my-plugin-editor', 'my-plugin', '...' );
//                                                ^^^^^^^^^^^
//                                                Must match the JS calls

אתרו את אותן בעיות לפני שחרור בעזרת AI Visual QA

לולאת האבחון שלעיל היא תגובתית. תרגום חסר, ואתם יוצאים לחפש את הגורם. ה־AI Visual QA של PTC מאתר את אותן בעיות לפני שהן משוחררות. הוא בודק את התוסף המרונדר בכל שפת יעד לאחר כל עדכון תרגום ומדווח בחזרה מה חסר או שגוי.

במקרה של מחרוזת אנגלית מוטמעת בקוד (hardcoded) מחוץ ל־__() (גורם 1 לעיל), AI Visual QA רואה את המחרוזת הלא מתורגמת בתוסף המרונדר. PTC מייצרת פרומפט מוכן להדבקה עבור Cursor או Claude Code כדי לעטוף את המחרוזת ב־__(). במקרה של חוסר התאמה ב־text domain (הבדיקה מהסעיף הקודם), הוא רואה שהמחרוזת נותרה ללא תרגום בזמן שמחרוזות אחרות באותו מסך מתורגמות, ומדווח על חוסר העקביות.

אם טרם הפעלתם את AI Visual QA, עיינו במדריך לתבניות ותוספים של WordPress לקבלת הוראות הגדרה.

כאשר כל ארבע הבדיקות עוברות בהצלחה והתרגומים עדיין חסרים

אם הרצתם את כל ארבע הבדיקות והתרגומים עדיין אינם מופיעים, שלחו דוא״ל לתמיכה של PTC וצרפו:

• את ה־text domain של התוסף שלכם.
• את אחד משמות קובצי ה־.mo (לדוגמה, my-plugin-es_ES.mo).
• צילום מסך מלוח הבקרה של PTC המציג את המחרוזת המושפעת עם התרגום שלה.
• את הגדרת שפת האתר מתוך הגדרות > כללי.

רוב המקרים של ”תרגום חסר“ מסתכמים באחד הגורמים לעיל. מקרי קצה (גרסאות מסוימות של WordPress, פענוח locale ב־MultiSite, התנגשות עם תוסף i18n אחר) דורשים לעיתים בדיקה מעמיקה יותר.

שמרו על סינכרון בשחרורים עתידיים בעזרת לוקליזציה מתמשכת

ברגע שהתרגומים שלכם נטענים כראוי, הגדירו את תהליך הלוקליזציה המתמשכת כך ששחרורים עתידיים יישארו מסונכרנים עם התרגומים שלכם - באופן אוטומטי, בכל push ל־main.