لإزالة مفاتيح التعريب غير المستخدمة في Xcode، تعامل مع إدخالات Stale كمرشحين للمراجعة. تحقّق من بناء المفتاح في وقت التشغيل قبل الحذف، احتفظ بالرسائل الديناميكية المطلوبة كإدارات يدوية، واختبر شاشات تطبيق Mac المتأثرة بعد التنظيف.

هذا الدليل لمطوّر يحافظ على تطبيق SwiftUI لـ Mac مع كتالوجات السلاسل (String Catalogs). المهمة هي تنظيف كتالوج واحد: تحديد الرسائل التي يمكن إزالتها مع الحفاظ على التسميات ورسائل العد التي يعرضها التطبيق فعلياً. يفصل جدول اتخاذ القرار أدناه أدلة الاستخراج عن سلوك وقت التشغيل.

ماذا يعني مفتاح تعريب Stale فعلياً؟

يكتشف Xcode السلاسل القابلة للتعريب أثناء عمليات البناء. تشرح Apple أن الاستخراج يغطي المخطط (scheme) والمنصة الحالية. عندما تختفي سلسلة مستخرجة سابقاً، يمكن لـ Xcode إزالة إدخال غير مترجم تلقائياً؛ بينما يبقى الإدخال الذي يحتوي على ترجمات ويحصل على حالة Stale. تعني هذه الحالة أن Xcode لم يعثر على السلسلة في الكود بعد الآن. تجعل Apple الحذف مشروطاً بتأكيد أن السلسلة لم تعد مطلوبة. اكتشف كتالوجات السلاسل

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

استخدم جدول المراجعة المقترح أدناه لكل مرشح. إنه أداة قرار مشتقة من حدود الاستخراج الموثقة، وليست ميزة إضافية في Xcode.

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

كيف تؤسس أساساً مفيداً في Xcode؟

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

اختر الكتالوج في متصفح المشروع (Project navigator) واختر Product > Build. توثق Apple أن عمليات البناء تملأ كتالوجات السلاسل وتحدّثها من النص المصدري القابل للتعريب. مع تحديد الكتالوج، اختر Editor > Assistant، ثم اختر مفتاحاً لفحص موقعه المصدري. يوفّر الكتالوج أيضاً التنقل العكسي إلى المصدر. تعريب النصوص وتنويعها باستخدام كتالوج السلاسل

إذا كانت سلاسل Swift المتوقعة مفقودة، تحقّق من تمكين إعداد البناء Use Compiler to Extract Swift Strings للهدف. توثق Apple هذا كشرط مسبق لاستخراج المترجم. كتالوج مملوء باستخراج غير مكتمل أساس ضعيف لاتخاذ قرار ما يجب إزالته. عرّب تطبيق SwiftUI الخاص بك

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

لا تدمج القرارات لمجرد أن إدخالين يعرضان نفس النص. تقبل واجهات برمجة تطبيقات تعريب Apple أسماء الجداول، ويمكن للموارد خارج التطبيق الرئيسي أن تتطلب حزمة مختلفة (bundle). تتبّع جدول البحث والحزمة قبل التعامل مع إدخال آخر كبديل. إعداد نصوص تطبيقك للترجمة

كيف تحافظ على الرسائل المشار إليها ديناميكياً؟

توثّق Apple الإدارة اليدوية خصيصاً للسلاسل التي يتم بناء مفاتيحها ديناميكياً. اختر الإدخال المطلوب واستخدم المفتش (inspector) الخاص به لجعله مُداراً يدوياً. لا يتم تحديث هذه الإدخالات أو إزالتها بواسطة مزامنة التعريب بعد البناء في Xcode. لإدخال ديناميكي مفقود، توضح Apple أيضاً إضافة سلسلة يدوية باستخدام زر زائد الكتالوج. اكتشف كتالوجات السلاسل

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

تحقّق مما إذا كان SwiftUI يؤدي عملية بحث فعلياً

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

التطبيق التجريبي الكامل التالي يحتفظ بمفتاح مختار في وقت التشغيل منفصلاً عن عد مُدرَج. في مشروع تطبيق SwiftUI لـ Mac يمكن التخلص منه يستخدم Xcode 15 أو أحدث وهدف نشر macOS 13، استبدل تعريف التطبيق المولّد بهذا الكود. احتفظ بإعلان @main واحد فقط. تم فحصه مقابل واجهات API الموثقة؛ لم يتم تجميعه هنا لأن سلسلة أدوات Swift لم تكن متاحة.

import SwiftUI

