دعم لغات وثقافات مختلفة

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

من الممارسات الجيدة فصل الموارد الخاصة بثقافة عن باقي التطبيق في حل مشكلة الموارد الخاصة باللغة والثقافة بناءً على إعدادات لغة النظام. يمكنك تقديم دعم للغات مختلفة باستخدام دليل الموارد في مشروع Android الخاص بك.

يمكنك تحديد الموارد المخصّصة لثقافات الأشخاص الذين يستخدمون تطبيقك. ويمكنك تقديم أي نوع موارد مناسب للغة المستخدمين وثقافتهم. على سبيل المثال، تعرض لقطات الشاشة التالية تطبيقًا يعرض سلسلة وموارد قابلة للرسم بلغة en_US التلقائية للجهاز واللغة es_ES الإسبانية.

يعرض التطبيق نصًا ورمزًا مختلفًا بناءً على اللغة الحالية

الشكل 1. التطبيق يستخدم موارد مختلفة بناءً على اللغة الحالية.

عند إنشاء مشروع باستخدام أدوات SDK لنظام التشغيل Android، تنشئ الأدوات دليل res/ في المستوى الأعلى من المشروع. تتوفّر ضمن دليل res/ هذا أدلة فرعية لأنواع الموارد المختلفة. هناك أيضًا بعض الملفات التلقائية، مثل ملف res/values/strings.xml الذي يحتوي على قيم السلسلة.

إنّ دعم لغات مختلفة لا يقتصر على استخدام موارد خاصة باللغة. يختار بعض المستخدمين لغة تستخدم نصوصًا برمجية من اليمين إلى اليسار (RTL)، مثل العربية أو العبرية، في لغة واجهة المستخدم الخاصة بهم. بالنسبة إلى المستخدمين الآخرين الذين ضبطوا لغة واجهة المستخدم على لغة تستخدم نصوص LTR، مثل الإنجليزية، يمكنهم عرض أو إنشاء محتوى بلغة تستخدم النصوص البرمجية من اليمين إلى اليسار. لدعم كلا النوعين من المستخدمين، يحتاج تطبيقك إلى ما يلي:

  • يمكنك استخدام تخطيط واجهة المستخدم من اليمين إلى اليسار للغات التي تُكتب من اليمين إلى اليسار.
  • يتيح لك هذا التقرير معرفة اتجاه البيانات النصية المعروضة داخل الرسائل المنسّقة وتوضيحها. يمكنك عادةً طلب طريقة تحدِّد اتجاه البيانات النصية نيابةً عنك، كما هو موضّح في هذا الدليل.

إنشاء أدلة اللغات وملفات الموارد

لإتاحة المزيد من اللغات، أنشِئ أدلة إضافية داخل res/. يجب أن يتقيد اسم كل دليل بالتنسيق التالي:

<resource type>-b+<language code>[+<country code>]

على سبيل المثال، يحتوي values-b+es/ على موارد سلسلة لللغات التي تحمل رمز اللغة es. وبالمثل، يحتوي mipmap-b+es+ES/ على رموز للغات مع رمز اللغة es ورمز البلد ES.

يحمّل Android الموارد المناسبة وفقًا لإعدادات اللغة للجهاز في وقت التشغيل. لمزيد من المعلومات، يُرجى الاطّلاع على تقديم موارد بديلة.

بعد أن تقرر اللغات التي تريد دعمها، أنشئ الأدلة الفرعية للموارد وملفاتها. مثلاً:

MyProject/
    res/
       values/
           strings.xml
       values-b+es/
           strings.xml
       mipmap/
           country_flag.png
       mipmap-b+es+ES/
           country_flag.png

تعبئة ملفات الموارد بموارد مترجمة. في ما يلي أمثلة على ملفات موارد الصور والسلسلة المترجمة:

السلاسل الإنجليزية (اللغة التلقائية) باللغة /values/strings.xml:

<resources>
    <string name="hello_world">Hello World!</string>
</resources>

السلاسل الإسبانية (لغة es) باللغة /values-b+es/strings.xml:

<resources>
    <string name="hello_world">¡Hola Mundo!</string>
</resources>

