chrome.i18n

תיאור

מניפסט

אם לתוסף יש ספרייה /_locales, צריך להגדיר את "default_locale" במניפסט.

מושגים ושימוש

צריך להעביר את כל המחרוזות שגלויות למשתמש לקובץ בשם messages.json. בכל פעם שמוסיפים לוקאל חדש, מוסיפים קובץ הודעות בספרייה בשם /_locales/_localeCode_, כאשר localeCode הוא קוד כמו en לאנגלית.

זוהי היררכיית הקבצים של תוסף בינלאומי שתומך באנגלית (en), בספרדית (es) ובקוריאנית (ko):

תמיכה במספר שפות

נניח שיש לכם תוסף עם הקבצים שמוצגים באיור הבא:

כדי להתאים את התוסף הזה לשוק הבינלאומי, צריך לתת שם לכל מחרוזת שגלויה למשתמשים ולהוסיף אותה לקובץ הודעות. המניפסט, קובצי ה-CSS וקוד ה-JavaScript של התוסף משתמשים בשם של כל מחרוזת כדי לקבל את הגרסה המתורגמת שלה.

כך נראה התוסף אחרי ההתאמה הגלובלית (שימו לב שעדיין יש בו רק מחרוזות באנגלית):

כמה הערות לגבי התאמה לשוק הבינלאומי:

• אפשר להשתמש בכל אחת מהשפות הנתמכות. אם משתמשים באזור לא נתמך, Google Chrome מתעלם ממנו.

• בקובצי manifest.json ו-CSS, מפנים למחרוזת בשם messagename באופן הבא:

  __MSG_messagename__
  

• בקוד ה-JavaScript של התוסף או האפליקציה, מפנים למחרוזת בשם messagename באופן הבא:

  chrome.i18n.getMessage("messagename")
  

• בכל קריאה ל-getMessage(), אפשר לספק עד 9 מחרוזות שייכללו בהודעה. לפרטים נוספים, ראו דוגמאות: getMessage.

• הודעות מסוימות, כמו @@bidi_dir ו-@@ui_locale, מסופקות על ידי מערכת ההתאמה לשוק הבינלאומי. בקטע הודעות מוגדרות מראש מופיעה רשימה מלאה של שמות של הודעות מוגדרות מראש.

• ב-messages.json, לכל מחרוזת שגלויה למשתמשים יש שם, פריט 'message' ופריט 'description' אופציונלי. השם הוא מפתח כמו 'extName' או 'search_string' שמזהה את המחרוזת. השדה message מציין את הערך של המחרוזת באותו אזור גיאוגרפי. השדה האופציונלי 'description' עוזר למתורגמנים, שיכול להיות שלא יוכלו לראות איך משתמשים במחרוזת בתוסף. לדוגמה:

  {
    "search_string": {
      "message": "hello%20world",
      "description": "The string we search for. Put %20 between words that go together."
    },
    ...
  }
  

מידע נוסף זמין במאמר פורמטים: הודעות ספציפיות לאזור.

אחרי שמבצעים תהליך של עיבוד לתמיכה בשפות שונות בתוסף, קל לתרגם אותו. מעתיקים את messages.json, מתרגמים אותו ומעבירים את העותק לספרייה חדשה ב-/_locales. לדוגמה, כדי לתמוך בספרדית, פשוט מוסיפים עותק מתורגם של messages.json בקטע /_locales/es. באיור הבא מוצג התוסף הקודם עם תרגום חדש לספרדית.

הודעות מוגדרות מראש

מערכת ההתאמה הגלובלית מספקת כמה הודעות מוגדרות מראש שיעזרו לכם לבצע לוקליזציה. אלה כוללים את @@ui_locale, כדי שתוכלו לזהות את ה-locale הנוכחי של ממשק המשתמש, וכמה הודעות @@bidi_... שמאפשרות לכם לזהות את כיוון הטקסט. לשמות של ההודעות האחרונות יש שמות דומים למשתנים קבועים ב-gadgets BIDI (bi-directional) API.

אפשר להשתמש בהודעה המיוחדת @@extension_id בקובצי ה-CSS וה-JavaScript, גם אם התוסף או האפליקציה לא מותאמים לשוק המקומי. ההודעה הזו לא פועלת בקובצי מניפסט.

בטבלה הבאה מתוארות כל ההודעות שמוגדרות מראש.

דוגמה לשימוש ב-@@extension_id בקובץ CSS כדי ליצור כתובת URL:

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

