דף זה תורגם על ידי Cloud Translation API.

פורמטים של הודעות בהתאמה לשוק המקומי

לכל תוסף או אפליקציה בינלאומיים יש לפחות קובץ אחד בשם messages.json שמספק מחרוזות ספציפיות ללוקאל. בדף הזה מתואר הפורמט של messages.json קבצים. לקבלת מידע על כיצד להפוך לבינלאומי ולבצע לוקליזציה, ראה את הדף Internationalization.

סיכום השדות

הקוד הבא מציג את השדות הנתמכים של messages.json. רק name ו-"message" השדות הם שדות חובה.

{
  "name": {
    "message": "Message text, with optional placeholders.",
    "description": "Translator-aimed description of the message.",
    "placeholders": {
      "placeholder_name": {
        "content": "A string to be placed within the message.",
        "example": "Translator-aimed example of the placeholder string."
      },
      ...
    }
  },
  ...
}

דוגמה

הנה קובץ messages.json שמגדיר שלוש הודעות בשם "prompt_for_name", "hello" ו- "להתראות":

{
  "prompt_for_name": {
    "message": "What's your name?",
    "description": "Ask for the user's name"
  },
  "hello": {
    "message": "Hello, $USER$",
    "description": "Greet the user",
    "placeholders": {
      "user": {
        "content": "$1",
        "example": "Cira"
      }
    }
  },
  "bye": {
    "message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!",
    "description": "Say goodbye to the user",
    "placeholders": {
      "our_site": {
        "content": "Example.com",
      },
      "user": {
        "content": "$1",
        "example": "Cira"
      }
    }
  }
}

פרטי השדה

בקטע הזה מתואר כל שדה שיכול להופיע בקובץ messages.json. לקבלת פרטים על אופן השימוש שבו נעשה שימוש בקובץ הודעות - לדוגמה, מה קורה כאשר לוקאל לא מגדיר את כל ההודעות - בינלאומיות.

שם

למעשה, אין שדה בשם 'שם'. שם השדה הזה הוא שם ההודעה — אותו שם שמוצג ב__MSG__name___ או בgetMessage("_name_").

השם הוא מפתח לא תלוי-רישיות שמאפשר לאחזר את הטקסט של ההודעה שהותאם לשוק המקומי. השם יכול כוללים את התווים הבאים:

א'-ת'
a-z
0-9
_ (קו תחתון)
@

הערה: אין להגדיר שמות שמתחילים ב-'@@'. השמות האלה שמורים להודעות מוגדרות מראש.

הנה שלוש דוגמאות לשמות שנלקחים מהקטע דוגמה:

"prompt_for_name": {
  ...
},
"hello": {
  ...
},
"bye": {
  ...
}

דוגמאות נוספות לשימוש בשמות מופיעות בדף Internationalization.

הודעה

ההודעה המתורגמת, בפורמט של מחרוזת שיכולה להכיל placeholders. כדאי להשתמש $_placeholder_name_$ (לא תלוי-רישיות) כדי להפנות ל-placeholder מסוים. לדוגמה, אפשר: להפנות ל-placeholder בשםour_site בתור $our_site$ , $OUR_SITE$ או $oUR_sITe$ .

הנה שלוש דוגמאות להודעות שנלקחו מהקטע דוגמה:

"message": "What's your name?"
...
"message": "Hello, $USER$"
...
"message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"

כדי להוסיף סימן דולר ($) למחרוזת, צריך להשתמש בסימן $$. For example, use the following code to specify the message Amount (in $):

"message": "Amount (in $$)"

למרות ש-placeholders כמו $USER$ הם הדרך המועדפת להתייחס למחרוזות החלפה (מחרוזות שצוינו באמצעות הפרמטר substitutions של i18n.getMessage) אפשר גם להפנות להחליף מחרוזות ישירות בתוך ההודעה. לדוגמה, ההודעה הבאה מתייחסת שלוש מחרוזות ההחלפה הראשונות שמועברות אל getMessage():

"message": "Params: $1, $2, $3"

למרות הדוגמה הזו, מומלץ להשתמש ב-placeholders במקום במחרוזות $_n_. בהודעות. אפשר לחשוב על placeholders כעל שמות טובים של משתנים. שבוע אחרי שכתבתם סביר להניח שתשכחו את המונח $1, אבל תדעו למה מציינים את ה-placeholders. מידע נוסף על placeholders ומחרוזות החלפה זמין בקטע placeholders.

תיאור

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

הנה שלוש דוגמאות לתיאורים שנלקחים מהקטע דוגמה:

"description": "Ask for the user's name"
...
"description": "Greet the user"
...
"description": "Say goodbye to the user"

ערכי placeholder

אופציונלי. מגדירה מחרוזת משנה אחת או יותר לשימוש בתוך ההודעה. הנה שתי סיבות לכך כדאי להשתמש ב-placeholder:

כדי להגדיר את הטקסט של חלק בהודעה שלא צריך לתרגם. דוגמאות: קוד HTML, שמות מסחריים, מצייני פורמט.
הפניה למחרוזת החלפה שהועברה אל getMessage(). לדוגמה: $1.

לכל placeholder יש שם, 'תוכן' ו'דוגמה' אופציונלית שימושי. שם של placeholder הוא לא תלוי רישיות ויכול לכלול את אותם תווים כמו שם ההודעה.

השדה 'תוכן' 'הערך של הפריט' הוא מחרוזת שיכולה להתייחס למחרוזות החלפה, שצוינו באמצעות הפרמטר substitutions של השיטה i18n.getMessage. הערך של תוכן הפריט הוא בדרך כלל משהו כמו "Example.com" או '$1'. אם מפנים למחרוזת החלפה שלא מקבלים מחרוזת ריקה. בטבלה הבאה אפשר לראות את ההתאמה של מחרוזות $_n_ למחרוזות שצוין באמצעות הפרמטר subsExchanges.

הפרמטר substitutions	הערך של 1$	ערך של 8 ש"ח	הערך של 3$
`userName`	הערך של `userName`	`""`	`""`
`["Cira", "Kathy"]`	`"Cira"`	`"Kathy"`	`""`

"דוגמה" item (אופציונלי, אבל מומלץ מאוד) עוזר למתרגמים על ידי הצגת האופן שבו התוכן תוצג למשתמש הקצה. לדוגמה, placeholder של סכום בדולרים צריך לכלול דוגמה כמו "$23.45"

בקטע הקוד הבא, שנלקח מהקטע דוגמה, מוצגים placeholders פריט ש מכיל שני ערכי placeholder שנקראיםour_site ו-'user'. רכיב 'our_site' ל-placeholder אין 'דוגמה' מכיוון שהערך שלו בולט לעין השדה הזה.

"placeholders": {
  "our_site": {
    "content": "Example.com",
  },
  "user": {
    "content": "$1",
    "example": "Cira"
  }
}