chrome.i18n

תיאור

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

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

כדי לבדוק תרגומים, כדאי להגדיר את הלוקאל של הדפדפן. בקטע הזה מוסבר איך להגדיר את הלוקאל ב-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

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

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

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

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

Mac OS

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

מידע נוסף על 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.

סוגים

LanguageCode

‫Chrome 47 ואילך

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

סוג

מחרוזת

Methods

detectLanguage()

‫Chrome 47 ואילך

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

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

פרמטרים

• text

  מחרוזת

  מחרוזת קלט של משתמש שצריך לתרגם.

החזרות

• Promise<object>

  ‫Chrome 99 ואילך

getAcceptLanguages()

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

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

החזרות

• Promise<LanguageCode[]>

  ‫Chrome 99 ואילך

getMessage()

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

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

פרמטרים

• messageName

  מחרוזת

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

• החלפות

  כל אופציונלי

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

• options

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

  ‫Chrome 79 ואילך
  • escapeLt

    ‫boolean אופציונלי

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

החזרות

• מחרוזת

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

getUILanguage()

chrome.i18n.getUILanguage(): string

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

החזרות

• מחרוזת

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