رمز علم الولايات المتحدة (اللغة التلقائية) باللغة /mipmap/country_flag.png:

يُعد رمز علم الولايات المتحدة

الشكل 2. الرمز المستخدَم للّغة التلقائية (en_US).

رمز العلم الإسباني (لغة es_ES) باللغة /mipmap-b+es+ES/country_flag.png:

يُعد رمز علم إسبانيا

الشكل 3. الرمز المستخدَم للّغة es_ES

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

استخدام الموارد في تطبيقك

أشِر إلى الموارد في رمز المصدر وملفات XML الأخرى باستخدام سمة name لكل مورد: R.<resource type>.<resource name>. هناك مجموعة متنوعة من الطرق التي تقبل المورد بهذه الطريقة، كما هو موضح في الأمثلة التالية:

Kotlin

// Get a string resource
val hello = resources.getString(R.string.hello_world)

// Or supply a string resource to a method that requires a string
TextView(this).apply {
    setText(R.string.hello_world)
}

Java

// Get a string resource
String hello = getResources().getString(R.string.hello_world);

// Or supply a string resource to a method that requires a string
TextView textView = new TextView(this);
textView.setText(R.string.hello_world);

في ملفات XML، يمكنك الإشارة إلى مورد يتضمّن البنية @<resource type>/<resource name> عندما تقبل سمة XML قيمة متوافقة، كما هو موضّح في المثال التالي:

<ImageView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:src="@mipmap/country_flag" />

ملاحظة: لضمان منح الأولوية لإعدادات اللغة للمستخدِم بشكل صحيح، حدِّد اللغات التي يتيحها تطبيقك باستخدام السمة resConfigs. ولمزيد من المعلومات، يمكنك الاطّلاع على تحديد اللغات التي يتيحها تطبيقك.

تنسيق النص في الرسائل

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

وتتم كتابة اللغات مثل العربية والعبرية والفارسية والأوردية من اليمين إلى اليسار. ومع ذلك، تتم كتابة بعض العناصر، مثل الأرقام ونص LTR المضمن، LTR داخل نص RTL بطريقة أخرى. إنّ اللغات التي تستخدم النصوص البرمجية من اليسار إلى اليمين، بما في ذلك الإنجليزية، تكون ثنائية الاتجاه أيضًا، لأنها قد تحتوي على نصوص من اليمين إلى اليسار (RTL)، ويجب عرضها من اليمين إلى اليسار.

تنشئ التطبيقات غالبًا مثيلات من هذا النوع من النصوص المعاكسة الاتجاه، مثلاً عن طريق إدراج بيانات نصية بلغة عشوائية واتجاه نص عشوائي في الرسائل المترجَمة. ولا يتضمن هذا المزيج من الاتجاهات في كثير من الأحيان مؤشرًا واضحًا لمكان بدء النص في الاتجاه المقابل وانتهائه، لذلك يمكن أن يتسبب النص الذي يتم إنشاؤه من خلال التطبيق في تجربة مستخدم سيئة.

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

  • تم إدراج النص في بداية الرسالة:

    PERSON_NAME يتصل بك

  • النص الذي يبدأ برقم، مثل عنوان أو رقم هاتف:

    987 654-3210

  • النص الذي يبدأ بعلامات ترقيم، مثل رقم الهاتف:

    +19876543210

  • نص ينتهي بعلامة ترقيم:

    هل أنت متأكّد من خيارك؟

  • النص الذي يحتوي على كلا الاتجاهين:

    كلمة TABNPA هي العبرية التي تعني موزة.

مثال

لنفترض أن أحد التطبيقات يحتاج أحيانًا إلى عرض الرسالة "هل تقصد %s؟"، مع إدراج عنوان بدلاً من %s في وقت التشغيل. يتوافق التطبيق مع لغات واجهة مستخدم مختلفة، لذا تأتي الرسالة من مورد خاص بلغة معيّنة وتستخدم اتجاه RTL عند ضبط الجهاز على لغة من اليمين إلى اليسار. على سبيل المثال، بالنسبة إلى واجهة المستخدم العبرية، تظهر الرسالة على النحو التالي:

