בינאום WordPress: איך לתרגם תבניות ותוספים

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

מדריך זה מיועד למפתחים הכותבים את הקוד. אם כבר יש לכם קובץ POT או PO ואתם רק צריכים לתרגם אותו, עברו אל דף קובצי ה־PO לתהליך עבודה ב־3 שלבים.

בסיום המדריך, התבנית או התוסף שלכם יהיו:

עוברים תהליך בינאום (Internationalized) נכון לפי תקני הקידוד של WordPress.
ניתנים לתרגום על ידי PTC ל־40+ שפות.
ניתנים להפצה דרך חבילות השפה (Language Packs) של WordPress.org.
ניתנים לאימות בכל גרסה באמצעות סקירת התרגום החזותית של PTC.

מהו בינאום WordPress?

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

עבור תבניות ותוספים של WordPress, בינאום כולל שלושה דברים:

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

ברגע שהעבודה הזו מסתיימת, יש לכם כל מה שצריך כדי להפיק קובצי PO,‏ MO,‏ JSON ו־.l10n.php מתורגמים לכל שפה.

PTC מתרגם קובצי POT ל־MO,‏ JSON ו־.l10n.php עבור WordPress

חמש סיומות קבצים מופיעות בכל תהליך עבודה של תרגום WordPress. ‏PTC מתרגם מ־.pot (המקור שלכם) ל־.po,‏ .mo,‏ .json ו־.l10n.php עבור כל שפת יעד. לכל פורמט תפקיד ספציפי:

POT (Portable Object Template). קובץ המקור המופק מהקוד שלכם. הוא מכיל רשימה של כל המחרוזות הניתנות לתרגום ללא תרגומים מצורפים. את הקובץ הזה אתם מוסרים ל־PTC.
PO (Portable Object). עותק של ה־POT עם תרגומים שנוספו עבור שפה ספציפית אחת. זהו קובץ טקסט קריא. PTC מחזיר קובץ PO אחד לכל שפת יעד.
MO (Machine Object). הגרסה הבינארית המקומפלת של קובץ PO. ‏WordPress קוראת קובצי MO בזמן ריצה כי הם נטענים מהר יותר מקובצי טקסט מסוג PO.
JSON. המקבילה של MO עבור JavaScript. ‏WordPress אינה יכולה לקרוא MO מתוך JavaScript, לכן צינור הבנייה מפיק קובצי JSON עבור מחרוזות בצד הדפדפן.
.l10n.php. חלופה חדשה יותר ל־MO, שהוצגה ב־WordPress 6.5. היא נטענת מהר יותר וצורכת פחות זיכרון. WordPress בוחרת בה אוטומטית כשיש קובץ כזה לצד קובץ ה־MO.

הפעילו את .l10n.php עבור פרויקטים חדשים. הוא טוב משמעותית מ־MO בגרסאות הנתמכות של WordPress.

למה תרגום קהילתי אינו מספיק

‏WordPress.org מציעה תרגום קהילתי דרך GlotPress. בפועל, הוא מכסה רק חלק קטן ממה שרוב התוספים והתבניות צריכים. ניתוח של יותר מ־60,000 תוספים ותבניות של WordPress מצא שתרגום קהילתי מכסה פחות מ־5% מצרכי התרגום ב־40 שפות.

שתי בעיות מבניות מסבירות את הפער הזה:

קשה למצוא מתנדבים ברוב המקומות. קומץ תוספים עם בסיס משתמשים עצום מושכים מתרגמים. רובם לא.
לתרגומים יכול לקחת חודשים או שנים להופיע, אם הם מופיעים בכלל. אם אתם רוצים שהמשתמשים יראו את התוסף או התבנית שלכם בשפתם מהיום הראשון, אינכם יכולים להסתמך על הקהילה.

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

הכנת תבנית ה־WordPress או התוסף שלכם לתרגום

תחום טקסט (text domain) לא תואם או מחרוזת לא עטופה פירושם שהטקסט הזה לעולם לא יופיע בפלט המתורגם שלכם. הפרטים הקטנים חשובים.

שלב 1: הגדרת תחום הטקסט ונתיב התחום

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

