chrome.i18n

תיאור

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

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

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

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

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

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

קובץ המניפסט.json וקובץ עם JavaScript. בקובץ ה- .json יש

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

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

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales=&quot;&quot; a=&quot;&quot; Alt="בקובץ המניפסט.json, " and=&quot;&quot; כבר="" changed=&quot;&quot; chrome.i18n.getmessage("extname").="" defines=&quot;&quot; en=&quot;&quot; file=&quot;&quot; file,=&quot;&quot; has=&quot;&quot; hello=&quot;&quot; in=&quot;&quot; item=&quot;&quot; javascript=&quot;&quot; messages.json=&quot;&quot; named=&quot;&quot; new="" src=&quot;/static/images/i18n-after-1.gif&quot; the=&quot;&quot; to=&quot;&quot; value="" עולם"="" />

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

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

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

    __MSG_messagename__

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

    chrome.i18n.getMessage("messagename")

  • בכל קריאה אל getMessage(), אפשר לציין עד 9 מחרוזות שייכללו בהודעה. צפייה דוגמאות: getMessage לפרטים.

  • חלק מההודעות, כמו @@bidi_dir ו-@@ui_locale, מסופקות על ידי ההתאמה לשוק הבינלאומי המערכת. רשימה מלאה של שמות ההודעות המוגדרים מראש מופיעה בקטע הודעות שהוגדרו מראש.

  • ב-messages.json, לכל מחרוזת הגלויה למשתמש יש שם – "message" ואופציונלי, &quot;description&quot; שימושי. השם הוא מפתח כמו extName או 'search_string' שמזהה את String. השדה 'הודעה' מציין את ערך המחרוזת בלוקאל הזה. השדה האופציונלי 'תיאור' מספקת עזרה למתרגמים, שייתכן שאינם יכולים לראות את אופן השימוש במחרוזת לתוסף. לדוגמה:

    {
  "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'; אחרת יהיה "נכון".
@@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 בארה"ב אנגלית רואה את התווית 'צבעים', ומשתמש באנגלית בריטית רואה את התווית 'צבעים'. גם אנגלית (ארה"ב) וגם משתמשים באנגלית בריטית רואים את שם התוסף "Hello World". מכיוון ששפת ברירת המחדל היא ספרדית, שמשתמשים ב-Google Chrome בשפה שאינה אנגלית יראו את התווית 'צבעים' ואת התוסף בשם "Hola mundo".

ארבעה קבצים: flash.json ושלושה קובצי messages.json (ל-es, ל-en ול-en_GB). בקובצי es ו-en מוצגים רשומות של הודעות בעלות שם

איך מגדירים את הלוקאל של הדפדפן

כדי לבדוק תרגומים, מומלץ להגדיר את הלוקאל של הדפדפן. בקטע הזה מוסבר איך להגדיר הלוקאל ב-Windows, ב-Mac OS X, ב-Linux וב-ChromeOS.

Windows

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

שימוש בקיצור דרך ספציפי ללוקאל

כדי ליצור קיצור דרך ולהשתמש בו שמפעיל את Google Chrome עם מקום מסוים:

  1. יוצרים עותק של קיצור הדרך ל-Google Chrome שכבר נמצא בשולחן העבודה.
  2. משנים את השם של קיצור הדרך החדש בהתאם ללוקאל החדש.

  3. משנים את המאפיינים של קיצור הדרך כך שבשדה היעד יפורטו --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. בוחרים בכרטיסייה מאחורי הקלעים
  3. גוללים למטה אל Web Content (תוכן מהאינטרנט).
  4. לוחצים על שינוי הגדרות הגופן והשפה
  5. בוחרים בכרטיסייה שפות.
  6. בתפריט הנפתח מגדירים את השפה ב-Google Chrome
  7. הפעלה מחדש של Chrome

Mac OS X

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

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

דוגמה: getAcceptLanguage

הקוד הבא מקבל שפות קבלה מהדפדפן ומציג אותן כמחרוזת שמפרידות כל שפה שמתקבלת באמצעות התו ,

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

פרטים על קריאה ל-getAcceptLanguages() מופיעים במאמרי העזרה של ה-API.

דוגמה: IdentityLanguage

הקוד הבא מזהה עד 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()

הבטחה Chrome מגרסה 47 ואילך 
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

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

פרמטרים

  • טקסט

    מחרוזת

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

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

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

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

    (result: object) => void

    • תוצאה

      אובייקט

      אובייקט LanguageDetectionתוצאה שמכיל את המהימנות של langugae ומערך של DetectedLanguage

      • isReliable

        בוליאני

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

      • שפות

        object[]

        מערך של foundLanguage

        • language

          מחרוזת

        • אחוזים

          number

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

החזרות

  • Promise&lt;object&gt;

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

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

getAcceptLanguages()

הבטחה 
chrome.i18n.getAcceptLanguages(
  callback?: function,
)

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

פרמטרים

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

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

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

    (languages: string[]) => void

    • שפות

      String[]

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

החזרות

  • Promise&lt;LanguageCode[]&gt;

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

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

getMessage()

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

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

פרמטרים

  • messageName

    מחרוזת

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

  • החלפות

    כל אופציונלי

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

  • אפשרויות

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

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

      ערך בוליאני אופציונלי

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

החזרות

  • מחרוזת

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

getUILanguage()

chrome.i18n.getUILanguage()

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

החזרות

  • מחרוזת

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