@main
struct CatalogReviewDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogReviewView()
        }
    }
}

struct CatalogReviewView: View {
    @State private var compact = true
    @State private var itemCount = 2

    private var selectedKey: String {
        "panel." + (compact ? "compact" : "expanded")
    }

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Toggle("Compact layout", isOn: $compact)

            Text(LocalizedStringKey(selectedKey))

            Text("\(itemCount) items",
                 comment: "Number of items in the sample panel.")

            Button("Add item") {
                itemCount += 1
            }
        }
        .padding()
        .frame(minWidth: 320)
    }
}

أضف Localizable.xcstrings إلى هدف التطبيق. أضف إدخالات مُدارة يدوياً لـ panel.compact و panel.expanded، مع قيم مصدر Compact panel و Expanded panel. ابنِ المشروع لاستخراج الرسائل الحرفية. التحويل الصريح لـ LocalizedStringKey يطلب بحثاً في وقت التشغيل؛ إنه لا يزوّد المستخرج بإعلان حرفي لكل مفتاح مبني محتملاً.

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

لماذا تختلف العدادات المتغيرة عن المفاتيح المتغيرة؟

في التجريبي، يؤدي اختيار تخطيط إلى تغيير مفتاح الرسالة الذي يبحث عنه التطبيق. تغيير itemCount يزوّد وسيطاً مختلفاً لرسالة قابلة للتعريب واحدة. تحول التداخل (interpolation) في SwiftUI القيم المضمنة إلى مواضع تنسيق للتعريب؛ يزوّد العرض في وقت التشغيل قيمها. عرّب تطبيق SwiftUI الخاص بك

لذلك لا تحتاج إلى مفاتيح منفصلة للتصييرات 2 items و 3 items و 4 items. ابنِ المثال، اعثر على رسالة العد المستخرجة، اضغط Control على مفتاحها واختر Vary by Plural. لتعريب مصدر إنجليزي، أدخل %lld item لـ One و %lld items لـ Other، باستخدام العنصر النائب للعدد الصحيح الذي يعرضه Xcode. توثق Apple سير عمل رسائل العد وإضافة متغيرات الجمع المناسبة للغات المدعومة الأخرى. تعريب النصوص وتنويعها باستخدام كتالوج السلاسل

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

أي إدخالات يجب أن يزيلها التنظيف فعلياً؟

ضع في اعتبارك مراجعة توضيحية لـ 24 مرشحاً. تصف هذه الأرقام مثالاً اصطناعياً، وليس نتيجة مشروع مقاسة.

نتيجة المراجعة الإدخالات الإجراء
المستهلكون الوحيدون انتموا إلى لوحة مزالة 9 احذف بعد تأكيد زوال اللوحة وبيانات بحثها
المفاتيح لا تزال قابلة للوصول من خلال الاختيار في وقت التشغيل 8 احتفظ ووثّق الإدارة اليدوية
المراجع تنتمي لهدف آخر أو بناء شرطي 5 احتفظ وتحقّق من نطاق البناء ذاك
أصل المفتاح لا يزال غير محلول 2 احتفظ بانتظار التحقيق
إجمالي ما تمت مراجعته 24 9 مرشحين للحذف

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

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

كيف تتحقّق من الرسائل المحتفظ بها على جهاز Mac؟

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

اختبر كل اختيار ديناميكي مسموح، بما في ذلك التخطيطين في التجريبي. تأكد من أن التطبيق يعرض قيم الكتالوج المتوقعة بدلاً من المعرّفات. لرسائل العد، تحقّق من قيم تركيبية مثل 0، 1، 2، و 12، وتحقّق من فئات جمع إضافية حيث تتطلب تعريباتك المدعومة ذلك. تغيير العد الأولي في العينة كافٍ للوصول إلى قيم الاختبار تلك.

عندما تعرض رسالة محتفَظ بها بشكل غير صحيح، افحص المفتاح الدقيق، والجدول، والحزمة (bundle)، و Text initializer قبل تغيير الكتالوج. يمكن أن يجعل سير عمل الرموز المولّدة الأحدث من Apple الموارد اليدوية أسهل في الإشارة: قدمت Xcode 26 توليد رموز كتالوج السلاسل (String Catalog symbol generation)، مفعلة للمشاريع الموجودة عبر Generate String Catalog Symbols. هذا مسار إعادة هيكلة اختياري، وليس دليلاً على أن مورداً يدوياً غير مُشار إليه غير مستخدم. جلسة برمجة: استكشف التعريب مع Xcode

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

المصادر