chrome.i18n

توضیحات

از زیرساخت chrome.i18n برای پیاده‌سازی بین‌المللی‌سازی در کل برنامه یا افزونه خود استفاده کنید.

مانیفست

اگر یک افزونه دارای دایرکتوری /_locales ‎ باشد، مانیفست باید "default_locale" را تعریف کند.

مفاهیم و کاربردها

شما باید تمام رشته‌های قابل مشاهده توسط کاربر را در فایلی به نام messages.json قرار دهید. هر بار که یک زبان جدید اضافه می‌کنید، یک فایل پیام در دایرکتوری به نام /_locales/_localeCode_ اضافه می‌کنید، که در آن localeCode کدی مانند en برای زبان انگلیسی است.

در اینجا سلسله مراتب فایل برای یک افزونه بین‌المللی که از زبان‌های انگلیسی ( en )، اسپانیایی ( es ) و کره‌ای ( ko ) پشتیبانی می‌کند، آمده است:

در دایرکتوری افزونه: manifest.json، *.html، *.js، دایرکتوری /_locales. در دایرکتوری /_locales: دایرکتوری‌های en، es و ko که هر کدام دارای یک فایل messages.json هستند.

پشتیبانی از چندین زبان

فرض کنید شما یک پسوند با فایل‌های نشان داده شده در شکل زیر دارید:

یک فایل manifest.json و یک فایل حاوی جاوا اسکریپت. فایل .json دارای عبارت 'Hello World' است. فایل جاوا اسکریپت دارای عنوان 'Hello World' است.

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

این شکلی است که افزونه پس از بین‌المللی شدن به خود می‌گیرد (توجه داشته باشید که هنوز فقط رشته‌های انگلیسی دارد):

در فایل manifest.json، عبارت 'Hello World' به '__MSG_extName__' تغییر یافته است و یک آیتم جدید default_locale' با مقدار 'en' ایجاد شده است. در فایل جاوا اسکریپت، عبارت 'Hello World' به chrome.i18n.getMessage('extName') تغییر یافته است. یک فایل جدید با نام /_locales/en/messages.json 'extName' را تعریف می‌کند.

چند نکته در مورد بین‌المللی‌سازی:

  • شما می‌توانید از هر یک از زبان‌های پشتیبانی‌شده استفاده کنید. اگر از زبان پشتیبانی‌نشده‌ای استفاده کنید، گوگل کروم آن را نادیده می‌گیرد.

  • در فایل‌های manifest.json و CSS، به رشته‌ای با نام messagename به این صورت اشاره کنید:

    __MSG_messagename__

  • در کد جاوا اسکریپت افزونه یا برنامه خود، به رشته‌ای با نام 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 را کپی می‌کنید، آن را ترجمه می‌کنید و نسخه را در یک دایرکتوری جدید در /_locales قرار می‌دهید. به عنوان مثال، برای پشتیبانی از زبان اسپانیایی، کافیست یک کپی ترجمه شده از messages.json را در /_locales/es قرار دهید. شکل زیر افزونه قبلی را با ترجمه جدید اسپانیایی نشان می‌دهد.

این شکل مشابه شکل قبلی است، اما با یک فایل جدید در /_locales/es/messages.json که شامل ترجمه اسپانیایی پیام‌ها است.

پیام‌های از پیش تعریف‌شده

سیستم بین‌المللی‌سازی چند پیام از پیش تعریف‌شده برای کمک به بومی‌سازی ارائه می‌دهد. این پیام‌ها شامل @@ui_locale هستند که به شما امکان می‌دهد زبان فعلی رابط کاربری را تشخیص دهید و چند پیام @@bidi_... که به شما امکان می‌دهند جهت متن را تشخیص دهید. پیام‌های اخیر نام‌های مشابهی با ثابت‌های موجود در API دو جهته BIDI گجت‌ها دارند.

پیام ویژه @@extension_id می‌تواند در فایل‌های CSS و جاوا اسکریپت استفاده شود، چه افزونه یا برنامه بومی‌سازی شده باشد چه نباشد. این پیام در فایل‌های مانیفست کار نمی‌کند.

جدول زیر هر پیام از پیش تعریف شده را شرح می‌دهد.

نام پیام توضیحات
@@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 ).

شما می‌توانید افزونه خود را به هر زبانی که توسط فروشگاه وب کروم پشتیبانی می‌شود، بومی‌سازی کنید. اگر زبان شما در اینجا فهرست نشده است، نزدیکترین جایگزین را انتخاب کنید. برای مثال، اگر زبان پیش‌فرض افزونه شما "de_CH" است، در فروشگاه وب کروم "de" را انتخاب کنید.

