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="في ملفManifest.json, " and="" been="" change="" chrome.i18n.getmessage("extname/imagesmessage("extname/images{0}" target=""snippet="" file="" />"<i}{i>"<em="" target="" target=""file" />"<i}{i>" name=""file.json", " and="" be="" change="" chrome.i18n.getmessage("extname/images/message=""<a

إليك بعض الملاحظات حول نشر المحتوى على نطاق عالمي:

• يمكنك استخدام أي من اللغات المعتمَدة. إذا كنت تستخدم لغة غير متاحة، سيتجاهلها 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" للتعرف على السلسلة. وتحدّد "الرسالة" قيمة السلسلة بهذه اللغة. تساعد السمة الاختيارية "description" المترجمين الذين قد لا يتمكنون من الاطّلاع على كيفية استخدام السلسلة في إضافتك. مثال:

  {
    "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 في ملف 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 الإلكتروني".

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

وليس عليك تحديد كل سلسلة لكل لغة معتمَدة. ما دام ملف 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".

في الشكل التالي، تظهر الرسالة "colores" (الألوان) بجميع اللغات الثلاث التي تدعمها الإضافة، بينما تتوفّر الرسالة "extName" في لغتين فقط. أينما يرى مستخدم يستخدم Google Chrome باللغة الإنجليزية الولايات المتحدة التصنيف "ألوان"، يرى مستخدم اللغة الإنجليزية البريطانية "الألوان". يرى المستخدمون لكل من الإنجليزية الأمريكية والإنجليزية البريطانية اسم الإضافة "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. بعد إضافة اللغة، انقر على عنصر القائمة مزيد من الإجراءات المكوّن من 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)"، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات.

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

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

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

chrome.i18n.getUILanguage()