chrome.i18n

תיאור

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

מניפסט

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

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

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

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

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

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

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

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

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" Alt="In the המניפסט.json file, " and="" were="" changed="" chrome.i18n.getmessage("extname")." מגדירs="" en="" file="" file="" מגדירs="" en="" file="" file

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

• אפשר להשתמש בכל אחד מהלוקאלים הנתמכים. אם משתמשים בלוקאל שלא נתמך, 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, מתרגמים אותו ומוסיפים את העותק לספרייה חדשה תחת /_locates. לדוגמה, כדי לתמוך בספרדית, פשוט מוסיפים עותק מתורגם של messages.json תחת /_locates/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', אז הוא 'משמאל'; אחרת, הוא 'ימין'.
@@bidi_end_edge	אם @@bidi_dir הוא 'ltr', אז זה 'ימין'; אחרת, הוא 'שמאל'.

דוגמה לשימוש ב-@@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	הינדית
שעה	קרואטית
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), המערכת תחפש קודם את ההודעה ב-/_locates/en_GB/messages.json. אם הקובץ קיים וההודעה מופיעה בו, המערכת לא מחפשת עוד.
2. אם בלוקאל המועדף על המשתמש יש אזור (כלומר, בלוקאל יש קו תחתון: _), מחפשים את הלוקאל בלי האזור הזה. לדוגמה, אם קובץ ההודעות en_GB לא קיים או לא מכיל את ההודעה, המערכת תבדוק את הקובץ של ההודעות en. אם הקובץ קיים וההודעה מופיעה בו, המערכת לא מחפשת עוד.
3. מחפשים בקובץ ההודעות את לוקאל ברירת המחדל. לדוגמה, אם הערך של "default_locale" של התוסף הוא es, ולא /_locates/en_GB/messages.json ולא /_locates/en/messages.json מכילים את ההודעה, התוסף ישתמש בהודעה מ-/_locates/es/messages.json.

באיור הבא, ההודעה בשם 'colores' מופיעה בכל שלושת הלוקאלים שהתוסף תומך בהם, אבל המילה extName מופיעה רק בשני אזורים. בכל מקום שבו משתמש שמפעיל את Google Chrome באנגלית אמריקאית רואה את התווית "Colors", משתמש באנגלית בריטית רואה את "Colours". משתמשים באנגלית אמריקאית ואנגלית בריטית רואים את שם התוסף 'שלום עולם'. מכיוון ששפת ברירת המחדל היא ספרדית, משתמשים המריצים את Google Chrome בשפה שאינה אנגלית רואים את התווית 'צבעים' ואת שם התוסף '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. בחר בכרטיסייה מאחורי הקלעים
3. גוללים למטה אל תוכן אינטרנט.
4. לוחצים על שינוי הגדרות הגופן והשפה
5. בוחרים בכרטיסייה שפות.
6. משתמשים בתפריט הנפתח כדי להגדיר את השפה של Google Chrome
7. מפעילים מחדש את Chrome

Mac OS X

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

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

סוג

מחרוזת

שיטות

detectLanguage()

Promise Chrome 47 ואילך

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

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

פרמטרים

• טקסט

  מחרוזת

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

• קריאה חוזרת (callback)

  פונקציה אופציונלי

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

  (result: object)=>void

  • תוצאה אחת

    אובייקט

    אובייקט LanguageDetectionResults שמחזיק באמינות השפה שזוהו ובמערך DetectedLanguage

    • isReliable

      boolean

      זוהתה אמינות השפה באמצעות CLD

    • שפות

      אובייקט[]

      מערך שלDetectLanguage

      • language

        מחרוזת

      • אחוזים

        מספר

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

החזרות

• Promise<object>

  Chrome 99 ומעלה

  יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

getAcceptLanguages()

הבטחה

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

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

פרמטרים

• קריאה חוזרת (callback)

  פונקציה אופציונלי

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

  (languages: string[])=>void

  • שפות

    מחרוזת[]

    מערך של קוד שפה

החזרות

• Promise<LanguageCode[]>

  Chrome 99 ומעלה

  יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

getMessage()

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

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

פרמטרים

• messageName

  מחרוזת

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

• החלפות

  כל אופציונלי

  עד 9 מחרוזות החלפה, אם יש צורך במחרוזות כלשהן.

• אפשרויות

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

  Chrome 79 ומעלה
  • escapeLt

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

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

החזרות

• מחרוזת

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

getUILanguage()

chrome.i18n.getUILanguage()

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

החזרות

• מחרוזת

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