ריבוי שפות / לוקליזציה

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

Yii מספק תמיכה עבור I18N בכמה היבטים.

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

בחלק הבא, אנו נפרט לגבי כל אחד ואחד מההיבטים הרשומים למעלה.

1. שפה ואיזור ¶

איזור הוא סט של פרמטרים המגדיר את שפת המשתמש, המדינה והגדרות נוספות שהמשתמש רוצה לראות בממשק שלו. איזור בדרך כלל מזוהה על ידי מזהה יחודי המכיל את המזהה היחודי של השפה והמזהה היחודי של המחוז. לדוגמא, המזהה היחודי en_US מייצג את האיזור של אנגלית - ארה"ב. למטרת עקביות, כל המזהים היחודיים ב-Yii נכתבים בפורמט של LanguageID או LanguageID_RegionID באותיות קטנות בלבד (לדוגמא en, en_us).

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

עם קבלת המזהה היחודי של האיזור או השפה, ניתן לקבל את האובייקט של CLocale על ידי קריאה ל CLocale::getInstance($localeID) או CApplication::getLocale($localeID).

מידע: Yii מגיע עם מידע איזורי עבור כמעט כל שפה ואיזור. המידע מתקבל מ-Common Locale Data Repository (CLDR). עבור כל שפה, רק חלק מהמידע המקורי ב CLDR נמצא בקבצי המידע של כל שפה מאחר והמידע המקורי מכיל מידע רב שבדרך כלל לא נעשה בו שימוש. החל מגרסא 1.1.0, משתמשים יכולים לספק את המידע אודות השפה שלהם בהתאמה אישית. בכדי לעשות זאת, יש להגדיר את המאפיין CApplication::localeDataPath עם הנתיב לתיקיה המכילה את המידע עבור השפות. יש לעיין בקבצי המידע של השפות הנמצאות תחת framework/i18n/data בכדי ליצור קבצים מותאמים אישית.

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

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

טיפ: לפעמים, אנו נרצה להגדיר את שפת השימוש לשפה המועדפת על ידי המשתמש (המוגדרת בהגדרות הדפדפן של המשתמש). בכדי לבצע זאת, אנו יכולים לקבל את השפה המועדפת על המשתמש על ידי CHttpRequest::preferredLanguage.

2. תרגום ¶

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

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

תרגום הודעות

תרגום הודעות מתבצע על ידי שימוש ב-()Yii::t. המתודה מתרגמת את ההודעה שפת המקור אל שפת היעד.

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

הודעות יכולות להכיל פרמטרים אשר יוחלפו עם הערכים שלהם בזמן השימוש (קריאה) למתודה ()Yii::t. לדוגמא, בבקשת תרגום ההודעה הבאה הפרמטר {alias} בהודעה המקורית יוחלף עם הערך שהוגדר לו.

Yii::t('app', 'Path alias "{alias}" is redefined.',
    array('{alias}'=>$alias))

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

"Invalid
{$message} content."

יש להשתמש בפרמטרים כמו בדוגמא הקודמת במידה וההודעה צריכה להכיל משתנים ומידע אשר משתנה בהתאם לפרמטר כלשהו.

הודעות מתורגמות שמורות בספריה הנקראת מקור הודעות (message source). מקור הודעה מיוצג כאובייקט של CMessageSource או מחלקות היורשות ממנו. בעת הקריאה למתודה ()Yii::t, המתודה תחפש את ההודעה במקור ההודעות ותחזיר את הגרסא המתורגמת של ההודעה במידה והיא נמצאה.

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

• CPhpMessageSource: הודעות התרגום שמורות במערך של אלמנטים המכילים מפתח=>ערך. ההודעה המקורית היא המפתח בכל אלמנט במערך והתרגום הוא הערך בכל אלמנט במערך. כל מערך מייצג תרגום של הודעות בקטגוריה ספציפית והמערך שמור בקובץ PHP נפרד ששמו של הקובץ הוא שם הקטגוריה. קבצי התרגום של אותה שפה נמצאים תחת אותה תיקיה ששמה הוא שם המזהה היחודי של השפה (לדוגמא en, he, de). וכל תיקיות השפות הללו נמצאות תחת התיקיה המוגדרת על ידי basePath.

• CGettextMessageSource: קבצי התרגום נשמרים כקבצי GNU Gettext.

• CDbMessageSource: ההודעות המתורגמות שמורות בטבלאות במסד הנתונים. למידע נוסף יש לעיין בדוקומנטציה של CDbMessageSource.

תרגום ההודעות נטען כרכיב אפליקציה. המערכת טוענת מראש רכיב אפליקציה בשם messages כדי לאחסן הודעות אשר נמצאות בשימוש על ידי האפליקציה של המשתמש. כברירת מחדל, סוג הרכיב של תרגום ההודעות הינו CPhpMessageSource והתיקיה בה שמורים קבצי ה-PHP המכילים את התרגומים נמצא תחת protected/messages.

לסיכום, בכדי להשתמש בתרגום הודעות, יש לבצע את השלבים הבאים:

1. להשתמש ב ()Yii::t במקומות שההודעות צריכות להיות על פי שפה;

2. ליצור קבצי PHP אשר יכילו את התרגום תחת protected/messages/LocaleID/CategoryName.php. כל קובץ מחזיר מערך של הודעות מתורגמות. יש לזכור שדוגמא זו יוצאת מנוקדת הנחה שהינך משתמש ברכיב תרגום ההודעות ברירת המחדל שהוא CPhpMessageSource כדי לאחסן את ההודעות המתורגמות.

