chrome.i18n

تاریخ به‌روزرسانی: 2026-09-25 ربات‌ها: noindex

توضیحات

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

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

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

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

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

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

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

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

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

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

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

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

سیستم بین‌المللی‌سازی چند پیام از پیش تعریف‌شده برای کمک به بومی‌سازی ارائه می‌دهد. این پیام‌ها شامل @@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 ).

زبان‌های پشتیبانی‌شده

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

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

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

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

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

ویندوز

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

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

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

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

نکته: مشخص کردن --user-data-dir اختیاری اما مفید است. داشتن یک دایرکتوری داده برای هر زبان به شما امکان می‌دهد مرورگر را همزمان به چندین زبان اجرا کنید. یک عیب این است که به دلیل اینکه داده‌های زبان‌ها به اشتراک گذاشته نمی‌شوند، باید افزونه خود را چندین بار نصب کنید - یک بار برای هر زبان، که وقتی به آن زبان صحبت نمی‌کنید، می‌تواند چالش برانگیز باشد. برای اطلاعات بیشتر، به بخش ایجاد و استفاده از پروفایل‌ها مراجعه کنید.

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

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

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 مراجعه کنید.

مثال‌ها: 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."
    }
  }
}

برای اطلاعات بیشتر در مورد 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,
  callback?: function,
): Promise<object>

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

پارامترها

• متن

  رشته

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (result: object) => void

  • نتیجه

    شیء

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

    • قابل اعتماد است

      بولی

      قابلیت اطمینان زبان تشخیص داده شده توسط CLD

    • زبان‌ها

      شیء[]

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

      • زبان

        رشته

      • درصد

        شماره

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

بازگشت‌ها

• قول دادن<object>

  کروم ۹۹+

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getAcceptLanguages()

وعده

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

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

پارامترها

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (languages: string[]) => void

  • زبان‌ها

    رشته[]

    آرایه‌ای از کد زبان

بازگشت‌ها

• قول< کد زبان []>

  کروم ۹۹+

  Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getMessage()

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

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

پارامترها

• نام پیام

  رشته

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

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

  هر اختیاری

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

• گزینه‌ها

  شیء اختیاری

  کروم ۷۹+
  • escapeLt

    بولی اختیاری

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

بازگشت‌ها

• رشته

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

getUILanguage()

chrome.i18n.getUILanguage(): string

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

بازگشت‌ها

• رشته

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