chrome.i18n

الوصف

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

البيان

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

المفاهيم والاستخدام

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

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

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

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

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

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

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="In the تقريرك.json file, " and="" be="" change="" chrome.i18n.get("extname/extensions" item="" en="" file has" file=" "

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

• يمكنك استخدام أي من اللغات المتاحة. إذا كنت تستخدم لغة غير مدعومة، فسيتجاهلها 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 وترجمته ووضع النسخة في دليل جديد ضمن /_locates. على سبيل المثال، لدعم الإسبانية، ما عليك سوى إضافة نسخة مترجمة من messages.json ضمن /_locates/es. يوضح الشكل التالي الإضافة السابقة بترجمة إسبانية جديدة.

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

يوفّر نظام التدويل بعض الرسائل المحدّدة مسبقًا لمساعدتك في الأقلمة. وتتضمّن هذه الميزات @@ui_locale لكي تتمكّن من التعرّف على اللغة الحالية لواجهة المستخدم، بالإضافة إلى بعض رسائل @@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 الإلكتروني". إذا لم تكن لغتك مدرَجة هنا، اختَر أقرب بديل. على سبيل المثال، إذا كانت اللغة التلقائية للإضافة هي "de_CH"، اختَر "de" في "سوق Chrome الإلكتروني".

رمز اللغة	اللغة (المنطقة)
ar	العربية
صباحًا	الأمهرية
bg	البلغارية
bn	البنغالية
ca	الكتالانية
cs	التشيكية
da	الدانمركية
de	الألمانية
el	اليونانية
en	الإنجليزية
en_AU	الإنجليزية (أستراليا)
en_GB	الإنجليزية (بريطانيا العظمى)
en_US	الإنجليزية (الولايات المتحدة الأمريكية)
es	الإسبانية
es_419	الإسبانية (أمريكا اللاتينية ومنطقة البحر الكاريبي)
et	الإستونية
fa	الفارسية
fi	الفنلندية
fil	الفلبينية
fr	مأكولات فرنسية
gu	الغوجاراتية
he	العبرية
hi	الهندية
ساعة	الكرواتية
hu	المجرية
id	الإندونيسية
it	الإيطالية
ja	اليابانية
kn	الكانادا
ko	الكورية
lt	الليتوانية
lv	اللاتفية
ml	المالايالامية
mr	الماراثية
ms	الملاوية‬
nl	الهولندية
no	النرويجية
pl	البولندية
pt_BR	البرتغالية (البرازيل)
pt_PT	برتغالي (البرتغال)
ro	الرومانية
ru	الروسية
sk	السلوفاكية
sl	السلوفينية
sr	الصربية
sv	السويدية
sw	السواحيلية
ta	التاميلية
te	التيلوغوية
th	مأكولات تايلاندية
tr	التركية
uk	الأوكرانية
vi	الفيتنامية
zh_CN	الصينية (الصين)
zh_TW	الصينية (تايوان)

البحث عن رسائل

ليس عليك تحديد كل سلسلة لكل لغة متاحة. ما دام ملف messages.json للّغة التلقائية يتضمّن قيمة لكل سلسلة، سيتم تشغيل الإضافة أو التطبيق مهما كان مدى قلة الترجمة. وفي ما يلي طريقة بحث نظام الإضافات عن الرسالة:

1. ابحث في ملف الرسائل (إن وجدت) عن اللغة المفضّلة للمستخدم. على سبيل المثال، عند ضبط لغة Google Chrome على الإنجليزية البريطانية (en_GB)، يبحث النظام أولاً عن الرسالة في /_locates/en_GB/messages.json. في حالة وجود هذا الملف والرسالة كذلك، لن يبحث النظام بعد ذلك.
2. إذا كانت اللغة المفضلة للمستخدم لها منطقة (أي اللغة بها شرطة سفلية: _)، فابحث عن اللغة بدون تلك المنطقة. على سبيل المثال، إذا لم يتوفّر ملف رسائل en_GB أو لا يحتوي على الرسالة، سيبحث النظام في ملف رسائل en. إذا كان هذا الملف موجودًا وكانت الرسالة كذلك، فلن يبحث النظام بعد ذلك.
3. ابحث عن اللغة التلقائية في ملف الرسائل. على سبيل المثال، إذا تم ضبط "default_locale" للإضافة على "es"، ولم تحتوي أيٌ من /_locates/en_GB/messages.json أو /_locates/en/messages.json على الرسالة، ستستخدم الإضافة الرسالة الواردة من /_locates/es/messages.json.

في الشكل التالي، تظهر الرسالة المسماة "الألوان" في جميع اللغات الثلاث التي تتيحها الإضافة، لكن "extName" موجود في لغتين فقط من اللغات. حيثما يرى مستخدم يشغّل Google Chrome باللغة الإنجليزية الأمريكية تصنيف "الألوان"، يرى مستخدم اللغة الإنجليزية البريطانية "الألوان". يشاهد مستخدمو كل من الإنجليزية الأمريكية والإنجليزية البريطانية اسم الإضافة "Hello World". ولأن اللغة الافتراضية هي الإسبانية، فإن المستخدمين الذين يشغلون Google Chrome بأي لغة غير إنجليزية يرون التصنيف "الألوان" واسم الإضافة "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. بعد الإضافة، انقر على عنصر القائمة مزيد من الإجراءات المكوّن من 3 نقاط بجانب لغتك واختَر عرض نظام التشغيل 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، ما يعني أنّ [percentage] من النص غير معروفة لـ CLD

النوع

سلسلة

الطُرق

detectLanguage()

التوقعات Chrome 47 والإصدارات الأحدث

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

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

المعلمات

• text

  سلسلة

  سلسلة البيانات التي أدخلها المستخدم المطلوب ترجمتها.

• رد الاتصال

  الدالة اختيارية

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

  (result: object) => void

  • نتيجة

    عنصر

    كائن LanguageDetectionResult الذي يحتوي على موثوقية langugae ومصفوفة DetectedLanguage

    • isReliable

      boolean

      تم رصد موثوقية اللغة التي تم رصدها باستخدام أداة CLD

    • لغة

      الكائن[]

      مصفوفة اللغة المكتشفة

      • language

        سلسلة

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

        الرقم

        النسبة المئوية للّغة التي تم رصدها

المرتجعات

• Promise<object>

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

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال للتوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. ويحلّ الوعد بالنوع نفسه الذي يتم إرساله إلى معاودة الاتصال.

getAcceptLanguages()

وعد بذلك

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

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

المعلمات

• رد الاتصال

  الدالة اختيارية

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

  (languages: string[]) => void

  • لغة

    سلسلة[]

    مصفوفة LanguageCode

المرتجعات

• Promise<LanguageCode[]>

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

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال للتوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. ويحلّ الوعد بالنوع نفسه الذي يتم إرساله إلى معاودة الاتصال.

getMessage()

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

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

المعلمات

• messageName

  سلسلة

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

• البدائل

  أي خيار اختياري

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

• الخيارات

  الكائن اختياري

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

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

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

المرتجعات

• سلسلة

  تمت ترجمة الرسالة إلى اللغة الحالية.

getUILanguage()

chrome.i18n.getUILanguage()

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

المرتجعات

• سلسلة

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