3. יש להגדיר את CApplication::sourceLanguage ו CApplication::language

טיפ: הכלי yiic בתוך המערכת של Yii יכול להיות לכלי עזר שימושי לניהול תרגום הודעות בעת השימוש ב-CPhpMessageSource כרכיב התרגום. הפקודה message יכולה לחלץ הודעות שדורשות תרגום מקבצי מקור בצורה אוטומטית ולאחד אותם עם קבצי תרגום קיימים.

החל מגרסא 1.0.10, בזמן השימוש ב-CPhpMessageSource לניהול ההודעות, הודעות עבור מחלקות של וידג'טים, תוספים, מודולים ניתן לנהל ולהשתמש בהם בצורה מיוחדת. במיוחד, אם הודעה שייכת לתוסף ששם המחלקה שלו הוא Xyz, אז ניתן להגדיר את שם הקטגוריה של ההודעה בפורמט של Xyz.categoryName. קובץ ההודעות יהיה BasePath/messages/LanguageID/categoryName.php, כש-BasePath מתייחס לתיקיה שבה קובץ המחלקה של התוסף נמצא. ובעת השימוש ב Yii::t() בכדי לתרגם הודעה של תוסף, יש להשתמש בפורמט הבא במקום:

Yii::t('Xyz.categoryName', 'הודעה לתרגום')

החל מגרסא 1.0.2, Yii הוסיפה תמיכה עבור פורמט בחירה. פורמט בחירה מתייחס לבחירת נתון מתורגם בהתאם לערך המספרי. לדוגמא, בשפה האנגלית המילה book יכולה להיות במונח של יחיד או רבים בהתאם לכמות הספרים, בזמן שבשפות אחרות המילה הזו נשארת באותו מצב עבור יחיד או רבים (כמו סינית) או מכילה כללים יותר מסובכים עבור רבים (כמו ברוסית). פורמט בחירה פותר בעיה זו באופן פשוט אך יעיל.

בכדי להשתמש בפורמט בחירה, הודעה מתורגמת צריכה להכיל רצף של זוגות ביטויים המופרדים ב-|, כפי שמוצג בדוגמא הבאה:

'expr1#message1|expr2#message2|expr3#message3'

כשהביטוי exprN מתייחס לביטוי PHP אשר תוצאתו שווה לערך בוליאני (true/false) המעיד אם ההודעה המדוברת היא זו שצריכה להיות מוצגת. רק ההודעה הראשונה אשר תוצאת הביטוי תחזיר true תוצג. ביטוי יכול להכיל משתנה מיוחד בשם n (שים לב שם המשתנה הוא n לא n$) אשר מייצג את הערך המספרי כפרמטר ראשון שעליו מתבצעת הבדיקה. לדוגמא, נניח והודעה מתורגמת הינה:

'n==1#one book|n>1#many books'

ואנו מעבירים ערך מספרי השווה ל 2 למערך הפרמטרים של ההודעה בעת הקריאה ל ()Yii::t, אנו נקבל many book בהודעה המתורגמת הסופית.

בכדי לקצר את התחביר, אם הביטוי הוא מספר, הוא מקבל יחס של n==Number. לכן, את ההודעה המתורגמת למעלה ניתן לכתוב בצורה הבאה:

'1#one book|n>1#many books'

תרגום קבצים

תרגום קבצים נעשה על ידי קריאה ל - CApplication::findLocalizedFile(). עם הנתיב לקובץ שצריך לתרגם, המתודה תחפש את הקובץ עם אותו השם תחת תיקיה ששמה הוא שם האיזור לתרגום (LocaleID). במידה ונמצא הנתיב לקובץ יוחזר; אחרת, הנתיב המקורי יוחזר.

תרגום קבצים נועד בעיקר בעת הצגת קובץ תצוגה. בעת הקריאה לאחת ממתודות התצוגה בקונטרולר או וידג'ט, קבצי התצוגה יתורגמו אוטומטית. לדוגמא, אם שפת היעד הינה zh_cn בזמן ששפת המקור הינה en_us, הצגת קובץ תצוגה בשם edit יגרום לחיפוש אחר קובץ התצוגה תחת התיקיה protected/views/ControllerID/zh_cn/edit.php. במידה והקובץ נמצא, גרסא מתורגמת זו היא זו שתוצג; אחרת, הקובץ protected/views/ControllerID/edit.php יוצג במקום.

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

3. תצוגת תאריך ושעה ¶

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

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

מחלקת CDateFormatter מספקת בעיקר שני מתודות עבור תצוגה של זמן בפורמט UNIX.

• format: מתודה זו מציגה את הזמן הנתון בפורמט UNIX כסטרינג רגיל בהתאם לדפוס שהוגדר, לדוגמא,

$dateFormatter->format('yyyy-MM-dd',$timestamp)

• formatDateTime: מתודה זו מציגה את הזמן הנתון בפורמט UNIX כסטרינג רגיל בהתאם לדפוס שהוגדר מראש בהגדרות השפה (לדוגמא, short , long)

4. תצוגת ספרות (מספרים) ¶

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

בכדי להשתמש בתצוגת ספרות על פי שפת היעד לאורך כל האפליקציה ניתן להשתמש במאפיין numberFormatter באפליקציה.

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

• format: מתודה זו מציגה את המספר הנתון בהתאם לדפוס שהוגדר, לדוגמא,

$numberFormatter->format('#,##0.00',$number)

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

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

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