chrome.i18n

refresh date: 2026-09-25 robots: noindex

الوصف

عليك وضع جميع السلاسل النصية المرئية للمستخدمين في ملف باسم 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"="" />

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

• يمكنك استخدام أي من اللغات المتوافقة. إذا كنت تستخدم لغة غير متوافقة، سيتجاهلها 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 في ملف 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" في لغتين فقط. في أي مكان يظهر فيه التصنيف "Colors" لمستخدمي Google Chrome باللغة الإنجليزية في الولايات المتحدة، يظهر التصنيف "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

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

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

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

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

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

chrome.i18n.getUILanguage(): string