chrome.i18n

תיאור

מניפסט

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

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

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

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

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

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

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

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

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locters="" a="" Alt="בקובץ המניפסט.json, " and="" be="" changed="" chrome.i18n.getmessage("extname" file"). ""defined has="" en="" fileafter" file

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

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

הודעות שהוגדרו מראש

מערכת הבינלאומיות מספקת כמה הודעות מוגדרות מראש כדי לעזור לכם לבצע לוקליזציה. למשל, @@ui_locale, כך שתוכלו לזהות את הלוקאל הנוכחי של ממשק המשתמש, וכמה הודעות @@bidi_... שמאפשרות לזהות את כיוון הטקסט. להודעות האחרונות יש שמות דומים לאלה שקיימים בקבועים בגאדג'טים BIDI (דו-כיווני) API.

ניתן להשתמש בהודעה המיוחדת @@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 באנגלית ארה"ב רואה את התווית 'Colors', משתמש באנגלית בריטית רואה את התווית 'Colours'. משתמשים באנגלית ארה"ב וגם באנגלית בריטית רואים את שם התוסף "Hello World". מכיוון ששפת ברירת המחדל היא ספרדית, משתמשים שמפעילים את 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

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

כך משנים את המיקום באמצעות ממשק המשתמש ב-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 נקודות) More actions (פעולות נוספות) שלצד השפה ובוחרים באפשרות הצגת 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()