کد محلی زبان (منطقه)
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 اسلوونیایی
sr صربی
sv سوئدی
sw سواحیلی
ta تامیل
te تلوگو
th تایلندی
tr ترکی
uk اوکراینی
vi ویتنامی
zh_CN چینی (چین)
zh_TW چینی (تایوان)

جستجوی پیام‌ها

لازم نیست هر رشته را برای هر زبان پشتیبانی‌شده تعریف کنید. تا زمانی که فایل messages.json زبان پیش‌فرض برای هر رشته مقداری داشته باشد، افزونه یا برنامه شما صرف نظر از میزان پراکندگی ترجمه اجرا خواهد شد. در اینجا نحوه جستجوی پیام توسط سیستم افزونه آمده است:

  1. در فایل پیام‌ها (در صورت وجود) زبان مورد نظر کاربر را جستجو کنید. برای مثال، وقتی زبان گوگل کروم روی انگلیسی بریتانیایی ( 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" فقط در دو زبان وجود دارد. هر جا که کاربری که گوگل کروم را با زبان انگلیسی آمریکایی اجرا می‌کند، برچسب "Colors" را می‌بیند، کاربری که انگلیسی بریتانیایی دارد، "Colours" را می‌بیند. هم کاربران انگلیسی آمریکایی و هم کاربران انگلیسی بریتانیایی، نام افزونه "Hello World" را می‌بینند. از آنجا که زبان پیش‌فرض اسپانیایی است، کاربرانی که گوگل کروم را با هر زبان غیر انگلیسی اجرا می‌کنند، برچسب "Colores" و نام افزونه "Hola mundo" را می‌بینند.

چهار فایل: manifest.json و سه فایل messages.json (برای es، en و en_GB). فایل‌های es و en ورودی‌هایی برای پیام‌هایی با نام 'extName' و 'colores' را نشان می‌دهند؛ فایل en_GB فقط یک ورودی دارد (برای 'colores').

زبان مرورگر خود را تنظیم کنید

برای آزمایش ترجمه‌ها، ممکن است بخواهید زبان مرورگر خود را تنظیم کنید. این بخش به شما می‌گوید که چگونه زبان را در ویندوز ، macOS ، لینوکس و ChromeOS تنظیم کنید.

ویندوز

شما می‌توانید زبان را با استفاده از یک میانبر مخصوص زبان یا رابط کاربری گوگل کروم تغییر دهید. پس از تنظیم، رویکرد میانبر سریع‌تر است و به شما امکان می‌دهد از چندین زبان به طور همزمان استفاده کنید.

از یک میانبر مخصوص هر زبان استفاده کنید

برای ایجاد و استفاده از میانبری که گوگل کروم را با یک زبان خاص اجرا می‌کند:

  1. یک کپی از میانبر گوگل کروم که از قبل روی دسکتاپ شما قرار دارد، تهیه کنید.
  2. نام میانبر جدید را طوری تغییر دهید که با زبان جدید مطابقت داشته باشد.

  3. ویژگی‌های میانبر را طوری تغییر دهید که فیلد Target، پرچم‌های --lang و --user-data-dir را مشخص کند. target باید چیزی شبیه به این باشد:

    path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir

  4. با دوبار کلیک کردن روی میانبر، گوگل کروم را اجرا کنید.

برای مثال، برای ایجاد میانبری که گوگل کروم را به زبان اسپانیایی ( 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
از رابط کاربری استفاده کنید

در اینجا نحوه تغییر زبان با استفاده از رابط کاربری در گوگل کروم برای ویندوز آورده شده است:

  1. آیکون برنامه > گزینه‌ها
  2. برگه «زیر کاپوت» را انتخاب کنید
  3. به محتوای وب بروید
  4. روی تغییر تنظیمات فونت و زبان کلیک کنید
  5. برگه زبان‌ها را انتخاب کنید
  6. برای تنظیم زبان گوگل کروم از منوی کشویی استفاده کنید
  7. کروم را دوباره راه‌اندازی کنید

سیستم عامل مک

برای تغییر زبان در مک، از تنظیمات سیستم استفاده می‌کنید.

  1. از منوی اپل، گزینه System Preferences را انتخاب کنید.
  2. در بخش شخصی ، بین‌المللی را انتخاب کنید
  3. زبان و مکان خود را انتخاب کنید
  4. کروم را دوباره راه‌اندازی کنید

لینوکس

برای تغییر زبان در لینوکس، ابتدا از گوگل کروم خارج شوید. سپس، در یک خط، متغیر محیطی LANGUAGE را تنظیم کرده و گوگل کروم را اجرا کنید. برای مثال: 

LANGUAGE=es ./chrome

کروم او اس

برای تغییر زبان در ChromeOS:

  1. از سینی سیستم، تنظیمات (Settings) را انتخاب کنید.
  2. در بخش زبان‌ها و ورودی ، منوی کشویی زبان را انتخاب کنید.
  3. اگر زبان شما در لیست نیست، روی افزودن زبان‌ها کلیک کنید و آن را اضافه کنید.
  4. پس از افزودن، روی گزینه منوی «اقدامات بیشتر» با سه نقطه در کنار زبان خود کلیک کنید و «نمایش ChromeOS به این زبان» را انتخاب کنید.
  5. برای راه‌اندازی مجدد ChromeOS، روی دکمه‌ی «راه‌اندازی مجدد» که در کنار زبان تنظیم‌شده ظاهر می‌شود، کلیک کنید.

مثال‌ها

می‌توانید نمونه‌هایی از بین‌المللی‌سازی را در دایرکتوری examples/api/i18n بیابید. برای مشاهده‌ی یک مثال کامل، به examples/extensions/news مراجعه کنید. برای مشاهده‌ی سایر مثال‌ها و کمک در مشاهده‌ی کد منبع، به Samples مراجعه کنید.

دریافت پیام()

کد زیر یک پیام محلی‌شده را از مرورگر دریافت کرده و آن را به صورت یک رشته نمایش می‌دهد. این کد دو متغیر درون پیام را با رشته‌های "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."
    }
  }
}

