شرح
از زیرساخت chrome.i18n برای پیادهسازی بینالمللیسازی در کل برنامه یا افزونهتان استفاده کنید.
مانیفست
اگر افزونهای دارای دایرکتوری /_locales باشد، مانیفست باید "default_locale" را تعریف کند.
مفاهیم و کاربرد
باید همه رشتههای قابلمشاهده برای کاربر را در فایلی با نام messages.json قرار دهید. هر بار که منطقه زبانی جدیدی اضافه میکنید، فایل پیامها را در دایرکتوریای بهنام /_locales/_localeCode_ اضافه میکنید که در آن localeCode کدی مانند en برای انگلیسی است.
در اینجا سلسلهمراتب فایل برای افزونه بینالمللیشدهای که از انگلیسی (en)، اسپانیایی (es)، و کرهای (ko) پشتیبانی میکند آورده شده است:

پشتیبانی از چند زبان
فرض کنید افزونهای با فایلهای نشاندادهشده در شکل زیر دارید:

برای بینالمللی کردن این افزونه، هر رشته قابلمشاهده برای کاربر را نامگذاری میکنید و آن را در فایل پیامها قرار میدهید. مانیفست افزونه، فایلهای CSS، و کد جاوا اسکریپت از نام هر رشته برای دریافت نسخه بومیسازیشده آن استفاده میکنند.
در اینجا ظاهر افزونه را پساز بینالمللی شدن میبینید (توجه داشته باشید که هنوز فقط رشتههای انگلیسی دارد):

چند نکته درباره بینالمللیسازی:
- میتوانید از هرکدام از منطقههای زبانی پشتیبانیشده استفاده کنید. اگر از منطقه زبانی پشتیبانینشدهای استفاده کنید، Google Chrome آن را نادیده میگیرد.
در فایلهای
manifest.jsonو CSS، به رشتهای با نام messagename به این صورت ارجاع دهید:__MSG_messagename__در کد جاوا اسکریپت افزونه یا برنامهتان، به رشتهای بهنام messagename به این صورت ارجاع دهید:
browser.i18n.getMessage("messagename")در هر تماس با
getMessage()، میتوانید حداکثر ۹ رشته برای گنجاندن در پیام ارائه دهید. برای جزئیات، نمونهها: getMessage را ببینید.برخیاز پیامها، مانند
@@bidi_dirو@@ui_locale، توسط سیستم بینالمللیسازی ارائه میشوند. برای مشاهده فهرست کامل نامهای پیام ازپیشتعریفشده، بخش پیامهای ازپیشتعریفشده را ببینید.در
messages.json، هر رشته قابلمشاهده برای کاربر دارای یک نام، یک مورد «پیام»، و یک مورد اختیاری «شرح» است. نام کلیدی است مانند «extName» یا «search_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 قرار دهید. شکل زیر
افزونه قبلی را با ترجمه اسپانیایی جدید نشان میدهد.

