chrome.i18n

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

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

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

איך תומכים בכמה שפות

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

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

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

‪<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="In the manifest.json file, " and="" been="" changed="" chrome.i18n.getmessage("extname").="" defines="" en="" file="" file,="" has="" hello="" in="" item="" javascript="" messages.json="" named="" new="" src="/static/images/i18n-after-1.gif" the="" to="" value="" world"="" />

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

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

  {
    "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 תומכת בהם.

חיפוש הודעות

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

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

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

Linux

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

LANGUAGE=es ./chrome

ChromeOS

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

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

מידע נוסף על placeholder זמין בדף הודעות ספציפיות ללוקאל. פרטים על קריאה ל-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,
  callback?: function,
): Promise<object>

chrome.i18n.getAcceptLanguages(
  callback?: function,
): Promise<LanguageCode[]>

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

chrome.i18n.getUILanguage(): string