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

תרגומים חסרים לאחר הרצת PTC? ארבע בדיקות מוצאות כמעט כל גורם. בדקו שהמחרוזת הגיעה אל 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(), והגרסאות שעברו escaping, עם ה־text domain הנכון. מחרוזות בתוך domain שגוי מדולגות. מחרוזות מוטמעות בקוד מחוץ לפונקציית 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 לא מחזיר כלום, המחרוזת מוטמעת בקוד ואינה עטופה ב־__(). זהו הבאג שלכם. עטפו את המחרוזת וחלצו מחדש.

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

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

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

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

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

בלוח הבקרה של PTC, עברו אל Settings > Monitored Files.
ערכו את קובץ המשאבים הרלוונטי והפעילו את “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 של האתר מוגדר כראוי? עברו אל Settings > General > Site Language (הגדרות > כללי > שפת האתר) ב־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 הקנוני כדי שתרגומים יחולו על מחרוזות המודפסות במהלך עיבוד בקשה רגיל.

אבחון 4: האם תרגומי קהילה דורסים את הקבצים המצורפים שלכם? כברירת מחדל, WordPress נותנת עדיפות לקובצי תרגום המאוחסנים ב־/wp-content/languages/. אם לתוסף או לתבנית שלכם יש תרגומים שסופקו על ידי הקהילה ב־WordPress.org, קבצים אלו עשויים לדרוס את קובצי ה־.mo המצורפים לפרויקט שלכם. כדי למנוע זאת, השתמשו ב־filter load_textdomain_mofile כדי לאלץ טעינה של נתיב הקבצים המצורפים שלכם לפני ש־WordPress בודקת את התיקייה הגלובלית. פרויקטים מרובי text domain (תוסף שמטמיע בתוכו תוסף אחר) דורשים שכל domain ייטען בנפרד. כל domain דורש קריאת 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 עבור יפנית (לחלק מה־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 תופס את אותן הבעיות לפני שהן משוחררות. הוא סוקר את התוסף המרונדר בכל שפת יעד לאחר כל עדכון תרגום ומדווח בחזרה מה חסר או שגוי.

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

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

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

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

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

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

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

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