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

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

סיכום השדה

הקוד הבא מציג את השדות הנתמכים של 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. למידע נוסף על אופן השימוש בקובץ ההודעות (לדוגמה, מה קורה כשלוקאל לא מגדיר את כל ההודעות), תוכלו לקרוא את המאמר Internationalization.

name

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

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

• A-Z
• a-z
• 0-9
• _ (קו תחתון)
• @

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

messages.json:

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

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

הודעה

ההודעה המתורגמת, בצורת מחרוזת שיכולה להכיל 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$ הם הדרך המועדפת להתייחס למחרוזות החלפה (מחרוזות שמצוינות באמצעות הפרמטר substitus של i18n.getMessage), אבל אפשר גם להתייחס למחרוזות החלפה ישירות בתוך ההודעה. לדוגמה, ההודעה הבאה מתייחסת לשלוש מחרוזות ההחלפה הראשונות שהועברו אל getMessage():

messages.json:
"message": "Params: $1, $2, $3"

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

תיאור

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

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

messages.json:
"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' הוא מחרוזת שיכולה להתייחס למחרוזות החלפה, שמצוינות באמצעות הפרמטר החלפות של השיטה i18n.getMessage. הערך של פריט 'content' הוא בדרך כלל כמו 'Example.com' או '$1'. אם אתם מפנים למחרוזת החלפה שלא קיימת, מקבלים מחרוזת ריקה. הטבלה הבאה מראה איך מחרוזות $_n_ מתאימות למחרוזות שמצוינות באמצעות הפרמטר substitus.

הפרמטר substitutions
ערך של 4 ש"ח
ערך של 8 ש"ח
ערך של 12 ש"ח
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"
  }
}