דף זה תורגם על ידי 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 ו-bye:

{
  "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. לקבלת פרטים על אופן השימוש שבו נעשה שימוש בקובץ הודעות - לדוגמה, מה קורה כאשר לוקאל לא מגדיר את כל ההודעות — בינלאומיות.

שם

למעשה, אין שדה שנקרא 'name'. השם של השדה הזה הוא שם ההודעה – אותו שם שמופיע ב-__MSG__name___ או ב-getMessage("_name_").

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

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

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

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

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

דוגמאות נוספות לשימוש בשמות מפורטות בדף התאמה לשוק הבינלאומי.

הודעה

ההודעה המתורגמת, בצורת מחרוזת שיכולה להכיל 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 $$)"

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

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

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

תיאור

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

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

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

placeholders

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

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

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

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

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

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

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

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