chrome.i18n

refresh date: 2026-09-25 robots: noindex

شرح

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

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

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

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

نحوه پشتیبانی از چند زبان

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

یک فایل manifest.json و یک فایل با جاوا اسکریپت. فایل .json دارای

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

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

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="In the manifest.json file, " and="" been="" changed="" chrome.i18n.getmessage("extname").="" defines="" en="" file="" file,="" has="" hello="" in="" item="" javascript="" messages.json="" named="" new="" src="/static/images/i18n-after-1.gif" the="" to="" value="" world"="" />

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

  • می‌توانید از هرکدام از منطقه‌های زبانی پشتیبانی‌شده استفاده کنید. اگر از منطقه زبانی پشتیبانی‌نشده‌ای استفاده کنید، Google Chrome آن را نادیده می‌گیرد.
  • در فایل‌های manifest.json و CSS، به رشته‌ای با نام messagename به این صورت ارجاع دهید:

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

    chrome.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 پشتیبانی می‌کند استفاده کنید.

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

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

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

برای آزمایش ترجمه‌ها، شاید بخواهید زبان مرورگرتان را تنظیم کنید. این بخش به شما می‌گوید که چگونه منطقه زبانی را در Windows،‏ Mac OS X،‏ 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 OS X

برای تغییر دادن منطقه زبانی در 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 نسخه ۴۷ و بالاتر

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

نوع

رشته

روش‌ها

detectLanguage()

Promise Chrome 47+
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)
: Promise<object>

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

پارامترها

  • نوشتار

    رشته

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است:

    (result: object) => void

    • نتیجه

      شیء

      شیء LanguageDetectionResult که قابلیت اطمینان زبان شناسایی‌شده و آرایه DetectedLanguage را نگه می‌دارد

      • isReliable

        بولی

        قابلیت اطمینان زبان شناسایی‌شده CLD

      • زبان‌ها

        object[]

        آرایه detectedLanguage

        • زبان

          رشته

        • درصد

          شماره

          درصد زبان شناسایی‌شده

بازگشتی‌ها

  • Promise<object>

    Chrome نسخه ۹۹ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getAcceptLanguages()

قول
chrome.i18n.getAcceptLanguages(
  callback?: function,
)
: Promise<LanguageCode[]>

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است:

    (languages: string[]) => void

    • زبان‌ها

      string[]

      آرایه LanguageCode

بازگشتی‌ها

  • Promise<LanguageCode[]>

    Chrome نسخه ۹۹ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getMessage()

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

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

پارامترها

  • messageName

    رشته

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

  • تعویض‌ها

    هر اختیاری

    حداکثر ۹ رشته جایگزین، اگر پیام به آن نیاز داشته باشد.

  • گزینه‌ها

    شیء اختیاری

    Chrome نسخه ۷۹ و بالاتر
    • escapeLt

      بولی اختیاری

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

بازگشتی‌ها

  • رشته

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

getUILanguage()

chrome.i18n.getUILanguage(): string

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

بازگشتی‌ها

  • رشته

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