پیامهای ازپیش تعریفشده
سیستم بینالمللیسازی چند پیام ازپیشتعریفشده برای کمک به بومیسازی ارائه میدهد. این
شامل @@ui_locale است، بنابراین میتوانید زبان واسط کاربر فعلی را شناسایی کنید، و چند پیام @@bidi_... که
به شما امکان میدهد جهت نوشتار را شناسایی کنید. پیامهای دوم نامهای مشابهی با ثابتها در
میانای برنامهسازی کاربردی BIDI (دوجهته) ابزارکها دارند.
از پیام ویژه @@extension_id میتوان در فایلهای CSS و JavaScript استفاده کرد، چه افزونه یا برنامه بومیسازی شده باشد چه نشده باشد. این پیام در فایلهای مانیفست کار نمیکند.
جدول زیر هر پیام ازپیش تعریفشده را شرح میدهد.
| نام پیام | شرح |
|---|---|
@@extension_id | شناسه برنامه یا افزونه؛ ممکن است از این رشته برای ساختن نشانیهای وب برای منابع داخل افزونه استفاده کنید. حتی افزونههای بومیسازینشده میتوانند از این پیام استفاده کنند. توجه: نمیتوانید از این پیام در فایل مانیفست استفاده کنید. |
@@ui_locale | منطقه زبانی فعلی؛ ممکن است از این رشته برای ساختن نشانیهای وب مختص منطقه زبانی استفاده کنید. |
@@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 برای ساختن نشانی وب آورده شده است:
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 |
هندی |
hr |
کرواتی |
hu |
مجارستانی |
id |
اندونزیایی |
it |
ایتالیایی |
ja |
ژاپنی |
kn |
کنادا |
ko |
کرهای |
lt |
لیتوانیایی |
lv |
لتونیایی |
ml |
مالایالام |
mr |
ماراتی |
ms |
مالایی |
nl |
هلندی |
no |
نروژی |
pl |
لهستانی |
pt_BR |
پرتغالی (برزیل) |
pt_PT |
پرتغالی (پرتغال) |
ro |
رومانیایی |
ru |
روسی |
sk |
اسلوواکی |
sl |
Slovenian |
sr |
صربی |
sv |
سوئدی |
sw |
سواحیلی |
ta |
تامیلی |
te |
تلوگو |
th |
تایلندی |
tr |
ترکی |
uk |
اوکراینی |
vi |
ویتنامی |
zh_CN |
چینی (چین) |
zh_TW |
چینی (تایوان) |
جستجوی پیامها
لازم نیست هر رشته را برای هر منطقه زبانی پشتیبانیشده تعریف کنید. تا زمانی که فایل messages.json زبان پیشفرض برای هر رشته مقداری داشته باشد، افزونه یا برنامه شما بدون توجه به اینکه ترجمه چقدر پراکنده است، اجرا خواهد شد. در اینجا نحوه جستجوی سیستم افزونه برای یک پیام آورده شده است:
- فایل پیامها (درصورت وجود) را برای منطقه زبانی ترجیحی کاربر جستجو کنید. برای مثال، وقتی منطقه زبانی Google Chrome روی انگلیسی بریتانیایی (
en_GB) تنظیم شده باشد، سیستم ابتدا پیام را در/_locales/en_GB/messages.jsonجستجو میکند. اگر آن فایل وجود داشته باشد و پیام در آنجا باشد، سیستم دیگر جستجو نمیکند. - اگر منطقه زبانی ترجیحی کاربر دارای منطقه باشد (یعنی منطقه زبانی دارای زیرخط باشد: _)، منطقه زبانی را بدون آن منطقه جستجو کنید. برای مثال، اگر فایل پیامهای
en_GBوجود نداشته باشد یا حاوی پیام نباشد، سیستم در فایل پیامهایenجستجو میکند. اگر آن فایل وجود داشته باشد و پیام در آنجا باشد، سیستم دیگر جستجو نمیکند. - فایل پیامها را برای زبان پیشفرض جستجو کنید. برای مثال، اگر «default_locale» افزونه روی «es» تنظیم شده باشد و نه
/_locales/en_GB/messages.jsonو نه/_locales/en/messages.jsonحاوی پیام نباشد، افزونه از پیام/_locales/es/messages.jsonاستفاده میکند.
در شکل زیر، پیام با نام «colores» در هر سه منطقهای که افزونه پشتیبانی میکند وجود دارد، اما «extName» فقط در دو منطقه وجود دارد. هرجا که کاربر Google Chrome را در ایالات متحده اجرا میکند انگلیسی برچسب «Colors» را میبیند، کاربر انگلیسی بریتانیایی «Colours» را میبیند. هم کاربران انگلیسی امریکایی و هم کاربران انگلیسی بریتانیایی نام افزونه «Hello World» را میبینند. چون زبان پیشفرض اسپانیایی است، کاربرانی که Google Chrome را به زبانی غیراز انگلیسی اجرا میکنند، برچسب «Colores» و نام افزونه «Hola mundo» را میبینند.