طلع تشمل كل يوم %s?

ومع ذلك، قد يأتي العنوان المقترَح من قاعدة بيانات لا تتضمن نصًا بلغة اللغة. على سبيل المثال، إذا كان العنوان لمكان في كاليفورنيا، فسيظهر في قاعدة البيانات باستخدام نص باللغة الإنجليزية. إذا أدخلت العنوان " 15 Bay Street, Laurel, CA" في رسالة RTL بدون تقديم أي تلميحات بشأن اتجاه النص، فلن تكون النتيجة متوقَّعة أو صحيحة:

삹 惯 15 Bay Street, Laurel, CA?

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

الشرح والحل

تحدث المشكلة في هذا المثال لأن أداة تنسيق النص لا تحدد أن "15" هو جزء من العنوان، لذلك لا يمكن للنظام تحديد ما إذا كان الرقم "15" جزءًا من نص RTL الذي يأتي قبله أم من نص LTR الذي يأتي بعده.

ولحلّ هذه المسألة، استخدِم الطريقة unicodeWrap() من الفئة BidiFormatter. تكتشف هذه الطريقة اتجاه السلسلة وتلفّها بأحرف تنسيق يونيكود التي تشير إلى ذلك الاتجاه.

ويوضّح مقتطف الرمز التالي كيفية استخدام unicodeWrap():

Kotlin

val mySuggestion = "15 Bay Street, Laurel, CA"
val myBidiFormatter: BidiFormatter = BidiFormatter.getInstance()

// The "did_you_mean" localized string resource includes
// a "%s" placeholder for the suggestion.
String.format(getString(R.string.did_you_mean), myBidiFormatter.unicodeWrap(mySuggestion))

Java

String mySuggestion = "15 Bay Street, Laurel, CA";
BidiFormatter myBidiFormatter = BidiFormatter.getInstance();

// The "did_you_mean" localized string resource includes
// a "%s" placeholder for the suggestion.
String.format(getString(R.string.did_you_mean),
        myBidiFormatter.unicodeWrap(mySuggestion));

نظرًا لأن الرقم "15" يظهر الآن داخل النص الذي تم تعريفه على أنه LTR، يتم عرضه في الموضع الصحيح:

빥 惯 15 Bay Street, Laurel, CA?

استخدِم الأسلوب unicodeWrap() في كل جزء من النص تدرجه في رسالة مترجمة إلا في حال انطباق أي مما يلي:

  • يتم إدراج النص في سلسلة يمكن للأجهزة قراءتها، مثل معرّف موارد منتظم (URI) أو طلب بحث بلغة الاستعلامات البنيوية (SQL).
  • أنت تعرف أن جزء النص قد سبق التفافه بشكل صحيح.

ملاحظة: إذا كان تطبيقك يستهدف الإصدار Android 4.3 (المستوى 18 لواجهة برمجة التطبيقات) أو إصدارات أحدث، استخدِم إصدار BidiFormatter المتوفّر في إطار عمل Android. وفي الحالات الأخرى، يمكنك استخدام إصدار BidiFormatter المتوفّر في "مكتبة الدعم".

تنسيق الأرقام

استخدِم تنسيق السلاسل، وليس استدعاءات الطريقة، لتحويل الأرقام إلى سلاسل في منطق تطبيقك:

Kotlin

var myIntAsString = "$myInt"

Java

String myIntAsString = String.format("%d", myInt);

ويؤدي ذلك إلى تنسيق الأرقام بشكل مناسب للغتك، والتي قد تتضمّن استخدام مجموعة أرقام مختلفة.

عند استخدام String.format() لإنشاء طلب بحث SQL على جهاز تم ضبطه على لغة تستخدم مجموعتها الخاصة من الأرقام، مثل الفارسية ومعظم اللغات العربية، تحدث مشاكل إذا كان أي من معلَمات طلب البحث عبارة عن أرقام. وذلك لأن الرقم منسق بأرقام اللغة، وهذه الأرقام غير صالحة في SQL.

