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 שמזהה את המחרוזת. הערך של המחרוזת בלוקאל הזה. השדה האופציונלי 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, כך שתוכלו לזהות את הלוקאל הנוכחי של ממשק המשתמש, וכמה הודעות @@bidi_... שמאפשרות לכם לזהות את כיוון הטקסט. השמות של ההודעות האלה דומים לשמות של קבועים ב-API של BIDI (דו-כיווני) של הגאדג'טים.

אפשר להשתמש בהודעה המיוחדת @@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 באנגלית אמריקאית רואה את התווית Colors, משתמש באנגלית בריטית רואה את התווית Colours. משתמשים באנגלית אמריקאית ובאנגלית בריטית רואים את שם התוסף 'Hello World'. מכיוון ששפת ברירת המחדל היא ספרדית, משתמשים שמריצים את Google Chrome בכל שפה שאינה אנגלית רואים את התווית Colores ואת שם התוסף Hola mundo.

הגדרת הלוקאל בדפדפן

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

Windows

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

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

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

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

3. משנים את המאפיינים של קיצור הדרך כך שבשדה Target (יעד) יצוינו הדגלים --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. בוחרים בכרטיסייה Under the Hood (מאחורי הקלעים).
3. גוללים אל תוכן אינטרנט.
4. לוחצים על שינוי הגדרות הגופן והשפה.
5. לוחצים על הכרטיסייה שפות.
6. משתמשים בתפריט הנפתח כדי להגדיר את השפה ב-Google Chrome.
7. הפעלה מחדש של Chrome

Mac OS

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

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

Linux

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

LANGUAGE=es ./chrome

ChromeOS

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

1. במגש המערכת, בוחרים באפשרות הגדרות.
2. בקטע שפות וקלט, בוחרים בתפריט הנפתח שפה.
3. אם השפה שלכם לא מופיעה ברשימה, לוחצים על הוספת שפות ומוסיפים אותה.
4. אחרי שמוסיפים את השפה, לוחצים על סמל האפשרויות הנוספות ליד השפה ובוחרים באפשרות הצגת 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()

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

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,
): Promise<object>

chrome.i18n.getAcceptLanguages(): Promise<LanguageCode[]>

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

chrome.i18n.getUILanguage(): string