يتوافق Chrome الآن مع مساحة الاسم الموحّدة browser.* (المتاحة بدءًا من Chrome 148). نعمل تدريجيًا على تعديل المستندات. مزيد من المعلومات في دليل الانتقال.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

browser.i18n

الوصف

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

البيان

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

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

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

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

في دليل الإضافة: manifest.json و‎*.html و‎*.js ودليل ‎/_locales. في الدليل ‎ /_locales: الأدلة en وes وko، يحتوي كل منها على ملف messages.json.

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

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

ملف manifest.json وملف JavaScript يحتوي ملف ‎ .json على "Hello World". يحتوي ملف JavaScript على العنوان = 'Hello World'.

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

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

في ملف manifest.json، تم تغيير "Hello World" إلى "__MSG_extName__"، وتمت إضافة عنصر default_locale جديد بقيمة "en". في ملف JavaScript، تم تغيير Hello World إلى browser.i18n.getMessage('extName'). يحدّد ملف جديد باسم ‎ /_locales/en/messages.json السمة "extName".

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

يمكنك استخدام أي من اللغات المتاحة. في حال استخدام لغة غير متوافقة، سيتجاهلها Google Chrome.
في ملفات manifest.json وCSS، يمكنك الإشارة إلى سلسلة باسم messagename على النحو التالي:
```
__MSG_messagename__
```
في رمز JavaScript الخاص بالإضافة أو التطبيق، يمكنك الإشارة إلى سلسلة باسم messagename على النحو التالي:
```
browser.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. يوضّح الشكل التالي الإضافة السابقة مع ترجمة إسبانية جديدة.

يبدو هذا مماثلاً للشكل السابق، ولكن مع ملف جديد في ‎ /_locales/es/messages.json يحتوي على ترجمة إسبانية للرسائل.

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

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

رمز اللغة	اللغة (المنطقة)
`ar`	العربية
`am`	الأمهرية
`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`	الهندية
`hr`	الكرواتية
`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`	Chinese (Taiwan)

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

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

ابحث في ملف الرسائل (إن وُجد) عن اللغة المفضّلة للمستخدم. على سبيل المثال، عندما يتم ضبط لغة Google Chrome على الإنجليزية البريطانية (en_GB)، يبحث النظام أولاً عن الرسالة في /_locales/en_GB/messages.json. إذا كان هذا الملف موجودًا وكانت الرسالة موجودة، فلن يبحث النظام أكثر من ذلك.
إذا كانت اللغة المفضّلة للمستخدم تتضمّن منطقة (أي أنّ اللغة تحتوي على شرطة سفلية: _)، ابحث عن اللغة بدون تلك المنطقة. على سبيل المثال، إذا لم يكن ملف رسائل en_GB موجودًا أو لا يحتوي على الرسالة، يبحث النظام في ملف رسائل en. إذا كان هذا الملف موجودًا والرسالة موجودة، فلن يبحث النظام أكثر من ذلك.
ابحث في ملف الرسائل عن اللغة التلقائية. على سبيل المثال، إذا تم ضبط "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".

أربعة ملفات: manifest.json وثلاثة ملفات messages.json (للغات الإسبانية والإنجليزية والإنجليزية البريطانية). يعرض ملفا es وen إدخالات للرسائل المسماة "extName" و"colores"، بينما يحتوي ملف en_GB على إدخال واحد فقط (لـ "colores").

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

لاختبار الترجمات، قد تحتاج إلى ضبط لغة المتصفّح. يوضّح هذا القسم كيفية ضبط اللغة في Windows وmacOS وLinux وChromeOS.

Windows

يمكنك تغيير اللغة باستخدام اختصار خاص باللغة أو واجهة مستخدم Google Chrome. بعد إعداد الاختصار، يمكنك استخدامه بشكل أسرع واستخدام عدة لغات في الوقت نفسه.

استخدام اختصار خاص بلغة معيّنة

لإنشاء اختصار يشغّل Google Chrome بلغة معيّنة واستخدامه:

أنشئ نسخة من اختصار Google Chrome المتوفّر على سطح المكتب.
أعِد تسمية الاختصار الجديد ليتطابق مع اللغة الجديدة.
غيِّر خصائص الاختصار بحيث يحدّد حقل "الهدف" العلامتَين --lang و--user-data-dir. من المفترض أن يظهر الهدف على النحو التالي:
```
path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
```
افتح 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:

رمز التطبيق > الخيارات
اختَر علامة التبويب نظرة معمّقة
انتقِل إلى محتوى الويب
انقر على تغيير إعدادات الخط واللغة
انقر على علامة التبويب اللغات
استخدِم القائمة المنسدلة لضبط لغة Google Chrome
إعادة تشغيل Chrome

نظام تشغيل Mac

لتغيير اللغة على جهاز Mac، يمكنك استخدام الإعدادات المفضّلة للنظام.

من قائمة Apple، اختَر الإعدادات المفضّلة للنظام (System Preferences)
ضمن قسم شخصي، اختَر دولي
اختيار اللغة والموقع الجغرافي
إعادة تشغيل Chrome

Linux

لتغيير اللغة على نظام التشغيل Linux، عليك أولاً إغلاق Google Chrome. بعد ذلك، اضبط متغيّر بيئة LANGUAGE وشغِّل Google Chrome، كل ذلك في سطر واحد. على سبيل المثال:

LANGUAGE=es ./chrome

ChromeOS

لتغيير اللغة على ChromeOS:

من لوحة النظام، اختَر الإعدادات.
ضمن قسم اللغات والإدخال، اختَر القائمة المنسدلة اللغة.
إذا لم تكن لغتك مدرَجة، انقر على إضافة لغات وأضِفها.
بعد إضافة اللغة، انقر على رمز النقاط الثلاث مزيد من الإجراءات بجانب اللغة واختَر عرض ChromeOS بهذه اللغة.
انقر على الزر إعادة التشغيل الذي يظهر بجانب اللغة المحدّدة لإعادة تشغيل 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 والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

النوع

سلسلة

الطُرق

detectLanguage()

الإصدار 47 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

browser.i18n.detectLanguage(
  text: string,
): Promise<object>

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

المعلمات

نصي

سلسلة

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

المرتجعات

وعد<كائن>

الإصدار 99 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getAcceptLanguages()

browser.i18n.getAcceptLanguages(): Promise<LanguageCode[]>

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

المرتجعات

Promise<LanguageCode[]>

الإصدار 99 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getMessage()

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

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

المعلمات

messageName

سلسلة

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

أيّ اختياري

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

object اختياري

الإصدار 79 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome
- escapeLt
  
  قيمة منطقية اختيارية
  
  تجاهُل < في الترجمة إلى < ينطبق هذا على الرسالة نفسها فقط، وليس على العناصر النائبة. قد يحتاج المطوّرون إلى استخدام هذه الميزة إذا كانت الترجمة مستخدَمة في سياق HTML. تنشئ "نماذج Closure" المستخدمة مع "برنامج تجميع Closure" هذا تلقائيًا.

المرتجعات

سلسلة

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

getUILanguage()

browser.i18n.getUILanguage(): string

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

المرتجعات

سلسلة

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

browser.i18n تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الوصف

البيان

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

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

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

اللغات

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

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

Windows

استخدام اختصار خاص بلغة معيّنة

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

نظام تشغيل Mac

Linux

ChromeOS

أمثلة

getMessage()

getAcceptLanguages()

detectLanguage()

الأنواع

LanguageCode

النوع

الطُرق

detectLanguage()

المعلمات

المرتجعات

getAcceptLanguages()

المرتجعات

getMessage()

المعلمات

المرتجعات

getUILanguage()

المرتجعات

browser.i18n