תיאור
אפשר להשתמש בתשתית 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 | מזהה התוסף או האפליקציה. אפשר להשתמש במחרוזת הזו כדי ליצור כתובות 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 | ערבית |
בבוקר | אמהרית |
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
של הלוקאל שמוגדר כברירת המחדל יש ערך לכל מחרוזת, התוסף או האפליקציה יפעלו בלי קשר להיקף התרגום. כך מערכת התוספים תחפש הודעה:
- מחפשים בקובץ ההודעות (אם יש) את הלוקאל המועדף של המשתמש. לדוגמה, כשהלוקאל של Google Chrome מוגדר לאנגלית בריטית (
en_GB
), המערכת קודם מחפשת את ההודעה ב-/_locates/en_GB/messages.json
. אם הקובץ קיים וההודעה מופיעה, המערכת לא מחפשת עוד. - אם המיקום המועדף על המשתמש כולל אזור (כלומר, במקום מופיע קו תחתון: _), מחפשים את הלוקאל בלי האזור. לדוגמה, אם קובץ ההודעות
en_GB
לא קיים או שהוא לא מכיל את ההודעה, המערכת מחפשת את קובץ ההודעותen
. אם הקובץ קיים וההודעה מופיעה, המערכת לא מחפשת עוד. - מחפשים בקובץ ההודעות את לוקאל ברירת המחדל. לדוגמה, אם הערך 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 עם מקום מסוים:
- יוצרים עותק של קיצור הדרך ל-Google Chrome שכבר נמצא בשולחן העבודה.
- משנים את השם של קיצור הדרך החדש בהתאם ללוקאל החדש.
משנים את המאפיינים של קיצור הדרך כך שבשדה Target (יעד) יופיעו הדגלים
--lang
ו---user-data-dir
. היעד אמור להיראות כך:path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
מפעילים את 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:
- סמל האפליקציה > אפשרויות
- בוחרים בכרטיסייה מאחורי הקלעים
- גוללים למטה אל Web Content (תוכן מהאינטרנט).
- לוחצים על שינוי הגדרות הגופן והשפה
- בוחרים בכרטיסייה שפות.
- בתפריט הנפתח מגדירים את השפה ב-Google Chrome
- הפעלה מחדש של Chrome
Mac OS X
כדי לשנות את הלוקאל ב-Mac, צריך להשתמש בהעדפות המערכת.
- בתפריט Apple, בוחרים באפשרות System Preferences (העדפות המערכת)
- בקטע אישי בוחרים באפשרות International.
- בחירת השפה והמיקום
- הפעלה מחדש של Chrome
Linux
כדי לשנות את המקום ב-Linux, קודם צריך לצאת מ-Google Chrome. לאחר מכן, הכול בשורה אחת, מגדירים את משתנה הסביבה LANGUAGE ומפעילים את Google Chrome. למשל:
LANGUAGE=es ./chrome
ChromeOS
כדי לשנות את הלוקאל ב-ChromeOS:
- במגש המערכת, בוחרים באפשרות הגדרות.
- בקטע שפות וקלט, לוחצים על התפריט הנפתח שפה.
- אם השפה שלכם לא מופיעה ברשימה, לוחצים על הוספת שפות ומוסיפים אותה.
- אחרי ההוספה, לוחצים על סמל התפריט (3 נקודות) More actions (פעולות נוספות) שלצד השפה ובוחרים באפשרות הצגת ChromeOS בשפה הזו.
- כדי להפעיל מחדש את 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
קוד שפה לפי תקן ISO, כמו en
או fr
. לרשימה מלאה של השפות שנתמכות בשיטה הזו: kLanguageInfoTable. עבור שפה לא ידועה, מוחזר und
, כלומר [percentage] מהטקסט לא ידוע ל-CLD
סוג
string
שיטות
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
זיהוי השפה של הטקסט שסופק באמצעות CLD.
פרמטרים
-
טקסט
string
מחרוזת קלט של משתמשים לתרגום.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(result: object) => void
-
תוצאה אחת
אובייקט
אובייקט LanguageDetectionתוצאה שמכיל את המהימנות של langugae ומערך של DetectedLanguage
-
isReliable
boolean
אמינות השפה שזוהתה על ידי CLD
-
שפות
אובייקט[]
מערך של foundLanguage
-
language
string
-
אחוזים
number
אחוז השפה שזוהתה
-
-
-
החזרות
-
Promise<object>
Chrome מגרסה 99 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
מקבל את השפות המקובלות של הדפדפן. הערך הזה שונה מהלוקאל שבו הדפדפן משתמש. כדי לקבל את הלוקאל, צריך להשתמש ב-i18n.getUILanguage
.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(languages: string[]) => void
-
שפות
String[]
מערך של קוד שפה
-
החזרות
-
Promise<LanguageCode[]>
Chrome מגרסה 99 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
getMessage()
chrome.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
)
הפונקציה מקבלת את המחרוזת שהותאמה עבור ההודעה שצוינה. אם ההודעה חסרה, השיטה הזו מחזירה מחרוזת ריקה ('). אם הפורמט של הקריאה ל-getMessage()
שגוי – לדוגמה, messageName הוא לא מחרוזת או שהמערך substitutions כולל יותר מ-9 רכיבים – השיטה הזו מחזירה undefined
.
פרמטרים
-
messageName
string
שם ההודעה, כפי שמצוין בקובץ
messages.json
. -
החלפות
כל אופציונלי
עד 9 מחרוזות החלפה, אם נדרשות מחרוזות החלפה.
-
אפשרויות
אובייקט אופציונלי
Chrome מגרסה 79 ואילך-
escapeLt
ערך בוליאני אופציונלי
תו בריחה של
<
בתרגום ל<
. ההנחיה מתייחסת רק להודעה עצמה, ולא ל-placeholders. כדאי למפתחים להשתמש באפשרות הזו אם התרגום משמש בהקשר HTML. תבניות סגירה שבהן נעשה שימוש בשילוב עם מהדר החסימות יוצרות זאת באופן אוטומטי.
-
החזרות
-
string
ההודעה הותאמה ללוקאל הנוכחי.
getUILanguage()
chrome.i18n.getUILanguage()
מקבל את שפת ממשק המשתמש של הדפדפן. השיטה הזו שונה מ-i18n.getAcceptLanguages
, שבה מוחזרות שפות המשתמש המועדפות.
החזרות
-
string
קוד השפה של ממשק המשתמש של הדפדפן, למשל en-US או fr-FR.