للحفاظ على الأرقام بتنسيق ASCII وإبقاء طلب بحث SQL صالحًا، عليك بدلاً من ذلك استخدام النسخة المحملة بشكل زائد من String.format() التي تتضمّن لغة باعتبارها المعلَمة الأولى. استخدِم وسيطة اللغة Locale.US.

دعم النسخ المطابق للتخطيط

يفضّل المستخدمون الذين يستخدمون النصوص البرمجية من اليمين إلى اليسار استخدام واجهة المستخدم من اليمين إلى اليسار، والتي تتضمّن قوائم محاذية لليمين ونصًا تمت محاذاته لليمين وأسهم للأمام تشير إلى اليسار.

يوضح الشكل 4 التباين بين إصدار LTR للشاشة داخل تطبيق "الإعدادات" ونظيره من اليمين إلى اليسار:

تمت محاذاة منطقة الإشعارات إلى اليمين بالقرب من أعلى اليمين، بالقرب من الزاوية العلوية اليسرى لكل من زر القائمة في شريط التطبيق، بينما محاذاة المحتوى في الجزء الرئيسي من الشاشة إلى اليسار مع عرض من اليسار إلى اليمين، بينما يظهر زر الرجوع بالقرب من أسفل اليمين ويشير إلى اليسار. تمت محاذاة منطقة الإشعارات إلى اليمين بالقرب من الزاوية العلوية اليمنى، وأن يكون زر القائمة في شريط التطبيقات أعلى اليسار، وأن يكون المحتوى في الجزء الرئيسي من الشاشة بمحاذاة المحتوى
الشكل 4. متغيرات LTR وRTL لشاشة الإعدادات

عند إضافة إتاحة RTL إلى التطبيق، يُرجى مراعاة النقاط التالية:

  • لا تتوفّر ميزة النسخ المطابق للنص من اليمين إلى اليسار في التطبيقات إلا في حال استخدامها على أجهزة تعمل بنظام التشغيل Android 4.2 (مستوى واجهة برمجة التطبيقات 17) أو الإصدارات الأحدث. للتعرّف على كيفية إتاحة النسخ المطابق للنص على الأجهزة القديمة، يمكنك الاطّلاع على إتاحة التطبيقات القديمة في هذا الدليل.
  • لاختبار ما إذا كان تطبيقك متوافقًا مع اتجاه النص من اليمين إلى اليسار، اختبِر ذلك باستخدام خيارات المطوّرين كما هو موضّح في هذا الدليل وادعُ الأشخاص الذين يستخدمون النصوص البرمجية من اليمين إلى اليسار لاستخدام تطبيقك.

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

لإجراء نسخ مطابق لتنسيق واجهة المستخدم في تطبيقك بحيث يظهر من اليمين إلى اليسار (RTL) بلغة من اليمين إلى اليسار، أكمِل الخطوات الواردة في الأقسام التالية.

تعديل ملفات الإصدار والبيان

يمكنك تعديل ملف build.gradle وبيان التطبيق ضمن وحدة تطبيقك على النحو التالي:

build.gradle (Module: app)

رائع

android {
    ...
    defaultConfig {
        targetSdkVersion 17 // Or higher
        ...
    }
}

Kotlin

android {
    ...
    defaultConfig {
        targetSdkVersion(17) // Or higher
        ...
    }
}

AndroidManifest.xml

<manifest ... >
    ...
    <application ...
        android:supportsRtl="true">
    </application>
</manifest>

