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

{
  "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."
      },
      ...
    }
  },
  ...
}

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

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

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

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

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

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

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

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

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

קטע הקוד הבא, שנלקח מהקטע דוגמה, מציג פריט 'placeholders' שמכיל שני placeholders בשם 'our_site' ו-'user'. ל-placeholder‏ 'our_site' אין פריט 'example' כי הערך שלו ברור מהשדה 'content'.
"placeholders": {
  "our_site": {
    "content": "Example.com",
  },
  "user": {
    "content": "$1",
    "example": "Cira"
  }
}