אם מזהה התוסף הוא abcdefghijklmnopqrstuvwxyzabcdef, השורה המודגשת בקטע הקוד הקודם תהפוך ל:

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

דוגמה לשימוש בהודעות @@bidi_* בקובץ CSS:

body {
  direction: __MSG_@@bidi_dir__;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi_start_edge__: 0;
  padding-__MSG_@@bidi_end_edge__: 1.5em;
  position: relative;
}

בשפות שנכתבות משמאל לימין, כמו אנגלית, הקווים המודגשים הופכים ל:

  dir: ltr;
  padding-left: 0;
  padding-right: 1.5em;

לוקאלים

אפשר לבחור מבין הרבה אזורים גיאוגרפיים, כולל אזורים מסוימים (כמו en) שמאפשרים לתרגום יחיד לתמוך בכמה וריאציות של שפה (כמו en_GB ו-en_US).

אתם יכולים להתאים את התוסף לכל אזור גיאוגרפי שנתמך בחנות האינטרנט של Chrome. אם האזור לא מופיע ברשימה, בוחרים באפשרות החלופית הקרובה ביותר. לדוגמה, אם אזור ברירת המחדל של התוסף הוא "de_CH", בוחרים באפשרות "de" בחנות האינטרנט של Chrome.

חיפוש הודעות

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

1. מחפשים את האזור המועדף על המשתמש בקובץ ההודעות (אם יש כזה). לדוגמה, כשהשפה והאזור של Google Chrome מוגדרים לאנגלית בריטית (en_GB), המערכת מחפשת את ההודעה קודם ב-/_locales/en_GB/messages.json. אם הקובץ הזה קיים וההודעה נמצאת בו, המערכת לא ממשיכה לחפש.
2. אם ללוקאל המועדף של המשתמש יש אזור (כלומר, ללוקאל יש קו תחתון: _), מחפשים את הלוקאל בלי האזור הזה. לדוגמה, אם קובץ ההודעות en_GB לא קיים או שהוא לא מכיל את ההודעה, המערכת מחפשת את ההודעה בקובץ ההודעות en. אם הקובץ הזה קיים וההודעה מופיעה בו, המערכת לא ממשיכה לחפש.
3. מחפשים את מקום ברירת המחדל בקובץ ההודעות. לדוגמה, אם הערך של default_locale בתוסף מוגדר כ-es, וגם /_locales/en_GB/messages.json וגם /_locales/en/messages.json לא מכילים את ההודעה, התוסף ישתמש בהודעה מ-/_locales/es/messages.json.

באיור הבא, ההודעה 'colores' מופיעה בכל שלוש הגרסאות המקומיות שהתוסף תומך בהן, אבל 'extName' מופיעה רק בשתי הגרסאות המקומיות. אם משתמש שמשתמש ב-Google Chrome באנגלית ארה"ב רואה את התווית 'צבעים', משתמש שמשתמש באנגלית בריטית רואה את התווית 'צבעים'. גם משתמשים באנגלית אמריקאית וגם משתמשים באנגלית בריטית רואים את שם התוסף 'Hello World'. שפת ברירת המחדל היא ספרדית, ולכן משתמשים שמפעילים את Google Chrome בשפה שאינה אנגלית רואים את התווית 'Colores' ואת שם התוסף 'Hola mundo'.

הגדרת האזור של הדפדפן

כדי לבדוק את התרגומים, מומלץ להגדיר את האזור של הדפדפן. בקטע הזה מוסבר איך להגדיר את האזור ב-Windows, ב-Mac OS, ב-Linux וב-ChromeOS.

Windows

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

שימוש במקש קיצור ספציפי לאזור

כדי ליצור קיצור דרך ולהשתמש בו כדי להפעיל את Google Chrome עם אזור זמן מסוים:

1. יוצרים עותק של קיצור הדרך ל-Google Chrome שכבר נמצא במחשב.
2. משנים את השם של קיצור הדרך החדש כך שיתאים לאזור הזמן החדש.

3. משנים את המאפיינים של קיצור הדרך כך ששדה היעד יציין את הדגלים --lang ו---user-data-dir. היעד אמור להיראות כך:

   path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
   

4. לוחצים פעמיים על קיצור הדרך כדי להפעיל את Google Chrome.

לדוגמה, כדי ליצור קיצור דרך שיפעיל את Google Chrome בספרדית (es), אפשר ליצור קיצור דרך בשם chrome-es עם היעד הבא:

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

אתם יכולים ליצור כמה קיצורי דרך שתרצו, וכך לבדוק בקלות בכמה שפות. לדוגמה:

