browser.i18n

תיאור

משתמשים בתשתית של chrome.i18n כדי להטמיע התאמה לשוק הבינלאומי בכל האפליקציה או התוסף.

מניפסט

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

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

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

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

בספריית התוספים: manifest.json,‏ ‎*.html,‏ ‎*.js,‏ ספריית ‎/_locales. בספרייה ‎ /_locales: הספריות en,‏ es ו-ko, שבכל אחת מהן יש קובץ messages.json.

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

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

קובץ manifest.json וקובץ עם JavaScript. בקובץ ה-‎ .json יש את הטקסט "Hello World". בקובץ ה-JavaScript יש את הכותרת "Hello World".

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

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

בקובץ manifest.json, הערך "Hello World" השתנה ל-"__MSG_extName__", והפריט החדש default_locale קיבל את הערך "en". בקובץ ה-JavaScript, הערך "Hello World" השתנה ל-browser.i18n.getMessage('extName').‎ קובץ חדש בשם ‎ /_locales/en/messages.json מגדיר את extName.

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

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

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

    __MSG_messagename__

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

    browser.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. בתמונה הבאה מוצג התוסף הקודם עם תרגום חדש לספרדית.

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

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

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

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

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

שם ההודעהתיאור
@@extension_idמזהה האפליקציה או התוסף. אפשר להשתמש במחרוזת הזו כדי ליצור כתובות URL למשאבים בתוך התוסף. גם תוספים שלא עברו לוקליזציה יכולים להשתמש בהודעה הזו.
הערה: אי אפשר להשתמש בהודעה הזו בקובץ מניפסט.
@@ui_localeהלוקאל הנוכחי. אפשר להשתמש במחרוזת הזו כדי ליצור כתובות URL ספציפיות ללוקאל.
@@bidi_dirכיוון הטקסט של הלוקאל הנוכחי, "ltr" לשפות שנכתבות משמאל לימין כמו אנגלית, או "rtl" לשפות שנכתבות מימין לשמאל כמו ערבית.
@@bidi_reversed_dirאם הערך של @@bidi_dir הוא "ltr", הערך הזה הוא "rtl". אחרת, הערך הוא "ltr".
@@bidi_start_edgeאם הערך של @@bidi_dir הוא "ltr", הערך של המאפיין הזה הוא "left". אחרת, הערך הוא "right".
@@bidi_end_edgeאם הערך של @@bidi_dir הוא "ltr", הערך של המאפיין הזה הוא "right". אחרת, הערך הוא "left".

הנה דוגמה לשימוש ב-@@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.

קוד לוקאל שפה (אזור)
ar ערבית
am אמהרית
bg בולגרית
bn בנגלית
ca קטלאנית
cs צ'כית
da דנית
de גרמנית
el יוונית
en אנגלית
en_AU אנגלית (אוסטרליה)
en_GB אנגלית (בריטניה)
en_US אנגלית (ארה"ב)
es ספרדית
es_419 ספרדית (אמריקה הלטינית והקריביים)
et אסטונית
fa פרסית
fi פינית
fil פיליפינית
fr צרפתית
gu גוג'ארטי
he עברית
hi הינדי
hr קרואטית
hu הונגרית
id אינדונזית
it איטלקית
ja יפנית
kn קנאדה
ko קוריאנית
lt ליטאית
lv לטבית
ml מליאלאם
mr מראטהית
ms מלאית
nl הולנדית
no נורווגית
pl פולנית
pt_BR פורטוגזית (ברזיל)
pt_PT פורטוגזית (פורטוגל)
ro רומנית
ru רוסית
sk סלובקית
sl סלובנית
sr סרבית
sv שוודית
sw סווהילי
ta טמילית
te טלוגו
th תאית
tr טורקית
uk אוקראינית
vi וייטנאמית
zh_CN סינית (סין)
zh_TW סינית (טאייוואן)

חיפוש הודעות

לא צריך להגדיר כל מחרוזת לכל לוקאל נתמך. כל עוד בקובץ 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".

ארבעה קבצים: manifest.json ושלושה קובצי messages.json (לשפות es,‏ en ו-en_GB). הקבצים es ו-en מציגים רשומות של הודעות בשם "extName" ו-"colores". בקובץ en_GB יש רק רשומה אחת (של "colores").

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

כדי לבדוק את התרגומים, כדאי להגדיר את הלוקאל של הדפדפן. בקטע הזה מוסבר איך להגדיר את הלוקאל ב-Windows, ב-macOS, ב-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. אחרי שמוסיפים את השפה, לוחצים על סמל האפשרויות הנוספות (3 נקודות) More actions ליד השפה ובוחרים באפשרות Display ChromeOS in this language.
  5. לוחצים על הכפתור הפעלה מחדש שמופיע לצד השפה שהוגדרה כדי להפעיל מחדש את ChromeOS.

דוגמאות

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

getMessage()

הקוד הבא מקבל הודעה מותאמת לשוק המקומי מהדפדפן ומציג אותה כמחרוזת. היא מחליפה שני פלייסהולדרים בהודעה במחרוזות "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."
    }
  }
}

