browser.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» به browser.i18n.getMessage('extName') تغییر کرده است. فایل جدیدی با نام /_locales/en/messages.json،‏ «extName» را تعریف می‌کند.

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

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

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

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

سیستم بین‌المللی‌سازی چند پیام ازپیش‌تعریف‌شده برای کمک به بومی‌سازی ارائه می‌دهد. این شامل @@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 زبان پیش‌فرض برای هر رشته مقداری داشته باشد، افزونه یا برنامه شما بدون توجه به اینکه ترجمه چقدر پراکنده است، اجرا خواهد شد. در اینجا نحوه جستجوی سیستم افزونه برای یک پیام آورده شده است:

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

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

تنظیم منطقه زبانی مرورگر

برای آزمایش ترجمه‌ها، شاید بخواهید زبان مرورگرتان را تنظیم کنید. این بخش به شما می‌گوید چگونه منطقه زبانی را در Windows،‏ macOS،‏ 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. برگه Under the Hood (زیر کاپوت) را انتخاب کنید
  3. به محتوای وب پیمایش کنید
  4. روی تغییر تنظیمات قلم و زبان کلیک کنید
  5. برگه زبان‌ها را انتخاب کنید
  6. از منو کرکره‌ای برای تنظیم زبان Google Chrome استفاده کنید
  7. بازراه‌اندازی Chrome

سیستم‌عامل Mac

برای تغییر دادن منطقه زبانی در Mac، از اولویت‌های سیستم استفاده می‌کنید.

  1. از منوِ Apple، System Preferences (تنظیمات سیستم) را انتخاب کنید
  2. در بخش شخصی، بین‌المللی را انتخاب کنید
  3. انتخاب زبان و مکان
  4. بازراه‌اندازی Chrome

Linux

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

LANGUAGE=es ./chrome

ChromeOS

برای تغییر دادن منطقه زبانی در ChromeOS:

  1. از سینی سیستم، تنظیمات را انتخاب کنید.
  2. در بخش زبان‌ها و ورودی، منو کرکره‌ای زبان را انتخاب کنید.
  3. اگر زبان موردنظرتان در فهرست نیست، روی افزودن زبان کلیک کنید و آن را اضافه کنید.
  4. پس‌از افزودن، روی منوِ ۳نقطه‌ای کنش‌های بیشتر در کنار زبان موردنظر کلیک کنید و نمایش ChromeOS به این زبان را انتخاب کنید.
  5. روی دکمه بازراه‌اندازی که در کنار زبان تنظیم‌شده نشان داده می‌شود کلیک کنید تا 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

Chrome نسخه ۴۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

کد زبان ISO مانند en یا fr. برای مشاهده فهرست کامل زبان‌های پشتیبانی‌شده توسط این روش، به kLanguageInfoTable مراجعه کنید. برای زبان ناشناخته، und برگردانده می‌شود، یعنی [درصد] نوشتار برای CLD ناشناخته است

نوع

رشته

روش‌ها

detectLanguage()

Chrome نسخه ۴۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸
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 < در ترجمه به &lt;. این فقط برای خود پیام اعمال می‌شود، نه برای جای‌بان‌ها. اگر ترجمه در بافت HTML استفاده شود، توسعه‌دهندگان ممکن است بخواهند از این استفاده کنند. «الگوهای Closure» که با Closure Compiler استفاده می‌شود این را به‌طور خودکار تولید می‌کند.

بازگشتی‌ها

  • رشته

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

getUILanguage()

browser.i18n.getUILanguage(): string

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

بازگشتی‌ها

  • رشته

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