תרגומים לתוסף 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(), והגרסאות עם ה־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:

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

זה מורה ל־PTC לסרוק קובצי JavaScript עבור מחרוזות לתרגום. PTC תיצור מחדש את התרגומים ותפתח pull 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: האם שפת האתר מוגדרת נכון? עברו אל Settings > General > Site Language (הגדרות > כללי > שפת האתר) ב־wp-admin וודאו שהיא תואמת לשפת היעד שלכם. לדוגמה, הגדירו אותה ל־"Espanol" כדי לבדוק ספרדית. אם האתר באנגלית, קובץ ה־.mo הספרדי שלכם לעולם לא ייטען. זה אינו באג.

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

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 ) );
} );

טענו מחדש דף ובדקו את יומן השגיאות (error log) של ה־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 תחזור בשקט להצגת אנגלית.

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

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

• 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 מייצרת prompt מוכן להדבקה עבור Cursor או Claude Code כדי לעטוף את המחרוזת ב־__(). עבור חוסר התאמה בדומיין טקסט (הבדיקה בסעיף הקודם), הוא מזהה שהמחרוזת לא מתורגמת בזמן שמחרוזות אחרות באותו מסך כן מתורגמות, ומדווח על חוסר העקביות.

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

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

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

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

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

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

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