ملاحظة: إذا كان تطبيقك يستهدف الإصدار Android 4.1.1 (المستوى 16 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم، يتم تجاهل السمة android:supportsRtl بالإضافة إلى أي قيم لسمة start وend تظهر في ملفات تنسيق تطبيقك. في هذه الحالة، لا يحدث النسخ المطابق لتخطيط RTL تلقائيًا في تطبيقك.

تعديل الموارد الحالية

يمكنك تحويل left وright إلى start وend، على التوالي، في ملفات موارد التنسيق الحالية. يتيح ذلك لإطار العمل محاذاة عناصر واجهة المستخدم في تطبيقك بناءً على إعدادات اللغة لدى المستخدم.

ملاحظة: قبل تعديل الموارد، تعرَّف على كيفية تقديم الدعم للتطبيقات القديمة أو التطبيقات التي تستهدف الإصدار Android 4.1.1 (المستوى 16 من واجهة برمجة التطبيقات) والإصدارات الأقدم.

لاستخدام إمكانات محاذاة RTL في إطار العمل، عليك تغيير السمات في ملفات التنسيق التي تظهر في الجدول 1.

الجدول 1. السمات التي يمكن استخدامها عندما يتوافق تطبيقك مع توجيهات نصية متعددة

سمة تدعم LTR فقط سمة تدعم من اليسار إلى اليمين (LTR) ومن اليمين إلى اليسار (RTL)
android:gravity="left" android:gravity="start"
android:gravity="right" android:gravity="end"
android:layout_gravity="left" android:layout_gravity="start"
android:layout_gravity="right" android:layout_gravity="end"
android:paddingLeft android:paddingStart
android:paddingRight android:paddingEnd
android:drawableLeft android:drawableStart
android:drawableRight android:drawableEnd
android:layout_alignLeft android:layout_alignStart
android:layout_alignRight android:layout_alignEnd
android:layout_marginLeft android:layout_marginStart
android:layout_marginRight android:layout_marginEnd
android:layout_alignParentLeft android:layout_alignParentStart
android:layout_alignParentRight android:layout_alignParentEnd
android:layout_toLeftOf android:layout_toStartOf
android:layout_toRightOf android:layout_toEndOf

يوضّح الجدول 2 كيفية معالجة النظام لسمات محاذاة واجهة المستخدم استنادًا إلى إصدار حزمة تطوير البرامج (SDK) المستهدَف، وما إذا تم تحديد السمتَين left وright، وما إذا تم تحديد السمتَين start وend.

الجدول 2. سلوك محاذاة عناصر واجهة المستخدم استنادًا إلى إصدار حزمة تطوير البرامج (SDK) المستهدَف والسمات المحدَّدة

هل تستهدف الإصدار 4.2 من نظام التشغيل Android
(المستوى 17 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث؟ 		هل تم تحديد الإدخال لليسار واليمين؟ هل تم تحديد البداية والنهاية؟ النتيجة
نعم نعم نعم يتم استخدام start وend، ما يؤدي إلى إلغاء left وright.
نعم نعم لا يتم استخدام left وright.
نعم لا نعم يتم استخدام start وend.
لا نعم نعم يتم استخدام left وright (يتم تجاهل start وend)
لا نعم لا يتم استخدام left وright.
لا لا نعم يؤدي الضغط على start وend إلى left وright

إضافة مراجع حول الاتجاهات واللغات

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

في نظام التشغيل Android 4.2 (المستوى 17 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكنك استخدام مؤهِّلي الموارد -ldrtl (تنسيق الاتجاه من اليمين إلى اليسار) و-ldltr (تنسيق الاتجاه من اليسار إلى اليمين). للحفاظ على التوافق مع الموارد الحالية، تستخدم الإصدارات القديمة من Android مؤهلات لغة المورد لاستنتاج اتجاه النص الصحيح.

لنفرض أنك تريد إضافة ملف تنسيق محدد يتوافق مع النصوص البرمجية من اليمين إلى اليسار، مثل اللغات العبرية والعربية والفارسية. لإجراء ذلك، أضِف دليل layout-ldrtl/ في دليل res/ على النحو الموضّح في المثال التالي:

res/
    layout/
        main.xml This layout file is loaded by default.
    layout-ldrtl/
        main.xml This layout file is loaded for languages using an
                 RTL text direction, including Arabic, Persian, and Hebrew.

إذا أردت إضافة نسخة معيَّنة من التنسيق المصممة للنص العربي فقط، ستبدو بنية الدليل على النحو التالي:

res/
    layout/
        main.xml This layout file is loaded by default.
    layout-ar/
        main.xml This layout file is loaded for Arabic text.
    layout-ldrtl/
        main.xml This layout file is loaded only for non-Arabic
                 languages that use an RTL text direction.

ملاحظة: يكون للموارد المخصّصة للغة الأولوية على الموارد الخاصة باتجاه التنسيق، والتي لها الأولوية على الموارد التلقائية.

استخدام التطبيقات المصغّرة المتوافقة

بدءًا من الإصدار 4.2 من Android (المستوى 17 من واجهة برمجة التطبيقات)، تتوافق معظم عناصر واجهة المستخدم في إطار العمل مع اتجاه النص من اليمين إلى اليسار تلقائيًا. مع ذلك، لا تتوافق بعض عناصر إطار العمل، مثل ViewPager، مع اتجاه النص من اليمين إلى اليسار.

تتيح التطبيقات المصغّرة على الشاشة الرئيسية اتجاه النص من اليمين إلى اليسار (RTL) ما دامت ملفات البيان المقابلة لها تشمل سمة تحديد السمة android:supportsRtl="true".

تقديم الدعم للتطبيقات القديمة

إذا كان تطبيقك يستهدف الإصدار Android 4.1.1 (المستوى 16 لواجهة برمجة التطبيقات) أو إصدارًا أقدم، عليك تضمين السمتَين left وright بالإضافة إلى start وend.

للتحقق مما إذا كان التنسيق يحتاج إلى استخدام اتجاه النص من اليمين إلى اليسار، استخدِم المنطق التالي:

Kotlin

private fun shouldUseLayoutRtl(): Boolean {
    return if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.JELLY_BEAN_MR1) {
        View.LAYOUT_DIRECTION_RTL == layoutDirection
    } else {
        false
    }
}

Java

private boolean shouldUseLayoutRtl() {
    if (android.os.Build.VERSION.SDK_INT >=
            android.os.Build.VERSION_CODES.JELLY_BEAN_MR1) {
        return View.LAYOUT_DIRECTION_RTL == getLayoutDirection();
    } else {
        return false;
    }
}

ملاحظة: لتجنّب مشاكل التوافق، استخدِم الإصدار 23.0.1 أو إصدارًا أحدث من أدوات إصدار حزمة تطوير البرامج (SDK) لنظام التشغيل Android.

الاختبار باستخدام ميزة "خيارات المطوّرين"

على الأجهزة التي تعمل بنظام التشغيل Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يمكنك تفعيل فرض اتجاه تنسيق RTL في خيارات المطوّرين على الجهاز. يتيح لك هذا الإعداد رؤية النص الذي يستخدم النصوص البرمجية من اليسار إلى اليمين، مثل النص الإنجليزي، في وضع RTL.

تعديل منطق التطبيق

يصف هذا القسم جوانب محددة من منطق تطبيقك ليتم تحديثه عند تكييف تطبيقك للتعامل مع اتجاهات النص المتعددة.

تغييرات الخصائص

لمعالجة تغيير في أي موقع ذي صلة من اليمين إلى اليسار، مثل اتجاه التنسيق أو معلمات التنسيق أو المساحة المتروكة أو اتجاه النص أو محاذاة النص أو الموضع القابل للرسم، يمكنك استخدام onRtlPropertiesChanged() رد الاتصال. تتيح لك معاودة الاتصال هذه الحصول على اتجاه التنسيق الحالي وتعديل كائنات View للنشاط وفقًا لذلك.

المشاهدات

إذا كنت تقوم بإنشاء أداة واجهة مستخدم ليست جزءًا مباشرةً من التسلسل الهرمي لعرض النشاط، مثل مربع حوار أو عنصر واجهة مستخدم يشبه نخب، فعيّن اتجاه التخطيط الصحيح بناءً على السياق. يوضح مقتطف الرمز التالي كيفية إكمال هذه العملية:

Kotlin

val config: Configuration = context.resources.configuration
view.layoutDirection = config.layoutDirection

Java

final Configuration config =
    getContext().getResources().getConfiguration();
view.setLayoutDirection(config.getLayoutDirection());

هناك عدة طرق للفئة View تتطلّب تفكيرًا إضافيًا:

onMeasure()
قد تختلف قياسات العرض بناءً على اتجاه النص.
onLayout()
إذا أنشأت تنفيذ تنسيق خاص بك، ستحتاج إلى طلب الرمز super() في إصدار onLayout() وتعديل المنطق المخصّص للتوافق مع النصوص البرمجية من اليمين إلى اليسار.
onDraw()
في حال تنفيذ طريقة عرض مخصّصة أو إضافة وظائف متقدّمة إلى رسم، يجب تعديل الرمز لإتاحة النصوص البرمجية من اليمين إلى اليسار. استخدِم الرمز التالي لتحديد ما إذا كانت الأداة في وضع RTL:

Kotlin

// On devices running Android 4.1.1 (API level 16) and lower,
// you can call the isLayoutRtl() system method directly.
fun isLayoutRtl(): Boolean = layoutDirection == LAYOUT_DIRECTION_RTL

Java

// On devices running Android 4.1.1 (API level 16) and lower,
// you can call the isLayoutRtl() system method directly.
public boolean isLayoutRtl() {
    return (getLayoutDirection() == LAYOUT_DIRECTION_RTL);
}

قابلة للرسم

إذا كان لديك ملف قابل للرسم يجب عكسه بتنسيق RTL، أكمل إحدى الخطوات التالية استنادًا إلى إصدار Android الذي يعمل على الجهاز:

  • على الأجهزة التي تعمل بنظام التشغيل Android 4.3 (المستوى 18 لواجهة برمجة التطبيقات) والإصدارات الأقدم، أضِف ملفات موارد -ldrtl وحدِّدها.

  • في نظام التشغيل Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكنك استخدام android:autoMirrored="true" عند تحديد العنصر القابل للرسم، ما يتيح للنظام إمكانية معالجة النسخ المطابق لتنسيق RTL.

    ملاحظة: يمكن استخدام السمة android:autoMirrored فقط مع العناصر القابلة للرسم البسيطة التي يكون فيها النسخ المطابق الثنائي الاتجاه ببساطة انعكاسًا بيانيًا لما هو قابل للرسم بالكامل. إذا كان العنصر القابل للرسم يحتوي على عناصر متعددة، أو إذا كان التعبير عن الشكل القابل للرسم يغيّر تفسيره، يمكنك إجراء النسخ المطابق بنفسك. كلّما أمكن، تواصَل مع خبير ثنائي الاتجاه لتحديد ما إذا كانت رسوماتك القابلة للرسم على المرآة منطقية للمستخدمين.

الجاذبية

إذا كان رمز تنسيق التطبيق يستخدم السمة Gravity.LEFT أو السمة Gravity.RIGHT، يجب تغيير هاتين القيمتين إلى Gravity.START وGravity.END على التوالي.

إذا كان لديك رمز لغة البرمجة Kotlin أو رمز Java يعتمد على السمتَين Gravity.LEFT أو Gravity.RIGHT، يمكنك تعديله للتوافق مع هذا التغيير من خلال ضبط absoluteGravity لمطابقة layoutDirection.

على سبيل المثال، إذا كنت تستخدم الرمز التالي:

Kotlin

when (gravity and Gravity.HORIZONTAL_GRAVITY_MASK) {
    Gravity.LEFT -> {
        // Handle objects that are left-aligned.
    }
    Gravity.RIGHT -> {
        // Handle objects that are right-aligned.
    }
}

Java

switch (gravity & Gravity.HORIZONTAL_GRAVITY_MASK) {
    case Gravity.LEFT:
        // Handle objects that are left-aligned.
        break;
    case Gravity.RIGHT:
        // Handle objects that are right-aligned.
        break;
}

قم بتغييره إلى ما يلي:

Kotlin

val absoluteGravity: Int = Gravity.getAbsoluteGravity(gravity, layoutDirection)
when (absoluteGravity and Gravity.HORIZONTAL_GRAVITY_MASK) {
    Gravity.LEFT -> {
        // Handle objects that are left-aligned.
    }
    Gravity.RIGHT -> {
        // Handle objects that are right-aligned.
    }
}

Java

final int layoutDirection = getLayoutDirection();
final int absoluteGravity =
        Gravity.getAbsoluteGravity(gravity, layoutDirection);
switch (absoluteGravity & Gravity.HORIZONTAL_GRAVITY_MASK) {
    case Gravity.LEFT:
        // Handle objects that are left-aligned.
        break;
    case Gravity.RIGHT:
        // Handle objects that are right-aligned.
        break;
}

وهذا يعني أنه يمكنك الاحتفاظ بالرمز البرمجي الحالي الذي يعالج قيم المحاذاة إلى اليسار والمحاذاة إلى اليمين، حتى إذا كنت تستخدم start وend لقيم الجاذبية لديك.

ملاحظة: عند تطبيق إعدادات الجاذبية، استخدم إصدارًا تحميلاً زائدًا من Gravity.apply() يتضمن وسيطة layoutDirection.

الهوامش والمساحة المتروكة

لإتاحة النصوص البرمجية من اليمين إلى اليسار في تطبيقك، اتّبِع أفضل الممارسات التالية المتعلّقة بقيم الهوامش والمساحة المتروكة:

  • ويمكنك استخدام getMarginStart() وgetMarginEnd() بدلاً من السمات المكافئة للاتجاهات leftMargin وrightMargin.
  • عند استخدام setMargins()، يمكنك تبديل قيم الوسيطات left وright إذا رصد تطبيقك نصوصًا مكتوبة من اليمين إلى اليسار.
  • إذا كان تطبيقك يتضمّن منطقًا مخصصًا للمساحة المتروكة، يمكنك إلغاء setPadding() وsetPaddingRelative().

إتاحة إعدادات اللغة المخصّصة حسب التطبيقات

في كثير من الحالات، يحدِّد المستخدمون متعددو اللغات لغة واحدة للنظام، مثل الإنجليزية، لكنّهم يريدون اختيار لغات أخرى لتطبيقات معيّنة، مثل الهولندية أو الصينية أو الهندية. لمساعدة التطبيقات في توفير تجربة أفضل لهؤلاء المستخدمين، يقدّم نظام التشغيل Android 13 الميزات التالية للتطبيقات التي تتوافق مع لغات متعددة:

  • إعدادات النظام: موقع مركزي يمكن للمستخدمين من خلاله اختيار لغة مفضّلة لكل تطبيق.

    يجب أن يذكر تطبيقك السمة android:localeConfig في ملف البيان لإعلام النظام بأنّه يتيح استخدام عدة لغات. لمعرفة مزيد من المعلومات، يمكنك الاطّلاع على تعليمات إنشاء ملف موارد والإعلان عنه في ملف بيان التطبيق.

  • واجهات برمجة التطبيقات الإضافية: تسمح واجهات برمجة التطبيقات المتاحة للجميع هذه، مثل طريقتَي l10n-placeholder1">setApplicationLocales() وl10n-placeholder2">getApplicationLocales() في LocaleManager، للتطبيقات بضبط لغة مختلفة عن لغة النظام في وقت التشغيل.

    يمكن للتطبيقات التي تستخدم أدوات اختيار اللغة داخل التطبيقات استخدام واجهات برمجة التطبيقات هذه لمنح المستخدمين تجربة مستخدم متسقة بغض النظر عن المكان الذي يختارون فيه إعدادات اللغة المفضّلة. تساعدك واجهات برمجة التطبيقات العامة أيضًا في تقليل مقدار الرموز النموذجية، كما أنّها تتوافق مع حِزم APK المقسّمة. وتتيح أيضًا ميزة التحميل التلقائي للتطبيقات لتخزين إعدادات اللغة الخاصة بالمستخدم على مستوى التطبيقات.

    للتوافق مع الأنظمة القديمة مع إصدارات Android السابقة، تتوفّر أيضًا واجهات برمجة تطبيقات مكافئة في AndroidX. ننصحك باستخدام Appcompat 1.6.0-beta01 أو الإصدارات الأحدث.

    لمزيد من المعلومات، يمكنك الاطّلاع على تعليمات تنفيذ واجهات برمجة التطبيقات الجديدة.

راجع أيضًا

مراجع إضافية

للتعرُّف على المزيد من المعلومات عن التوافق مع الأجهزة القديمة، يمكنك الاطّلاع على المراجع التالية:

مشاركات المدونة

السابق
إنشاء حِزم APK متعدّدة بسمات متعدّدة
التالي
إتاحة إصدارات مختلفة من النظام الأساسي