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

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

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

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

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

איך לבדוק:

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

להלן שלוש סיבות נפוצות לכך.

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

הפקודה wp i18n make-pot מחלצת רק מחרוזות שנמצאות בתוך פונקציות ה־i18n המוכרות. הכוונה היא ל־__(), ‏_e(), ‏_n(), ‏_x() והגרסאות עם ה־escape, עם טקסט דומיין נכון. מחרוזות בתוך דומיין שגוי יושמטו. מחרוזות קבועות (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

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

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

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

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

בלוח הבקרה של PTC, עברו אל Settings > Monitored Files.
ערכו את קובץ המשאבים הרלוונטי והפעילו את “Is this a WordPress project with localizable 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: האם שפת האתר מוגדרת נכון? עברו אל הגדרות > כללי > שפת האתר ב־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 עבור השפה הנוכחית. loaded: false אומר שהיא לא מצאה. הסיבה היא בדרך כלל חוסר התאמה בשם הקובץ (ראו בסעיף הבא) או נתיב תיקייה שגוי.

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

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

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

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

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

מיקום	תבנית	דוגמה
תיקיית `/languages/` של התוסף	`{text-domain}-{locale}.mo`	`my-plugin-de_DE.mo`
תיקיית `/languages/` של התבנית	`{locale}.mo`	`de_DE.mo`
תיקייה גלובלית (`/wp-content/languages/...`)	`{text-domain}-{locale}.mo`	`my-theme-de_DE.mo`

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

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

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

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

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

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 מוצאת את התיקייה.

בדקו שטקסט הדומיין שלכם עקבי לאורך כל הקוד

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

// 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" .

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

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

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

תפסו את אותן בעיות לפני שהן מופצות בעזרת AI Visual QA

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

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

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

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

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

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

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

שמרו על סנכרון בגרסאות עתידיות בעזרת תרגום רציף

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