chrome.i18n

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم البنية الأساسية لـ chrome.i18n لتنفيذ عملية التدويل في تطبيقك أو إضافتك بالكامل.

عليك وضع جميع السلاسل المرئية للمستخدم في ملف باسم messages.json. في كل مرة تضيف فيها لغة جديدة، يمكنك إضافة ملف رسائل ضمن دليل باسم _locales/_localeCode_، حيث localeCode هو رمز مثل en للغة الإنجليزية.

في ما يلي التسلسل الهرمي للملفات لإضافة تم تدويلها وتتوافق مع اللغات الإنجليزية (en) والإسبانية (es) والكورية (ko):

كيفية إتاحة لغات متعددة

لنفترض أنّ لديك إضافة تحتوي على الملفات الموضّحة في الشكل التالي:

لإتاحة هذه الإضافة بلغات متعددة، عليك تسمية كل سلسلة تظهر للمستخدم ووضعها في ملف رسائل. يستخدم بيان الإضافة وملفات CSS ورمز JavaScript اسم كل سلسلة للحصول على نسختها المترجَمة.

في ما يلي شكل الإضافة بعد تدويلها (يُرجى ملاحظة أنّها لا تزال تحتوي على سلاسل باللغة الإنجليزية فقط):

<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"="" />

ملاحظة مهمة: إذا كانت الإضافة تحتوي على دليل _locales، يجب أن يحدّد البيان "default_locale".

بعض الملاحظات حول التدويل:

• يمكنك استخدام أي من اللغات المتاحة. في حال استخدام لغة غير متوافقة، سيتجاهلها Google Chrome.

• في ملفات manifest.json وCSS، يمكنك الإشارة إلى سلسلة باسم messagename على النحو التالي:

  __MSG_messagename__
  

• في رمز JavaScript الخاص بالإضافة أو التطبيق، يمكنك الإشارة إلى سلسلة باسم messagename على النحو التالي:

  chrome.i18n.getMessage("messagename")
  

• في كل طلب إلى getMessage()، يمكنك تقديم ما يصل إلى 9 سلاسل ليتم تضمينها في الرسالة. لمزيد من التفاصيل، يُرجى الاطّلاع على أمثلة: 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. يوضّح الشكل التالي الإضافة السابقة مع ترجمة إسبانية جديدة.

الرسائل المحدّدة مسبقًا

يوفّر نظام التدويل بعض الرسائل المحدّدة مسبقًا لمساعدتك في الأقلمة. وتشمل هذه الميزات @@ui_locale، حتى تتمكّن من رصد اللغة الحالية لواجهة المستخدم، وبعض رسائل @@bidi_... التي تتيح لك رصد اتجاه النص. تحمل الرسائل الأخيرة أسماء مشابهة للثوابت في واجهة برمجة التطبيقات BIDI (ثنائية الاتجاه) للأدوات.

يمكن استخدام الرسالة الخاصة @@extension_id في ملفات CSS وJavaScript، سواء كانت الإضافة أو التطبيق مترجمَين أم لا. لا تعمل هذه الرسالة في ملفات البيان.

يوضّح الجدول التالي كل رسالة محدّدة مسبقًا.

اسم الرسالة	الوصف
@@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).

الإعدادات المحلية المدعمة

يمكنك استخدام أي من اللغات التي يتيحها "سوق 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".

كيفية ضبط لغة المتصفّح

لاختبار الترجمات، قد تحتاج إلى ضبط لغة المتصفّح. يوضّح لك هذا القسم كيفية ضبط اللغة في 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

ملاحظة: إنّ تحديد --user-data-dir هو أمر اختياري ولكنه مفيد. يتيح لك توفير دليل بيانات واحد لكل لغة تشغيل المتصفّح بعدة لغات في الوقت نفسه. من عيوب هذه الطريقة أنّه لا تتم مشاركة بيانات اللغات، لذا عليك تثبيت الإضافة عدة مرات، مرة لكل لغة، وقد يكون ذلك صعبًا إذا كنت لا تتحدث اللغة. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء الملفات الشخصية واستخدامها.

استخدام واجهة المستخدم

في ما يلي كيفية تغيير اللغة باستخدام واجهة المستخدم في Google Chrome لنظام التشغيل Windows:

1. رمز التطبيق > الخيارات
2. اختَر علامة التبويب نظرة معمّقة
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

