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

[לוקליזציה](http://he.wikipedia.org/wiki/%D7%9C%D7%95%D7%A7%D7%9C%D7%99%D7%96%D7%A6%D7%99%D7%94) או בקיצור (I18N) מתייחס לתהליך עיצוב אפליקצית תוכנה שהיא תוכל להיות תואמת למגוון של שפות ואזורים ללא ביצוע שינויים הדנסיים. עבור אפליקציות ווב, יש לאפשרות זו חשיבות רבה מאחר ומשתמשים יכולים להגיע מכל מקום בעולם.

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

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

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

שפה ואיזור
-------------------

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

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

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

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

עבור אפליקצית Yii, אנו מבדילים בין השפה [הנמצאת בשימוש|CApplication::language] לבין [שפת המקור|CApplication::sourceLanguage]. שפת השימוש היא השפה של המשתמשים שמשתמשים בה, בזמן ששפת המקור מתייחסת לשפה שקבצי המקור כתובים בה. לוקליזציה נעשית רק בזמן ששני השפות הללו שונות אחת מהשנייה.

ניתן להגדיר את [שפת השימוש|CApplication::language] [בהגדרות האפליקציה](/doc/guide/basics.application#application-configuration), או ניתן לשנותה בצורה דינאמית לפני כל ביצוע של לוקליזציה.

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

תרגום
-----------

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

בקשת תרגום כוללת את האובייקט שצריך לתרגם, שפת המקור בו האובייקט כתוב, ושפת היעד אליו האובייקט יתורגם. באפליקצית Yii, שפת המקור מוגדרת כברירת מחדל לערך המוגדר במאפיין [שפת המקור באפליקציה|CApplication::sourceLanguage] בזמן ששפת היעד מוגדרת לערך המיוצג על ידי המאפיין [שפת היעד באפליקציה|CApplication::language]. במידה ושפת המקור והיעד זהים התרגום לא מתבצע.

### תרגום הודעות

תרגום הודעות מתבצע על ידי שימוש ב-[()Yii::t|YiiBase::t]. המתודה מתרגמת את ההודעה [שפת המקור|CApplication::sourceLanguage] אל [שפת היעד|CApplication::language].

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

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

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

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

~~~
"Invalid
{$message} content."
~~~

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

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

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

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

- [CGettextMessageSource]: קבצי התרגום נשמרים כקבצי [GNU
Gettext](http://www.gnu.org/software/gettext/).

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

תרגום ההודעות נטען [כרכיב אפליקציה](/doc/guide/basics.application#application-component). המערכת טוענת מראש רכיב אפליקציה בשם [messages|CApplication::messages] כדי לאחסן הודעות אשר נמצאות בשימוש על ידי האפליקציה של המשתמש. כברירת מחדל, סוג הרכיב של תרגום ההודעות הינו [CPhpMessageSource] והתיקיה בה שמורים קבצי ה-PHP המכילים את התרגומים נמצא תחת `protected/messages`.

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


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

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

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

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

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

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

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

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

~~~
[php]
'expr1#message1|expr2#message2|expr3#message3'
~~~

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

~~~
[php]
'n==1#one book|n>1#many books'
~~~

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

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

~~~
[php]
'1#one book|n>1#many books'
~~~


### תרגום קבצים

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

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

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

תצוגת תאריך ושעה
------------------------

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

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

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

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

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

- [formatDateTime|CDateFormatter::formatDateTime]: מתודה זו מציגה את הזמן הנתון בפורמט UNIX כסטרינג רגיל בהתאם לדפוס שהוגדר **מראש** בהגדרות השפה (לדוגמא, `short` , `long`)

תצוגת ספרות (מספרים)
-----------------

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

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

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

- [format|CNumberFormatter::format]: מתודה זו מציגה את המספר הנתון בהתאם לדפוס שהוגדר, לדוגמא,

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

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

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

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

<div class="revision">$Id: topics.i18n.txt 2069 2009-12-26 20:56:05Z qiang.xue $</div>