chrome.i18n

الوصف

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

البيان

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

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

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

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

في دليل الإضافات: بيان.json، و*.html، و *.js، و/_locates. في الدليل /_locates: en وes وko، يحتوي كل منها على ملف Message.json.

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

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

ملف sitemap.json وملف باستخدام JavaScript ويحتوي ملف .json على

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

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

<img "__msg_extname__",="" "default_locale"="" "ar".="" "extname"."="" "hello="" _locates=&quot;&quot; a=&quot;&quot; alt="في ملفian.json، " and=&quot;&quot; كانت = " changed=&quot;&quot; chrome.i18n.getmessage("extname").="" defines=&quot;&quot; en=&quot;&quot; file=&quot;&quot; file,=&quot;&quot; has=&quot;&quot; hello=&quot;&quot; in=&quot;&quot; item=&quot;&quot; javascript=&quot;&quot; messages.json=&quot;&quot; named=&quot;&quot; new="" src=&quot;/static/docs/extensions/mv2/reference/i18n/images/i18n-after-1.gif&quot; the=&quot;&quot; to=&quot;&quot; value="" العالم"="" />

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

  • يمكنك استخدام أي من اللغات المتاحة. إذا كنت تستخدم لغة غير متاحة، سيتعين على Google Chrome ويتجاهله.

  • في manifest.json وملفات CSS، ارجع إلى سلسلة باسم messagename على النحو التالي:

    __MSG_messagename__

  • في رمز JavaScript للإضافة أو التطبيق، ارجع إلى سلسلة باسم messagename على النحو التالي:

    chrome.i18n.getMessage("messagename")

  • في كل استدعاء إلى getMessage()، يمكنك تقديم ما يصل إلى 9 سلاسل لتضمينها في الرسالة. عرض أمثلة: getMessage للحصول على التفاصيل.

  • تم توفير بعض الرسائل، مثل @@bidi_dir و@@ui_locale من خلال عملية نشر المحتوى على نطاق عالمي. . راجِع قسم الرسائل المحدَّدة مسبقًا للحصول على قائمة كاملة بأسماء الرسائل المحدَّدة مسبقًا.

  • في messages.json، يكون لكل سلسلة مرئية للمستخدم اسم أو "رسالة" وعنصر اختياري &quot;description&quot; عنصر واحد. الاسم هو مفتاح مثل "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. الشكل التالي لعرض الإضافة السابقة بترجمة إسبانية جديدة.

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

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

يوفّر نظام التدويل بعض الرسائل المحدّدة مسبقًا لمساعدتك في الأقلمة. هذه التي تتضمّن @@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". وإلا، فهي "صحيح".
@@bidi_end_edgeإذا كانت قيمة @@bidi_dir هي "ltr"، تكون القيمة "right". وإلا، فهي "اليسار".

في ما يلي مثال على استخدام @@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 الغوجاراتية
هو العبرية
hi الهندية
ساعة الكرواتية
hu الهنغارية
id الإندونيسية
it الإيطالية
ja اليابانية
kn الكانادا
ko الكورية
lt الليتوانية
lv اللاتفية
ml المالايالامية
mr الماراثية
ms الملاوية‬
nl الهولندية
لا النرويجية
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. ابحث عن اللغة التلقائية في ملف الرسائل. على سبيل المثال، إذا كانت الإضافة الإعدادات التلقائية تم ضبطها على "es"، وليس على /_locates/en_GB/messages.json أو تحتوي /_locates/en/messages.json على الرسالة، وتستخدم الإضافة الرسالة من /_locates/es/messages.json

في الشكل التالي، الرسالة المسماة "الألوان" موجودة في جميع اللغات الثلاث التي ولكن بامتداد "extName" في بلدين فقط. أينما كان المستخدم الذي يشغّل Google Chrome في الولايات المتحدة يرى الإنجليزية التصنيف "الألوان"، ويرى مستخدم الإنجليزية البريطانية "الألوان". كل من الإنجليزية الأمريكية ويظهر لمستخدمي اللغة الإنجليزية البريطانية اسم الإضافة "Hello World". ولأن اللغة الافتراضية هي الإسبانية، إذا كان المستخدمون يستخدمون Google Chrome بأي لغة غير إنجليزية، يمكنهم مشاهدة التصنيف "الألوان" والإضافة اسم "هولا موندو".

أربعة ملفات هي: ian.json وثلاثة ملفات message.json (لـ es وen وen_GB). يعرض الملفان es وen إدخالات للرسائل المُسمّاة.

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

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

الأنواع

LanguageCode

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

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

النوع

سلسلة

الطُرق

detectLanguage()

وعود الإصدار 47 من Chrome أو الإصدارات الأحدث 
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

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

المعلمات

  • text

    سلسلة

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

  • رد الاتصال

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

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

    (result: object) => void

    • نتيجة

      كائن

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

      • isReliable

        منطقي

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

      • اللغات

        object[]

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

        • language

          سلسلة

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

          الرقم

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

المرتجعات

  • Promise&lt;object&gt;

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

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

getAcceptLanguages()

وعود 
chrome.i18n.getAcceptLanguages(
  callback?: function,
)

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

المعلمات

  • رد الاتصال

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

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

    (languages: string[]) => void

    • اللغات

      سلسلة[]

      مصفوفة LanguageCode

المرتجعات

  • Promise&lt;LanguageCode[]&gt;

    الإصدار 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

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

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

المرتجعات

  • سلسلة

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

getUILanguage()

chrome.i18n.getUILanguage()

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

المرتجعات

  • سلسلة

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