يحصل الرمز التالي على رسالة مترجَمة من المتصفّح ويعرضها كسلسلة. وتستبدل عنصرين نائبين داخل الرسالة بالسلسلتين "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()، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

مثال: getAcceptLanguages

يحصل الرمز التالي على اللغات المقبولة من المتصفّح ويعرضها كسلسلة من خلال فصل كل لغة مقبولة بفاصلة ",".

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

للحصول على تفاصيل حول استدعاء getAcceptLanguages()، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

مثال: 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)، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

الأنواع

LanguageCode

الإصدار 47 من Chrome والإصدارات الأحدث

رمز لغة ISO، مثل en أو fr للاطّلاع على قائمة كاملة باللغات التي تتيحها هذه الطريقة، يُرجى مراجعة kLanguageInfoTable. بالنسبة إلى لغة غير معروفة، سيتم عرض und، ما يعني أنّ [النسبة المئوية] من النص غير معروفة لمكتبة CLD

النوع

سلسلة

الطُرق

detectLanguage()

Promise الإصدار 47 من Chrome والإصدارات الأحدث

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

ترصد هذه الدالة لغة النص المقدَّم باستخدام CLD.

المعلمات

• نصي

  سلسلة

  تمثّل هذه السمة سلسلة إدخال المستخدم المطلوب ترجمتها.

• callback

  function اختياري

  تظهر المَعلمة callback على النحو التالي:

  (result: object) => void

  • نتيجة

    عنصر

    عنصر LanguageDetectionResult الذي يحتوي على موثوقية اللغة التي تم التعرّف عليها ومصفوفة من DetectedLanguage

    • isReliable

      قيمة منطقية

      موثوقية اللغة التي تم التعرّف عليها من خلال CLD

    • اللغات

      object[]‎

      مصفوفة detectedLanguage

      • language

        سلسلة

      • النسبة المئوية

        الرقم

        النسبة المئوية للغة التي تم التعرّف عليها

المرتجعات

• وعد<كائن>

  الإصدار 99 من Chrome أو الإصدارات الأحدث

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getAcceptLanguages()

Promise

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

تستردّ اللغات المقبولة في المتصفّح. ويختلف هذا عن اللغة التي يستخدمها المتصفّح. للحصول على اللغة، استخدِم i18n.getUILanguage.

المعلمات

• callback

  function اختياري

  تظهر المَعلمة callback على النحو التالي:

  (languages: string[]) => void

  • اللغات

    string[]

    مصفوفة LanguageCode

المرتجعات

• Promise<LanguageCode[]>

  الإصدار 99 من Chrome أو الإصدارات الأحدث

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getMessage()

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

تحصل على السلسلة المترجَمة للرسالة المحدّدة. إذا كانت الرسالة غير متوفّرة، ستعرض هذه الطريقة سلسلة فارغة (''). وإذا كان تنسيق طلب getMessage() غير صحيح، على سبيل المثال، إذا لم تكن السلسلة messageName أو مصفوفة substitutions تحتوي على أكثر من 9 عناصر، ستعرض هذه الطريقة undefined.

المعلمات

• messageName

  سلسلة

  اسم الرسالة، كما هو محدّد في ملف messages.json.

• تبديلات

  أيّ اختياري

  ما يصل إلى 9 سلاسل بديلة، إذا كانت الرسالة تتطلب أيًا منها.

• الخيارات

  object اختياري

  الإصدار 79 من Chrome أو الإصدارات الأحدث
  • escapeLt

    قيمة منطقية اختيارية

    تجاهُل < في الترجمة إلى < ينطبق هذا على الرسالة نفسها فقط، وليس على العناصر النائبة. قد يحتاج المطوّرون إلى استخدام هذه الميزة إذا كانت الترجمة مستخدَمة في سياق HTML. تنشئ "نماذج Closure" المستخدمة مع "برنامج تجميع Closure" هذا تلقائيًا.

المرتجعات

• سلسلة

  تمت ترجمة الرسالة لتناسب اللغة الحالية.

getUILanguage()

chrome.i18n.getUILanguage(): string

للحصول على لغة واجهة مستخدم المتصفّح يختلف ذلك عن i18n.getAcceptLanguages التي تعرض لغات المستخدم المفضّلة.

المرتجعات

• سلسلة

  رمز لغة واجهة مستخدم المتصفّح، مثل en-US أو fr-FR