تنظیم منطقه زبانی مرورگر
برای آزمایش ترجمهها، شاید بخواهید زبان مرورگرتان را تنظیم کنید. این بخش به شما میگوید چگونه منطقه زبانی را در Windows، macOS، Linux، و ChromeOS تنظیم کنید.
Windows
میتوانید منطقه زبانی را بااستفاده از میانبر مختص منطقه زبانی یا واسط کاربر Google Chrome تغییر دهید. وقتی آن را راهاندازی کردید، روش میانبر سریعتر است و به شما امکان میدهد از چند زبان بهطور همزمان استفاده کنید.
استفاده از میانبر مختص منطقه زبانی
برای ایجاد و استفاده از میانبری که Google Chrome را با منطقه زبانی خاصی راهاندازی میکند:
- از میانبر Google Chrome که ازقبل در میز کارتان وجود دارد نسخهای تهیه کنید.
- نام میانبر جدید را تغییر دهید تا با منطقه زبانی جدید مطابقت داشته باشد.
ویژگیهای میانبر را تغییر دهید تا فیلد «هدف» پرچمهای
--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 آورده شده است:
- نماد برنامه > گزینهها
- برگه Under the Hood (زیر کاپوت) را انتخاب کنید
- به محتوای وب پیمایش کنید
- روی تغییر تنظیمات قلم و زبان کلیک کنید
- برگه زبانها را انتخاب کنید
- از منو کرکرهای برای تنظیم زبان Google Chrome استفاده کنید
- بازراهاندازی Chrome
سیستمعامل Mac
برای تغییر دادن منطقه زبانی در Mac، از اولویتهای سیستم استفاده میکنید.
- از منوِ Apple، System Preferences (تنظیمات سیستم) را انتخاب کنید
- در بخش شخصی، بینالمللی را انتخاب کنید
- انتخاب زبان و مکان
- بازراهاندازی Chrome
Linux
برای تغییر دادن زبان در Linux، ابتدا از Google Chrome خارج شوید. سپس، در یک خط، متغیر محیطی LANGUAGE را تنظیم کنید و Google Chrome را راهاندازی کنید. برای مثال:
LANGUAGE=es ./chrome
ChromeOS
برای تغییر دادن منطقه زبانی در ChromeOS:
- از سینی سیستم، تنظیمات را انتخاب کنید.
- در بخش زبانها و ورودی، منو کرکرهای زبان را انتخاب کنید.
- اگر زبان موردنظرتان در فهرست نیست، روی افزودن زبان کلیک کنید و آن را اضافه کنید.
- پساز افزودن، روی منوِ ۳نقطهای کنشهای بیشتر در کنار زبان موردنظر کلیک کنید و نمایش ChromeOS به این زبان را انتخاب کنید.
- روی دکمه بازراهاندازی که در کنار زبان تنظیمشده نشان داده میشود کلیک کنید تا ChromeOS بازراهاندازی شود.
مثالها
میتوانید نمونههای بینالمللیسازی را در دایرکتوری examples/api/i18n پیدا کنید. برای مشاهده نمونه کامل، به examples/extensions/news مراجعه کنید. برای نمونههای دیگر و راهنمایی در مشاهده کد منبع، نمونهها را ببینید.
getMessage()
کد زیر پیام بومیسازیشدهای را از مرورگر دریافت میکند و آن را بهصورت رشته نمایش میدهد. این کد دو جایبان را در پیام با رشتههای «رشته۱» و «رشته۲» جایگزین میکند.
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."
}
}
}
برای اطلاعات بیشتر درباره جایبانها، به صفحه پیامهای مختص منطقه مراجعه کنید. برای جزئیات درباره
فراخوانی getMessage()، به مرجع میانای برنامهسازی کاربردی مراجعه کنید.
getAcceptLanguages()
کد زیر زبانهای پذیرفتهشده را از مرورگر دریافت میکند و آنها را بهصورت رشتهای با جدا کردن هر زبان پذیرفتهشده با «،» نمایش میدهد.
function getAcceptLanguages() {
chrome.i18n.getAcceptLanguages(function(languageList) {
var languages = languageList.join(",");
document.getElementById("languageSpan").innerHTML = languages;
})
}
برای جزئیات مربوط به فراخوانی getAcceptLanguages()، به مرجع میانای برنامهسازی کاربردی مراجعه کنید.
detectLanguage()
کد زیر حداکثر ۳ زبان را از رشته ارائهشده شناسایی میکند و نتیجه را بهصورت رشتههایی که با خطوط جدید از هم جدا شدهاند نمایش میدهد.
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)، به مرجع میانای برنامهسازی کاربردی مراجعه کنید.
انواع
LanguageCode
کد زبان ISO مانند en یا fr. برای مشاهده فهرست کامل زبانهای پشتیبانیشده توسط این روش، به kLanguageInfoTable مراجعه کنید. برای زبان ناشناخته، und برگردانده میشود، یعنی [درصد] نوشتار برای CLD ناشناخته است
نوع
رشته
روشها
detectLanguage()
browser.i18n.detectLanguage(
text: string,
): Promise<object>
زبان نوشتار ارائهشده را بااستفاده از CLD تشخیص میدهد.
پارامترها
-
نوشتار
رشته
رشته ورودی کاربر برای ترجمه.
بازگشتیها
-
Promise<object>
Chrome نسخه ۹۹ و بالاتر browser.* از Chrome نسخه ۱۴۸
getAcceptLanguages()
browser.i18n.getAcceptLanguages(): Promise<LanguageCode[]>
زبانهای پذیرفتهشده مرورگر را دریافت میکند. این با منطقه زبانی مورداستفاده مرورگر متفاوت است؛ برای دریافت منطقه زبانی، از i18n.getUILanguage استفاده کنید.
بازگشتیها
-
Promise<LanguageCode[]>
Chrome نسخه ۹۹ و بالاتر browser.* از Chrome نسخه ۱۴۸
getMessage()
browser.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
): string
رشته بومیسازیشده را برای پیام مشخصشده دریافت میکند. اگر پیام وجود نداشته باشد، این روش رشتهای خالی ('') برمیگرداند. اگر قالب فراخوانی getMessage() اشتباه باشد — برای مثال، messageName رشته نباشد یا آرایه substitutions بیشاز ۹ عنصر داشته باشد — این روش undefined را برمیگرداند.
پارامترها
-
messageName
رشته
نام پیام، همانطور که در فایل
messages.jsonمشخص شده است. -
تعویضها
هر اختیاری
حداکثر ۹ رشته جایگزین، اگر پیام به آن نیاز داشته باشد.
-
گزینهها
شیء اختیاری
Chrome نسخه ۷۹ به بالا browser.* از Chrome نسخه ۱۴۸-
escapeLt
بولی اختیاری
Escape
<در ترجمه به<. این فقط برای خود پیام اعمال میشود، نه برای جایبانها. اگر ترجمه در بافت HTML استفاده شود، توسعهدهندگان ممکن است بخواهند از این استفاده کنند. «الگوهای Closure» که با Closure Compiler استفاده میشود این را بهطور خودکار تولید میکند.
-
بازگشتیها
-
رشته
پیام برای منطقه زبانی فعلی بومیسازی شده است.
getUILanguage()
browser.i18n.getUILanguage(): string
زبان واسط کاربر مرورگر را دریافت میکند. این با i18n.getAcceptLanguages که زبانهای ترجیحی کاربر را برمیگرداند متفاوت است.
بازگشتیها
-
رشته
کد زبان واسط کاربر مرورگر، مانند en-US یا fr-FR.