path_to_chrome.exe --lang=en --user-data-dir=c:\chrome-profile-en
path_to_chrome.exe --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB
path_to_chrome.exe --lang=ko --user-data-dir=c:\chrome-profile-ko

שימוש בממשק המשתמש

כך משנים את האזור באמצעות ממשק המשתמש ב-Google Chrome ל-Windows:

1. סמל האפליקציה > אפשרויות
2. בוחרים בכרטיסייה בתוך הדפדפן.
3. גוללים אל תוכן אינטרנט.
4. לוחצים על שינוי הגדרות הגופן והשפה.
5. בוחרים בכרטיסייה שפות.
6. משתמשים בתפריט הנפתח כדי להגדיר את השפה של Google Chrome.
7. הפעלה מחדש של Chrome

Mac OS

כדי לשנות את הלוקאל ב-Mac, משתמשים בהעדפות המערכת.

1. בתפריט Apple, בוחרים באפשרות העדפות המערכת.
2. בקטע Personal (אישי), בוחרים באפשרות International (בינלאומי).
3. בחירת השפה והמיקום
4. הפעלה מחדש של Chrome

Linux

כדי לשנות את האזור ב-Linux, קודם צריך לצאת מ-Google Chrome. לאחר מכן, כולם בשורה אחת, מגדירים את משתנה הסביבה LANGUAGE ומפעילים את Google Chrome. לדוגמה:

LANGUAGE=es ./chrome

ChromeOS

כדי לשנות את הלוקאל ב-ChromeOS:

1. בוחרים באפשרות הגדרות בסרגל האפליקציות.
2. בקטע שפות וקלט, בוחרים בתפריט הנפתח שפה.
3. אם השפה הרצויה לא מופיעה ברשימה, לוחצים על הוספת שפות ומוסיפים אותה.
4. אחרי שמוסיפים את השפה, לוחצים על סמל 3 הנקודות More actions (פעולות נוספות) ליד השפה ובוחרים באפשרות Display ChromeOS in this language (הצגת ChromeOS בשפה הזו).
5. לוחצים על הלחצן הפעלה מחדש שמופיע לצד השפה שהוגדרה כדי להפעיל מחדש את ChromeOS.

דוגמאות

דוגמאות לאינטרנציונליזציה מפורטות בספרייה examples/api/i18n. דוגמה מלאה זמינה ב-examples/extensions/news. דוגמאות נוספות ועזרה בהצגת קוד המקור זמינות במאמר דוגמאות.

getMessage()

הקוד הבא מקבל מהדפדפן הודעה מותאמת לשפה ומציג אותה כמחרוזת. הפונקציה מחליפה שני placeholders בהודעה במחרוזות "string1" ו-"string2".

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

כך מספקים מחרוזת אחת ומשתמשים בה:

  // In JavaScript code
  status.innerText = chrome.i18n.getMessage("error", errorDetails);

"error": {
  "message": "Error: $details$",
  "description": "Generic error template. Expects error parameter to be passed in.",
  "placeholders": {
    "details": {
      "content": "$1",
      "example": "Failed to fetch RSS feed."
    }
  }
}

מידע נוסף על placeholders זמין בדף הודעות ספציפיות לשפה. פרטים על קריאה ל-getMessage() זמינים בחומר העזרה של ה-API.

getAcceptLanguages()

הקוד הבא מקבל את שפות ה-accept מהדפדפן ומציג אותן כמחרוזת, על ידי הפרדה בין כל שפת accept באמצעות ','.

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

פרטים על קריאה ל-getAcceptLanguages() זמינים בחומר העזרה של ה-API.

detectLanguage()

הקוד הבא מזהה עד 3 שפות מהמחרוזת שצוינה ומציג את התוצאה כמחרוזות המופרדות באמצעות מעברי שורה.

function detectLanguage(inputText) {
  chrome.i18n.detectLanguage(inputText, function(result) {
    var outputLang = "Detected Language: ";
    var outputPercent = "Language Percentage: ";
    for(i = 0; i < result.languages.length; i++) {
      outputLang += result.languages[i].language + " ";
      outputPercent +=result.languages[i].percentage + " ";
    }
    document.getElementById("languageSpan").innerHTML = outputLang + "\n" + outputPercent + "\nReliable: " + result.isReliable;
  });
}

פרטים נוספים על קריאה ל-detectLanguage(inputText) זמינים בחומר העזרה של ה-API.

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

chrome.i18n.getMessage(
  messageName: string,
  substitutions?: any,
  options?: object,
)

chrome.i18n.getUILanguage()