הצהירו עליו בכותרת הקובץ הראשי של התוסף:

<?php
/**
 * Plugin Name: My Plugin
 * Description: An example plugin.
 * Version: 1.0.0
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

או בתוך קובץ ה־style.css של התבנית:

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

נתיב התחום (Domain Path) אומר ל־WordPress היכן נמצאים קובצי התרגום שלכם ביחס לשורש התוסף או התבנית. /languages הוא הסטנדרט.

שלב 2: עטיפת מחרוזות ה־PHP בפונקציות gettext

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

מחרוזות בסיסיות. השתמשו ב־__() כשאתם צריכים להחזיר מחרוזת. עבור פלט HTML, השתמשו בגרסאות ה־escaped. תקני הקידוד של WordPress ממליצים על echo esc_html__() במקום _e(). הצורה ה־escaped הופכת את טיהור הפלט למפורש ומונעת XSS בנקודת הפלט:

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

מחרוזות עם משתנים. אל תשרשרו משתנים לתוך מחרוזות. המתרגמים רואים רק קטעי מחרוזות ולא יכולים לשנות את סדר המילים עבור שפות עם תחביר שונה. השתמשו ב־printf() או sprintf() עם מציין מיקום. הוסיפו הערת מתרגם כדי שהמתרגמים ידעו מה %s מייצג:

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

צורות רבים. צורות רבים באנגלית הן פשוטות (one comment, two comments). שפות אחרות אינן כאלה. השתמשו ב־_n() כדי לטפל בכל כלל רבים ש־WordPress מכירה:

printf(
    esc_html( _n( '%s comment', '%s comments', $count, 'my-plugin' ) ),
    number_format_i18n( $count )
);

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

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

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

‏WordPress מספקת את חבילת wp-i18n כדי שתוכלו להשתמש באותן פונקציות gettext ב־JavaScript שבהן אתם משתמשים ב־PHP. בעת רישום הסקריפט שלכם, הצהירו על wp-i18n כתלות:

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

לאחר מכן, בקובץ ה־JavaScript שלכם:

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

אם אתם משתמשים ב־bundler כמו Webpack, התקינו את @wordpress/babel-plugin-makepot. הוא מחלץ מחרוזות ניתנות לתרגום מהחבילה שלכם כחלק מתהליך הבנייה.

שלב 4: הפקת קובץ ה־POT שלכם

ברגע שהמחרוזות שלכם עטופות, הפיקו קובץ POT. ה־POT הוא קובץ המקור שבו PTC (או כל מתרגם) משתמש. הוא מכיל כל מחרוזת ניתנת לתרגום אך ללא תרגומים.

wp i18n make-pot . languages/my-plugin.pot

‏WP-CLI סורק את קובצי ה־PHP, ה־JavaScript וה־block.json שלכם עבור קריאות gettext. הוא מקמפל אותן לקובץ POT יחיד. אם הצוות שלכם משתמש ב־Composer, הוסיפו את הפקודה הזו כסקריפט Composer. זה שומר על שימוש עקבי ב־WP-CLI בתוך הצוות ללא צורך בהתקנה גלובלית.

מערך הפקודות המלא של wp i18n מכסה את שאר הצינור:

פקודה	מה היא עושה
`wp i18n make-pot`	הפקת קובץ POT מהמקור.
`wp i18n update-po`	סנכרון קובצי PO קיימים כאשר ה־POT משתנה.
`wp i18n make-mo`	קימפול קובצי PO לקובצי MO בינאריים.
`wp i18n make-json`	חילוץ מחרוזות JS מתוך PO לקובצי JSON.
`wp i18n make-php`	הפקת קובצי `.l10n.php` (ב־WordPress 6.5+).

אין צורך ב־Poedit. כל מה שבתהליך העבודה הזה מתבצע דרך WP-CLI ו־PTC. ‏WP-CLI מטפל בהפקת POT ובקימפול MO/JSON. ‏PTC מטפל בתרגום ומחזיר כל פורמט קובץ ש־WordPress צריכה. Poedit הוא עורך שולחני שימושי לתרגום ידני, אך הוא אינו חלק מתהליך העבודה הזה.

תרגום קובצי POT עם PTC

‏PTC נבנה תוך מחשבה על מפתחי WordPress. התחילו עם קובץ POT וקבלו בחזרה קובצי תרגום מוכנים להפצה. תקופת הניסיון בחינם למשך 30 יום מכסה עד 20,000 מילים בשתי שפות.

הגדרת פרויקט התרגום הראשון שלכם

העלו את קובץ ה־POT שלכם. בחרו אילו פורמטים של פלט אתם צריכים. PTC מחזיר כל שילוב של:

קובצי .po לכל שפת יעד.
קובצי .mo, מקומפלים ומוכנים למשלוח.
קובצי .json עבור מחרוזות ה־JavaScript שלכם.
קובצי .l10n.php לטעינה מהירה יותר ב־WordPress 6.5+.

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

‏PTC מנתח את מבנה ה־gettext בעת ההעלאה. הוא מזהה מצייני מיקום (%s,‏ %1$s,‏ %d), צורות רבים (ערכים שחולצו על ידי _n() עם כותרת ה־Plural-Forms שלהם), והקשרים (ערכי _x() עם msgctxt). לאחר מכן הוא מפיק את קטגוריות הרבים הנכונות לכל שפה. פולנית מקבלת one / few / many / other. יפנית מקבלת רק other. ערבית מקבלת שש צורות.

מעבר ללוקליזציה רציפה

ברגע שהקבצים הראשונים שלכם תורגמו, עברו למודל Pay-As-You-Go. חברו את PTC למאגר ה־GitHub,‏ GitLab או ה־Bitbucket שלכם. מאותו רגע לא תעלו קבצים ידנית:

# .github/workflows/translate.yml
name: PTC translate
on:
  push:
    branches: [main]
    paths:
      - 'languages/my-plugin.pot'
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate POT
        run: |
          wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
      - name: Trigger PTC translation
        run: |
          curl -X POST https://api.ptc.wpml.org/v1/projects/${{ secrets.PTC_PROJECT_ID }}/sync \
            -H "Authorization: Bearer ${{ secrets.PTC_API_KEY }}"

‏PTC מסנכרן מחרוזות חדשות, מתרגם רק את מה שהשתנה, ופותח pull request עם קובצי ה־.po,‏ .mo,‏ .json ו־.l10n.php המעודכנים. עיינו ב־API reference של PTC עבור ה־webhook וה־REST API המלאים.

ההחלטה אם לעשות commit לקובצי .mo למאגר שלכם תלויה במדיניות הצוות. תוספים רבים מפיקים אותם בזמן השחרור במקום זאת. אינטגרציית ה־CI של PTC מפיקה אותם בכל הרצת תרגום. בצעו להם check-in רק אם אתם רוצים את הקבצים המתורגמים בהיסטוריית הגרסאות.

טעינת תרגומים ב־WordPress

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

דיוק בשמות הקבצים

קודי Locale עוקבים אחר הפורמט language_COUNTRY. ‏de_DE הוא גרמנית (גרמניה). fr_FR הוא צרפתית (צרפת). pt_BR הוא פורטוגזית (ברזיל). zh_CN הוא סינית מפושטת. פורטל התרגום של WordPress מפרט כל locale נתמך.

שם הקובץ הצפוי תלוי במקום שבו אתם מניחים את הקובץ:

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

תבניות משתמשות במוסכמת שמות קצרה יותר כאשר הקבצים ארוזים בתוך התבנית. בספריית השפות הגלובלית, גם תוספים וגם תבניות משתמשים בתבנית {text-domain}-{locale}.

טעינת תרגומים עבור תוספים (PHP)

רשמו את התרגומים ב־WordPress בתוך ה־hook של init. אל תשתמשו ב־plugins_loaded. הוא מפעיל אזהרת deprecation בגרסאות הנוכחיות של WordPress:

add_action( 'init', function () {
    load_plugin_textdomain(
        'my-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages/'
    );
} );

טעינת תרגומים עבור תבניות (PHP)

השתמשו ב־load_theme_textdomain() המחובר ל־after_setup_theme:

add_action( 'after_setup_theme', function () {
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
} );

טעינת תרגומי JavaScript

לאחר רישום הסקריפט שלכם (שלב 3 לעיל), קראו ל־wp_set_script_translations(). לאחר מכן WordPress טוענת את תרגומי ה־JSON עבור אותו script handle:

add_action( 'init', function () {
    wp_set_script_translations(
        'my-plugin-script',
        'my-plugin',
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

אימות הטעינה

הגדירו את שפת אתר ה־WordPress שלכם ל־locale היעד. ההגדרה נמצאת ב־הגדרות > כללי > שפת האתר.
טענו מחדש את ה־front end ואת דפי הניהול שהתוסף או התבנית שלכם מרנדרים.
מחרוזות העטופות ב־__() או ב־esc_html__() אמורות להופיע בשפה החדשה.

אם משהו חסר, עיינו ב־תרגומי תוספי WordPress לא מופיעים? תיקון תרגומים חסרים עבור הסיבות הנפוצות ביותר.

שפות מימין לשמאל ופריסות דו־כיווניות

תהליך עבודה של התרגום זהה עבור שפות הנכתבות מימין לשמאל (RTL). ערבית, עברית, פרסית ואורדו משתמשות באותו צינור POT/PO/MO.

השלב הנוסף הוא לוודא שהתבנית שלכם תומכת בסגנונות RTL. ‏WordPress טוענת אוטומטית קובץ rtl.css אם הוא קיים בספריית התבנית שלכם. השתמשו בפונקציה is_rtl() כדי להחיל סגנונות או סקריפטים ספציפיים ל־RTL באופן מותנה.

לוקליזציה של תאריכים, מספרים ומטבעות

מחרוזת מתורגמת אינה חזות הכל. תאריכים, מספרים ומטבעות חייבים גם הם לעקוב אחר ה־locale של המשתמש. השתמשו בפונקציות הפירמוט המובנות של WordPress במקום באלו המקוריות של PHP:

date_i18n() מפרמטת תאריכים בהתאם ל־locale הפעיל.
number_format_i18n() מפרמטת מספרים עם מפרידי אלפים ועשרוניים שמתחשבים ב־locale.

פונקציות אלו אינן חלק מתהליך העבודה של קובצי התרגום. הן חשובות עבור חוויית לוקליזציה מלאה.

בינאום בלוקים של עורך הבלוקים (Gutenberg)

בלוקים מוסיפים שני שלבים נוספים לצינור הסטנדרטי:

תרגומי JavaScript זקוקים לקובץ .json לכל locale. הפיקו אותו מה־.po באמצעות wp i18n make-json.
סקריפט העורך של הבלוק זקוק ל־wp_set_script_translations() ב־PHP. זה אומר ל־WordPress להגיש את ה־JSON לבלוק.

הפלט המרונדר של הבלוק ב־front end משתמש באותן קריאות __() כמו שאר ה־PHP שלכם. אין שם עבודה נוספת.

תרגום ה־README והרישום ב־WordPress.org

קובץ ה־readme.txt שלכם אינו קובץ משאבים. ‏WP-CLI לא יאסוף אותו בעת הפקת POT. כדי לתרגם אותו, השתמשו בתכונת הדבק לתרגום של PTC. הדביקו את התוכן, בחרו את שפות היעד שלכם והורידו את התוצאה. אימיילים הפונים ללקוחות שנשלחים מהתוסף ותיאור דף התוסף ב־WordPress.org מיתרגמים באותו אופן, כולם באותו פרויקט כדי שהטרמינולוגיה תישאר עקבית.

אם התוסף או התבנית שלכם רשומים ב־WordPress.org, התיאור המתורגם מופיע בלשונית ה־Details של התוסף בשפת המשתמש. כדי להעלות את התרגומים לשם, עקבו אחר תהליך הייבוא של WordPress.org.

תרגום תוכן משתמש בתוסף באמצעות ה־API של PTC

תוספים המאחסנים נתונים שנוצרו על ידי משתמשים (תוספי פורומים, תוספי ביקורות, תוספי תגובות) יכולים לתרגם את התוכן הזה עם הגעתו. ה־REST API של PTC מתרגם פוסטים של משתמשים, תגובות וביקורות לפי דרישה עם אימות Bearer-token, תוך שימוש באותו מילון מונחים וטון מותג כמו קובצי ה־.po שלכם.

סקירת תרגום חזותית של התבנית או התוסף המרונדרים – הפצה ללא QA ידני לכל שפה

קובץ .po מתורגם הוא הכרחי, אך הוא אינו מספיק. התבנית או התוסף המתורגמים עדיין זקוקים לאימות:

תווית מתורגמת עלולה לחרוג מגבולות כפתור בדף הגדרות בגרמנית.
"Submit" עלול להיתרגם כשם עצם בצרפתית כאשר פעולת הניהול דרשה פועל.
מחרוזת אנגלית עם hardcoding מחוץ ל־__() תרונדר ללא תרגום ללא קשר למספר השפות שאתם מפיצים.

סקירת התרגום החזותית של PTC מחליפה את סבב ה־QA הידני. תבניות ותוספי WordPress מרונדרים בדפדפן (הן ב־wp-admin והן ב־front end). הגרסה המתאימה היא ה־תוסף לדפדפן.

התקינו אותו פעם אחת. הקליטו walkthrough של התבנית או התוסף שלכם באתר בדיקה. כסו דפי הגדרות, פעולות ניהול ופלט ב־front end. ‏PTC מריץ מחדש את ההקלטה בכל שפת יעד לאחר כל עדכון תרגום. הוא לוכד כל מסך ומדווח על שני סוגי תיקונים:

תיקונים בקובצי ה־.po כאשר ל־PTC יש שליטה עליהם. PTC מתקן תרגומים עם משמעות שגויה, בוחר מילה נרדפת קצרה יותר שמתאימה לכפתור, או מפיק מחדש צורת רבים.
הנחיות (prompts) עבור Cursor או Claude Code כאשר הבעיה נמצאת בקוד ה־PHP או ה־JavaScript שלכם. דוגמאות כוללות עטיפת __() חסרה, מחרוזת אנגלית עם hardcoding, או משפט שנבנה על ידי שרשור שצריך להשתמש ב־sprintf( __( ... ) ).

אתם מפיצים תוסף מאומת ורב־לשוני בכל גרסה. הצורך ב־QA ידני נעלם.

תמחור: תקופת ניסיון חינם של 30 יום, ולאחר מכן Pay-As-You-Go

תקופת הניסיון בחינם מכסה 20,000 מילים בשתי שפות ללא כרטיס אשראי. כשתקופת הניסיון מסתיימת, PTC מציע מודל Pay-As-You-Go. ללא דמי מנוי. ללא התחייבות מינימלית. 500 המילים הראשונות בכל חודש הן בחינם. אתם משלמים רק על השאר. בדף התמחור יש מחשבון עלויות. הירשמו עם אימייל עסקי לקבלת תקופת ניסיון עסקית מורחבת.

מוכנים להפיץ תוסף או תבנית מאומתים?

‏PTC מפיק את התרגומים וסוקר את התוסף המרונדר. אתם מאשרים את התוצאה ומפיצים. הלופ המלא רץ ללא QA ידני:

הפיקו את קובץ ה־.pot שלכם באמצעות wp i18n make-pot.
העלו אותו ל־PTC וקבלו בחזרה קובצי .po,‏ .mo,‏ .l10n.php ו־.json תוך דקות.
התקינו את תוסף הדפדפן כדי לאמת את התוסף הפועל בכל שפת יעד.

התחילו את תקופת הניסיון שלכם למשך 30 יום בחינם – 20,000 מילים עלינו, ללא צורך בכרטיס אשראי.

נושאים קשורים:

תרגום קובצי PO אונליין עם בינה מלאכותית – דף התרגום הקנוני עבור PO/POT.
GlotPress מול PTC לתרגום תוספי/תבניות WordPress – מתי לבחור בתרגום קהילתי ומתי ב־PTC.
תרגומי תוספי WordPress לא מופיעים? תיקון תרגומים חסרים – מדריך לפתרון בעיות.
איך לייבא תרגומי תבניות ותוספים ל־WordPress.org – תהליך CLPTE וחלופה מהירה יותר.
API reference של PTC – נקודות קצה של REST עבור אינטגרציית CI.