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=&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/docs/extensions/mv2/reference/i18n/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, לתרגם אותו ולהוסיף את העותק לספרייה חדשה בקטע /_locates. לדוגמה, כדי לתמוך לספרדית, הועבר עותק מתורגם של messages.json בקטע /_locates/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. אם הלוקאל שלך לא מופיע ברשימה, צריך לבחור את החלופה הקרובה ביותר. לדוגמה, אם לוקאל ברירת המחדל של התוסף הוא "de_CH", צריך לבחור באפשרות "de" בחנות האינטרנט של Chrome.

חיפוש הודעות

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

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

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

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,
)

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

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

chrome.i18n.getUILanguage()