מידע נוסף על פלייסהולדרים זמין בדף הודעות ספציפיות ללוקאל. למידע נוסף על קריאה ל-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.

סוגים

LanguageCode

‫Chrome 47 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

קוד שפה לפי תקן ISO, כמו en או fr. הרשימה המלאה של השפות שנתמכות בשיטה הזו מופיעה ב-kLanguageInfoTable. אם השפה לא ידועה, יוחזר הערך und, כלומר [אחוז] מהטקסט לא ידוע ל-CLD

סוג

מחרוזת

Methods

detectLanguage()

‫Chrome 47 ואילך ‫browser.* ‎ מגרסה 148 של Chrome 
browser.i18n.detectLanguage(
  text: string,
): Promise<object>

מזהה את השפה של הטקסט שסופק באמצעות CLD.

פרמטרים

  • text

    מחרוזת

    מחרוזת קלט של המשתמש לתרגום.

החזרות

  • Promise<object>

    ‫Chrome 99 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

getAcceptLanguages()

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

הפונקציה מקבלת את השפות המקובלות בדפדפן. הוא שונה מהלוקאל שבו הדפדפן משתמש. כדי לקבל את הלוקאל, משתמשים ב-i18n.getUILanguage.

החזרות

  • Promise<LanguageCode[]>

    ‫Chrome 99 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

getMessage()

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

מקבל את המחרוזת המותאמת לשוק המקומי של ההודעה שצוינה. אם ההודעה חסרה, השיטה הזו מחזירה מחרוזת ריקה (''). אם הפורמט של הקריאה ל-getMessage() שגוי – לדוגמה, messageName הוא לא מחרוזת או שהמערך substitutions מכיל יותר מ-9 רכיבים – השיטה הזו מחזירה undefined.

פרמטרים

  • messageName

    מחרוזת

    שם ההודעה, כפי שצוין בקובץ messages.json.

  • החלפות

    any optional

    עד 9 מחרוזות להחלפה, אם ההודעה דורשת זאת.

  • אפשרויות

    object optional

    ‫Chrome 79 ואילך ‫browser.* ‎ מגרסה 148 של Chrome
    • escapeLt

      בוליאני אופציונלי

      התו < בתרגום ל&lt;. ההגדרה הזו חלה רק על ההודעה עצמה, ולא על הפלייסהולדרים. מפתחים יכולים להשתמש באפשרות הזו אם התרגום משמש בהקשר של HTML. תבניות Closure שמשתמשים בהן עם Closure Compiler יוצרות את זה באופן אוטומטי.

החזרות

  • מחרוזת

    ההודעה מותאמת לשפה הנוכחית.

getUILanguage()

browser.i18n.getUILanguage(): string

השפה של ממשק המשתמש בדפדפן. הפונקציה הזו שונה מהפונקציה i18n.getAcceptLanguages שמחזירה את השפות המועדפות על המשתמש.

החזרות

  • מחרוזת

    קוד השפה של ממשק המשתמש בדפדפן, למשל en-US או fr-FR.