chrome.i18n

توضیحات

آشکار

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

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

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

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

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

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

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

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

چند نکته در مورد بین المللی شدن:

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

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

  __MSG_messagename__
  

• در کد جاوا اسکریپت برنامه افزودنی یا برنامه خود، به رشته ای به نام پیام پیام مانند زیر مراجعه کنید:

  chrome.i18n.getMessage("messagename")
  

• در هر تماس با getMessage() می توانید حداکثر 9 رشته را وارد کنید تا در پیام گنجانده شود. برای جزئیات بیشتر به مثال‌ها مراجعه کنید: پیام دریافت کنید .

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

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

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

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

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

در اینجا مثالی از استفاده از @@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 messages وجود نداشته باشد یا حاوی پیام نباشد، سیستم در فایل en messages نگاه می کند. اگر آن فایل وجود داشته باشد و پیام وجود داشته باشد، سیستم دیگر به دنبال آن نیست.
3. فایل پیام ها را برای محلی پیش فرض جستجو کنید. به عنوان مثال، اگر "default_locale" برنامه افزودنی روی "es" تنظیم شده باشد و نه /_locates/en_GB/messages.json و نه /_locates/en/messages.json حاوی پیام نباشد، برنامه افزودنی از پیام /_locates/es/messages.json استفاده می کند. /_locates/es/messages.json .

در شکل زیر، پیامی با نام "colores" در هر سه محلی است که افزونه پشتیبانی می کند، اما "extName" تنها در دو مورد از محلی ها وجود دارد. هر جا که کاربری که Google Chrome را به زبان انگلیسی ایالات متحده اجرا می کند برچسب "Colors" را ببیند، کاربر انگلیسی انگلیسی "Colors" را می بیند. هم کاربران انگلیسی آمریکایی و هم کاربران انگلیسی بریتانیایی نام پسوند "Hello World" را می بینند. از آنجایی که زبان پیش‌فرض اسپانیایی است، کاربرانی که Google Chrome را به هر زبان غیر انگلیسی اجرا می‌کنند، برچسب "Colores" و نام برنامه افزودنی "Hola mundo" را می‌بینند.

محلی مرورگر خود را تنظیم کنید

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

ویندوز

می‌توانید با استفاده از میان‌بر مخصوص منطقه یا رابط کاربری 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

از رابط کاربری استفاده کنید

در اینجا نحوه تغییر زبان با استفاده از UI در Google Chrome برای Windows آمده است:

1. نماد برنامه > گزینه‌ها
2. تب Under the Hood را انتخاب کنید
3. به محتوای وب بروید
4. روی تغییر تنظیمات فونت و زبان کلیک کنید
5. زبانه زبان ها را انتخاب کنید
6. از منوی کشویی برای تنظیم زبان Google Chrome استفاده کنید
7. کروم را مجددا راه اندازی کنید

سیستم عامل مک

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

1. از منوی Apple، System Preferences را انتخاب کنید
2. در بخش Personal ، بین المللی را انتخاب کنید
3. زبان و مکان خود را انتخاب کنید
4. کروم را مجددا راه اندازی کنید

لینوکس

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

LANGUAGE=es ./chrome

ChromeOS

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

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

نمونه ها

می توانید نمونه هایی از بین المللی سازی را در پوشه examples/api/i18n بیابید. برای مثال کامل، نمونه‌ها/افزونه‌ها/اخبار را ببینید. برای مثال‌های دیگر و کمک به مشاهده کد منبع، به نمونه‌ها مراجعه کنید.

getMessage()

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

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

getAcceptLanguages()

کد زیر زبان های Accept-Languages ​​را از مرورگر دریافت می کند و با جدا کردن هر Accept-language با ',' آنها را به عنوان یک رشته نمایش می دهد.

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()