الوصف
يمكنك استخدام بنية chrome.i18n
الأساسية لنشر المحتوى على نطاق عالمي عبر التطبيق أو الإضافة بالكامل.
يجب وضع جميع السلاسل المرئية للمستخدم في ملف باسم messages.json
. في كل مرة
تضيف لغة جديدة، تتم إضافة ملف رسائل ضمن دليل باسم _locales/_localeCode_
، حيث يكون
localeCode عبارة عن رمز مثل en
للّغة الإنجليزية.
في ما يلي التدرّج الهرمي للملفات لامتداد دولي يتوافق مع الإنجليزية (en
) والإسبانية
(es
) والكورية (ko
):
كيفية إتاحة لغات متعددة
لنفترض أن لديك امتدادًا بالملفات الموضحة في الشكل التالي:
ولتدويل هذه الإضافة، عليك تسمية كل سلسلة مرئية للمستخدم ووضعها في ملف رسائل. يستخدم ملف بيان الإضافة وملفات CSS ورمز JavaScript اسم كل سلسلة للحصول على النسخة المترجَمة منها.
إليك ما تبدو عليه الإضافة عند تدويلها (مع العلم أنّها لا تزال تحتوي على سلاسل إنجليزية فقط):
<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="في ملفManifest.json، " and="" has="" change="" chrome.i18n.getmessage("extname/imagesmessage("extname/imagesmessage("extname/images"("extname/images8" ("extname)}"التعريف="" en="" item="" file="" 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" للتعرف على السلسلة. وتحدّد "الرسالة" قيمة السلسلة بهذه اللغة. تساعد السمة الاختيارية "description" المترجمين الذين قد لا يتمكنون من الاطّلاع على كيفية استخدام السلسلة في إضافتك. مثال:{ "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_...
التي تتيح لك رصد اتجاه النص. تحمل الرسائل الأخيرة أسماء مشابهة للثوابت في واجهة برمجة التطبيقات ثنائي الاتجاه للأدوات.
يمكن استخدام الرسالة الخاصة @@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"، تكون القيمة هي "اليسار" والقيمة "لليمين". |
@@bidi_end_edge | وإذا كانت قيمة @@bidi_dir هي "ltr"، يعني ذلك أنّها على اليمين، والقيمة أخرى هي "اليسار". |
إليك مثال على استخدام السمة @@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 الإلكتروني".
البحث عن الرسائل
وليس عليك تحديد كل سلسلة لكل لغة معتمَدة. ما دام ملف 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 باللغة الإنجليزية الولايات المتحدة التصنيف "ألوان"، يرى مستخدم اللغة الإنجليزية البريطانية "الألوان". يرى المستخدمون لكل من الإنجليزية الأمريكية والإنجليزية البريطانية اسم الإضافة "Hello World". نظرًا لأن اللغة الافتراضية هي الإسبانية، يرى المستخدمون الذين يستخدمون Google Chrome بأي لغة غير إنجليزية التسمية "Colores" واسم الإضافة "Hola mundo".
كيفية ضبط لغة المتصفّح
لاختبار الترجمات، قد تحتاج إلى ضبط لغة المتصفح. يخبرك هذا القسم بكيفية ضبط اللغة في Windows وMac OS X و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
استخدام واجهة المستخدم
إليك كيفية تغيير اللغة باستخدام واجهة المستخدم في Google Chrome لنظام التشغيل Windows:
- رمز التطبيق > الخيارات
- اختر علامة التبويب الخيارات المتقدمة
- انتقِل للأسفل إلى محتوى الويب.
- انقر على تغيير إعدادات الخط واللغة.
- اختَر علامة التبويب اللغات.
- استخدِم القائمة المنسدلة لضبط لغة Google Chrome.
- إعادة تشغيل Chrome
Mac OS X
لتغيير اللغة على Mac، يمكنك استخدام إعدادات النظام المفضّلة.
- من قائمة Apple، اختَر System Preferences (الإعدادات المفضَّلة للنظام).
- ضمن القسم إعدادات شخصية، اختَر دولي.
- اختيار اللغة والموقع الجغرافي
- إعادة تشغيل Chrome
Linux
لتغيير اللغة على نظام التشغيل Linux، عليك أولاً الخروج من Google Chrome. بعد ذلك، كل ذلك في سطر واحد، عيِّن متغير البيئة LANGUAGE وشغّل Google Chrome. مثال:
LANGUAGE=es ./chrome
ChromeOS
لتغيير اللغة على نظام التشغيل ChromeOS:
- من لوحة النظام، اختَر الإعدادات.
- ضمن قسم اللغات والإدخال، اختَر القائمة المنسدلة اللغة.
- إذا لم تكن لغتك مدرَجة، انقر على إضافة لغات وأضِفها.
- بعد إضافة اللغة، انقر على عنصر القائمة مزيد من الإجراءات المكوّن من 3 نقاط بجانب لغتك واختَر عرض نظام التشغيل 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()
، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات.
مثال: getAcceptاللغات
يحصل الرمز التالي على لغات قبول من المتصفح ويعرضها كسلسلة عن طريق فصل كل لغة قبول بـ ','.
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
تمثّل هذه السمة رمز لغة ISO، مثل en
أو fr
. للحصول على قائمة كاملة باللغات التي تتيحها هذه الطريقة، يُرجى الاطّلاع على kLanguageInfoTable. إذا كنت تستخدم لغة غير معروفة، سيتم عرض رمز الاستجابة und
، ما يعني أنّ [النسبة المئوية] من النص غير معروفة لدى بروتوكول CLD.
النوع
سلسلة
الطُرق
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
ترصد لغة النص المقدَّم باستخدام CLD.
المَعلمات
-
text
سلسلة
سلسلة البيانات التي أدخلها المستخدم المطلوب ترجمتها
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: object) => void
-
نتيجة
كائن
الكائن LanguageDetectionResult الذي يحمل موثوقية langugae المكتشفة والصفيفة من DetectedLanguage
-
isReliable
boolean
موثوقية اللغة التي تم رصدها من خلال بروتوكول CLD
-
اللغات
الكائن[]
مصفوفة اللغة التي تم رصدها
-
language
سلسلة
-
النسبة المئوية
الرقم
النسبة المئوية للّغة التي تم رصدها
-
-
-
المرتجعات
-
Promise<object>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
يتيح هذا الإعداد إمكانية قبول لغات المتصفّح. وتختلف هذه اللغة عن اللغة التي يستخدمها المتصفّح. للحصول على اللغة، يمكنك استخدام i18n.getUILanguage
.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(languages: string[]) => void
-
اللغات
سلسلة[]
مصفوفة LanguageCode
-
المرتجعات
-
Promise<LanguageCode[]>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من 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 Compiler هذا تلقائيًا.
-
المرتجعات
-
سلسلة
تمت ترجمة الرسالة للّغة الحالية.
getUILanguage()
chrome.i18n.getUILanguage()
للحصول على لغة واجهة المستخدم الخاصة بالمتصفّح ويختلف هذا عن i18n.getAcceptLanguages
التي تعرض لغات المستخدم المفضلة.
المرتجعات
-
سلسلة
رمز لغة واجهة المستخدم في المتصفّح، مثل en-US أو fr-FR.