chrome.i18n

الوصف

البيان

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

المفاهيم وطريقة الاستخدام

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

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

التوافق مع لغات متعدّدة

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

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

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

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

• يمكنك استخدام أي من اللغات المتاحة. إذا كنت تستخدم لغة غير متوافقة، سيتجاهلها 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 الإلكتروني". إذا لم تكن لغتك مُدرَجة هنا، اختَر أقرب بديل. على سبيل المثال، إذا كانت اللغة التلقائية لإضافتك هي "de_CH"، اختَر "de" في "سوق 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 باللغة الإنجليزية (الولايات المتحدة)، يظهر التصنيف "الألوان" لمستخدم يشغّل Google Chrome باللغة الإنجليزية (المملكة المتحدة). يظهر اسم الإضافة "Hello World" لكل من مستخدمي اللغة الإنجليزية في الولايات المتحدة و اللغة الإنجليزية البريطانية. وبما أنّ اللغة التلقائية هي الإسبانية، يظهر للمستخدمين الذين يستخدمون Google Chrome بأي لغة غير الإنجليزية التصنيف "Colores" واسم الإضافة "Hola mundo".

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

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

لتغيير اللغة على جهاز 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()

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

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()