תרגום תבניות ותוספי WordPress

WordPress מתורגמת למעל ל-50 שפות שונות והיא מבין מערכות ניהול התוכן הכי חמות ונפוצות כיום; לכן כאשר בונים תבנית או תוסף ל-WordPress חשוב לאפשר תרגום שלו לשפות שונות על מנת לא להפסיד נתח שוק.

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

פונקציות gettext

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

__

הפונקציה הראשונה נקראת __() והתפקיד שלה היא להחזיר את המחרוזת המתורגמת, היא מקבלת שתי פרמטרים, המחרוזת עצמה, ומזהה התרגום.

$myString = __( 'Hello World', 'dorzki' );

_e

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

<?php _e( 'Hello World', 'dorzki' ); ?>

_n

הפונקציה הבאה היא _n(), אך בניגוד לפונקציות הקודמות, פונקצייה זאת מקבלת 4 פרמטים – מחרוזת יחיד, מחרוזת רבים, כמות ומזהה התרגום. פונקציה זאת שימושית מאוד כאשר רוצים להציג תרגום שונה ליחיד ולרבים עפ״י מספר מסויים.

$myString = sprintf( _n( 'Hello %d World', 'Hello %d Worlds', $totalWorlds, 'dorzki' ), $totalWorlds );

כאמור הפונקציה הנ״ל תחזיר לנו את המחרוזת המתורגמת לפי הפרמטר שהגדרנו (לדוגמא $totalWorlds) וע״י שימוש בפונקציית sprintf, נכניס את המספר גם למחרוזת שמתורגמת ע״י שימוש ב-placeholder.

_x

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

$myString = _x( 'Comment', 'noun', 'dorzki' );

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

_ex

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

<?php _ex( 'Comment', 'noun', 'dorzki' ); ?>

_nx

הפונקציה הבאה היא שילוב של שתי פונקציות, _x() ו-_n(), מקבלת 5 פרמטרים, מחרוזת יחיד, מחרוזת רבים, כמות, תיאור המחרוזת ומזהה התרגום.

$myString = sprintf( _nx( 'Hello %d World', 'Hello %d Worlds', $totalWorlds, 'Welcome Greeting', 'dorzki' ), $totalWorlds );

פונקציות Escaping

ישנן פונקציות נוספות אשר עושות בדיוק את מה שעושות הפונקציות הבסיסיות, רק שהן מבצעות escaping למחרוזת המחוזרת, לצורך העניין אם נרצה לשים תרגום ב-attribute של תגית HTML או כאשר נרצה להציג מחרוזת בתוך קוד HTML מבלי לפגוע במבנה המסמך, משתמש בפונקציות הבאות:

• esc_attr__()
• esc_attr_e()
• esc_attr_x()
• esc_html__()
• esc_html_e()
• esc_html_x()

שימוש נכון בפונקציות gettext

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

תגיות HTML

לרוב יש מפתחים אשר מכניסים תגיות HTML למחרוזות התרגום שלהם, למה? אני לא יודע…
יש להימנע מהכנסה של תגיות HTML מכיוון שזה לא נוח לתרגום וגורם לסרבול בתרגום.

// Bad!
$badString = __( '<b>Geeky Web Developer</b>', 'dorzki' );

// Good!
$goodString = "<b>" . __( 'Geeky Web Developer', 'dorzki' ) . "</b>";

הכנסת משתנים למחרוזת

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

// Bad!
$badString = __( 'The Blog has', 'dorzki' ) . $totalFollowers . __( 'Followers on Facebook', 'dorzki' );

// Good!
$goodString = sprintf( __( 'The Blog has %d Followers on Facebook', 'dorzki' ), $totalFollowers );

רווחים לבנים (White Spaces)

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

// Bad!
$badString = __( '        Hello There!        ', 'dorzki' );

// Good!
$goodString = __( 'Hello There!', 'dorzki' );

הוספת תיעוד למחרוזות

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

/* translators: This is to help you understand better where the string is from... */
$myString = __( 'Well Howdy!', 'dorzki' );

ביצוע לוקליזציה לקבצי JavaScript

כאמור פונקציות gettext הן ב-PHP לכן מה נעשה כאשר נרצה להכניס תרגום לקבצי JavaScript? למזלנו קיימת פונקציה ממש נחמדה של WordPress בשם wp_localize_script – ניתן לקרוא בהרחבה במאמר שכתבתי "שימוש בפונקציות gettext בקבצי JavaScript".

function dorzki_enqueue_script() {
  
  wp_enqueue_script( 'dorzki-js', get_template_directory_uri() . '/assets/js/scripts.js', false, '1.0.0', true );

  wp_localize_script( 'dorzki-js', 'langObj', array( 
    'greeting' => __( 'Hello World', 'dorzki' )
  ) );

}

add_actions( 'wp_enqueue_scripts', 'dorzki_enqueue_script' );

תרגום פרטי התוסף או התבנית

אז תרגמתם את כלל התבנית אבל אתם מעוניינים לתרגם גם את פרטי התוסף או התבנית? פשוט מאוד! הוסיפו את השורה הבאה לפרטי התוסף וכך יהיה אפשר לתרגם את פרטי התוסף.

Text Domain: dorzki

לא לשכוח להחליף את dorzki במזהה התרגום שלכם.

סיכום

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

בהצלחה!