برای اطلاعات بیشتر در مورد placeholderها، به صفحه پیام‌های مختص به زبان مراجعه کنید. برای جزئیات بیشتر در مورد فراخوانی getMessage() ، به مرجع API مراجعه کنید.

تابع getAcceptLanguages()

کد زیر زبان‌های پذیرفته‌شده را از مرورگر دریافت کرده و با جدا کردن هر زبان پذیرفته‌شده با ','، آنها را به صورت رشته نمایش می‌دهد. 

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

برای جزئیات بیشتر در مورد فراخوانی getAcceptLanguages() ، به مرجع API مراجعه کنید.

تشخیص زبان()

کد زیر حداکثر ۳ زبان را از رشته داده شده تشخیص می‌دهد و نتیجه را به صورت رشته‌هایی که با خطوط جدید از هم جدا شده‌اند، نمایش می‌دهد. 

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 برگردانده می‌شود، به این معنی که [درصد] از متن برای CLD ناشناخته است.

نوع

رشته

روش‌ها

detectLanguage()

کروم ۴۷+
chrome.i18n.detectLanguage(
  text: string,
): Promise<object>

زبان متن ارائه شده را با استفاده از CLD تشخیص می‌دهد.

پارامترها

  • متن

    رشته

    رشته ورودی کاربر که باید ترجمه شود.

بازگشت‌ها

  • قول دادن<object>

    کروم ۹۹+

getAcceptLanguages()

chrome.i18n.getAcceptLanguages(): Promise<LanguageCode[]>

زبان‌های پذیرفته‌شده‌ی مرورگر را دریافت می‌کند. این با زبان محلی مورد استفاده‌ی مرورگر متفاوت است؛ برای دریافت زبان محلی، از i18n.getUILanguage استفاده کنید.

بازگشت‌ها

getMessage()

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

رشته محلی شده برای پیام مشخص شده را دریافت می‌کند. اگر پیام موجود نباشد، این متد یک رشته خالی ('') برمی‌گرداند. اگر قالب فراخوانی getMessage() اشتباه باشد - برای مثال، messageName یک رشته نباشد یا آرایه جایگزینی بیش از 9 عنصر داشته باشد - این متد undefined را برمی‌گرداند.

پارامترها

  • نام پیام

    رشته

    نام پیام، همانطور که در فایل messages.json مشخص شده است.

  • جایگزینی‌ها

    هر اختیاری

    تا ۹ رشته جایگزین، در صورتی که پیام نیاز به جایگزینی داشته باشد.

  • گزینه‌ها

    شیء اختیاری

    کروم ۷۹+
    • escapeLt

      بولی اختیاری

      از < در ترجمه به &lt; فرار کنید. این فقط برای خود پیام اعمال می‌شود، نه برای جانگهدارها. توسعه‌دهندگان ممکن است بخواهند از این استفاده کنند اگر ترجمه در یک زمینه HTML استفاده شود. قالب‌های Closure که با کامپایلر Closure استفاده می‌شوند، این را به طور خودکار تولید می‌کنند.

بازگشت‌ها

  • رشته

    پیام برای زبان فعلی بومی‌سازی شده است.

getUILanguage()

chrome.i18n.getUILanguage(): string

زبان رابط کاربری مرورگر را برمی‌گرداند. این با i18n.getAcceptLanguages ​​که زبان‌های ترجیحی کاربر را برمی‌گرداند، متفاوت است.

بازگشت‌ها

  • رشته

    کد زبان رابط کاربری مرورگر مانند en-US یا fr-FR.