chrome.i18n

refresh date: 2026-09-25 robots: noindex

תיאור

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

אתם צריכים להכניס את כל המחרוזות שגלויות למשתמשים לקובץ בשם 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"="" />

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

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

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

חיפוש הודעות

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

הערה: לא חובה לציין את --user-data-dir, אבל זה שימושי. אם יש ספריית נתונים אחת לכל לוקאל, אפשר להפעיל את הדפדפן בכמה שפות בו-זמנית. החיסרון הוא שהנתונים של הלוקאלים לא משותפים, ולכן צריך להתקין את התוסף כמה פעמים – פעם אחת לכל לוקאל. זה יכול להיות מאתגר אם אתם לא דוברים את השפה. מידע נוסף זמין במאמר יצירה ושימוש בפרופילים.

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

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

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

Mac OS X

כדי לשנות את הלוקאל ב-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 ואילך

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

סוג

מחרוזת

Methods

detectLanguage()

Promise Chrome 47+‎

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
): Promise<object>

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

פרמטרים

• text

  מחרוזת

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

• callback

  function optional

  הפרמטר callback נראה כך:

  (result: object) => void

  • תוצאה

    אובייקט

    אובייקט LanguageDetectionResult שמכיל את מהימנות השפה שזוהתה ומערך של DetectedLanguage

    • isReliable

      בוליאני

      אמינות השפה שזוהתה על ידי CLD

    • שפות

      object[]‎

      מערך של detectedLanguage

      • language

        מחרוזת

      • אחוזים

        number

        אחוז השפה שזוהתה

החזרות

• Promise<object>

  ‫Chrome מגרסה 99 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getAcceptLanguages()

Promise

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

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

פרמטרים

• callback

  function optional

  הפרמטר callback נראה כך:

  (languages: string[]) => void

  • שפות

    string[]‎

    מערך של LanguageCode

החזרות

• Promise<LanguageCode[]>

  ‫Chrome מגרסה 99 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getMessage()

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

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

פרמטרים

• messageName

  מחרוזת

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

• החלפות

  any optional

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

• אפשרויות

  object optional

  ‫Chrome מגרסה 79 ואילך
  • escapeLt

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

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

החזרות

• מחרוזת

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

getUILanguage()

chrome.i18n.getUILanguage(): string

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

החזרות

• מחרוזת

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