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

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

حدّد ما يُعدّ رسالة مكتملة

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

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

اقرأ التوطينات المدعومة للمشروع في محرر المشروع: حدّد المشروع ضمن Project، وافتح Info، ثم افحص Localizations. وافحص أيضًا الموارد التي تشارك في هذه التوطينات. يشرح إضافة دعم اللغات والمناطق من Apple إعدادات المشروع واختيارات الموارد هذه.

يمكنك استخدام أسماء مستعارة افتراضية في ورقة العمل، مثل Localization A وLocalization B وLocalization C. احتفظ بربطها بمعرّفات التوطين الفعلية للمشروع في سجل عملك. هذه الأسماء المستعارة تسميات لورقة العمل، وليست قيمًا تُدخلها في Xcode.

استخدم معايير الاكتمال التالية للتدقيق. هذه طريقة مراجعة مقترحة وليست حالة اكتمال تحددها Apple.

الفحص الأدلة المطلوب تسجيلها
الجرد للرسالة هدف وحزمة وجدول ومفتاح محددة.
الاكتشاف استُخرجت الرسالة من الشيفرة أو تتم صيانتها يدويًا عن قصد.
التغطية لكل توطين مطلوب متغيرات الرسالة اللازمة.
الوسائط تحتفظ كل وسيطة بمعناها المقصود ونوعها المتوافق.
وقت التشغيل تظهر الرسالة والقيم الصحيحة في واجهة Mac ذات الصلة.
المعالجة عولجت كل نتيجة، أو استُبعدت عمدًا مع ذكر السبب، أو ما زالت مفتوحة.

أنشئ جرد الكتالوج قبل مراجعة الترجمات

افتح كتالوجات السلاسل النصية الموجودة في المشروع. إذا لم يكن للهدف كتالوج، فمسار الإنشاء الذي توثقه Apple هو File > New > File from Template، ثم اختيار String Catalog. الاسم الافتراضي هو Localizable؛ استخدم اسم الجدول الذي تتوقعه شيفرتك. اختر Product > Build لملء الكتالوج وتحديثه. راجع توطين النصوص وتنويعها باستخدام كتالوج سلاسل نصية.

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

تحقق من إعداد البناء Use Compiler to Extract Swift Strings. تشترط Apple صراحةً تفعيله لإدراج كل نصوص Swift القابلة للتوطين في عمليات تصدير التوطين. إذا احتجت إلى نسخة للتبادل بغرض الترجمة، فحدّد المشروع واختر Product > Export Localizations، ثم اختر التوطينات المطلوبة. حزمة .xcloc المصدّرة هي كتالوج توطين Xcode، وهي مختلفة عن جدول سلاسل نصية منفرد بامتداد .xcstrings. راجع تصدير التوطينات.

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

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

افصل بين الاستخراج والبحث والتنسيق وقت التشغيل

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

في SwiftUI، تهم أنواع الوسائط. فالقيمة الحرفية مثل Text("Open collection") تدخل في البحث عن النص الموطّن. أما تمرير متغير من نوع String إلى المُهيئ المقابل فيعرض ذلك المتغير عادةً من دون توطين. توثّق Apple هذا الفرق في LocalizedStringKey.

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

للاستيفاء أيضًا دور على مستوى الرسالة. يستطيع SwiftUI البحث عن رسالة موطّنة تتضمن محدد تنسيق، ثم إدراج القيمة المستوفاة قبل العرض. توصي Apple بالاستيفاء لتركيب نصوص قابلة للتوطين في توثيق Text.

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

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

راجع كل لغة وكل متغير مطلوب

اعمل على جدول واحد في كل مرة، وتوطين واحد في كل مرة. لكل رسالة، افحص حالة الترجمة والنص والوسائط والتنوعات الموسّعة. اترك الصفوف غير المكتملة مفتوحة حتى لو اكتملت الرسائل المحيطة بها.

يميّز سير عمل الكتالوج لدى Apple بين New وNeeds Review والإدخالات المترجمة والسلاسل النصية Stale. لم تعد السلسلة النصية القديمة تظهر في الشيفرة؛ أما الإدخالات التي تُدار يدويًا فلا تُحدّث أو تُحذف تلقائيًا أثناء المزامنة. تأكد من أن المفتاح القديم غير ضروري قبل حذف ترجماته. راجع اكتشاف كتالوجات السلاسل النصية.

بالنسبة إلى الرسائل التي تعتمد على العدد، انقر مع الضغط على Control على المفتاح المستوفى واختر Vary by Plural. راجع كل صيغة يوفرها Xcode لكل توطين. قد تختلف الصيغ المطلوبة، لذا فإن مطابقة عدد صفوف توطين المصدر ليست فحصًا كافيًا. إذا تضمن الكتالوج تنويعات للأجهزة، فافحص قيمة Mac والقيمة العامة. توثّق Apple كلا الخيارين في توطين النصوص وتنويعها باستخدام كتالوج سلاسل نصية.

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

أضف سياقًا عندما تكون التسمية القصيرة ملتبسة. يمكن أن يوضح تعليق على Open أنها إجراء يُطبّق على صف مجموعة. تحمل وسيطة SwiftUI comment هذا السياق إلى مخرجات التوطين؛ وتصفها Apple في إعداد الواجهات للتوطين.

استخدم مصفوفة تغطية تكشف العمل غير المكتمل

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

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

التوطين الأزواج المطلوبة فحوص الكتالوج المكتملة فحوص وقت التشغيل المكتملة
Localization A 48 48 48
Localization B 48 46 44
Localization C 48 48 45
الإجمالي 144 142 137

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

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

شغّل تطبيق Mac بكل توطين مدعوم

استخدم إعدادات مخطط Xcode لإجراء فحوص متكررة على مستوى التطبيق. اختر Product > Scheme > Edit Scheme، وحدد Run، وافتح Options، ثم اختر App Language وApp Region. أغلق مربع الحوار، واختر وجهة تشغيل Mac، ثم شغّل التطبيق. كرر ذلك للتركيبات المدعومة في تدقيقك. توثّق Apple هذه الخطوات في اختبار التوطينات عند تشغيل تطبيقك.

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

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

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

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

المصادر