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

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

סיכום השדות

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

messages.json:

{
  "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:

messages.json:

{
  "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
  • _ (קו תחתון)
  • @

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

messages.json:

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

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

הודעה

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

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

messages.json:

"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 $):

messages.json:

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


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



messages.json:


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



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



תיאור



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



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



messages.json:


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



ערכי placeholder



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



    

  • כדי להגדיר את הטקסט של חלק מההודעה שלא צריך לתרגם. דוגמאות: קוד HTML, שמות של סימנים מסחריים, מפרטים של עיצוב.
    • 

  • הפניה למחרוזת החלפה שהועברה אל getMessage(). דוגמה: $1.
    • 




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



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



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



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



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



messages.json:


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