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

المهمة محدودة عمدًا: عرض عنوان نافذة وملخص يتضمن عددين صحيحين. جميع التسميات والقيم اصطناعية. ستنشئ عقد الفهرس، وتربطه بـ SwiftUI، وتتحقق من تشخيصات المترجم والمخرجات الظاهرة.

ما الذي يجعل واجهة الوصول الخاصة بالتوطين مُتحقَّقًا منها وقت الترجمة؟

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

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

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

إعداد تطبيق Mac صغير وعقد رسائله

استخدم Xcode 26 أو إصدارًا أحدث وهدف تطبيق macOS يستخدم SwiftUI. في هذا المثال، اضبط هدف النشر على macOS 15 أو إصدار أحدث. يتوفر النوع الأساسي LocalizedStringResource بدءًا من macOS 13؛ واختيار الهدف الأعلى في المثال شرط مسبق اختياري، وليس الحد الأدنى لإصدار هذا النوع. يمثل المورد نصًا قابلًا للتوطين يمكن تأجيل البحث عنه إلى حين الحاجة إليه. LocalizedStringResource

أضف فهرسًا عبر File > New > File from Template. اختر String Catalog ضمن Resource، وسمّه Workbench، وأدرجه في هدف التطبيق. توضح Apple أن كل فهرس يمثل جدولًا؛ واستخدام جدول منفصل هنا يجمع رسالتي المثال. توطين النص وتغييره باستخدام فهرس السلاسل

في محرر المشروع، افتح Build Settings، وابحث عن Generate String، واضبط Generate String Catalog Symbols على Yes للإعداد الفعلي للهدف. هذا هو المفتاح الموثق للمشاريع الأقدم. استخدام الرموز القابلة للتوطين المُنشأة في التعليمات البرمجية

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

المفتاح قيمة المصدر بالإنجليزية التعليق
TITLE Selection overview Heading above the selection summary.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Selection summary. selectedCount is the number selected; availableCount is the total number available, including selected items.

بالنسبة إلى SUBTITLE، يمكنك إدخال كل عنصر نائب عبر قائمة الإكمال في Xcode: اكتب %، واختر العنصر النائب الصحيح، وسمّه selectedCount أو availableCount. توثق Apple المتغيرات المسماة والمعلمات المُنشأة لمحددات التنسيق هذه. حدد كل إدخال وافحص Generate Swift Symbol وExample Usages في مفتش السمات. استخدام الرموز القابلة للتوطين المُنشأة في التعليمات البرمجية

العقد المقصود هو خاصية للعنوان ودالة للعنوان الفرعي تقبل قيمتين من النوع Int. تحقق من التهجئة المُنشأة فعليًا في المفتش قبل المتابعة: تذكر Apple أن أسماء الرموز تستخدم المفتاح والقيمة معًا. تستخدم الأمثلة أدناه .Workbench.title و.Workbench.subtitle(selectedCount:availableCount:)، وفق نمط المفتاح المكتوب بأحرف كبيرة الذي توثقه Apple. تطبيق عملي: استكشاف التوطين باستخدام Xcode

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

استخدام واجهات الوصول المُنشأة في نافذة كاملة

بعد إنشاء الفهرس، اختر Product > Build. استبدل تعريف التطبيق وعرض المحتوى في القالب بالبرنامج التالي، مع الإبقاء على تصريح واحد فقط لـ @main في الهدف. الفهرس مورد مطلوب لهذا البرنامج؛ ولن يؤدي لصق Swift في ملف مستقل إلى إنشاء واجهات الوصول الخاصة به.

import Foundation
import SwiftUI

@main
struct SelectionOverviewApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionOverviewView(
                selectedCount: 3,
                availableCount: 12
            )
        }
    }
}

struct SelectionOverviewView: View {
    let selectedCount: Int
    let availableCount: Int

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(.Workbench.title)
                .font(.title2)

            Text(
                .Workbench.subtitle(
                    selectedCount: selectedCount,
                    availableCount: availableCount
                )
            )
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 140)
    }
}

عند تفعيل التوطين المصدر باللغة الإنجليزية، ينبغي أن تعرض المدخلات التوضيحية Selection overview متبوعًا بـ 3 selected; 12 available. الأعداد ثابتة كي تتمكن من التحقق من مواضع الوسائط من دون إضافة تعليمات برمجية لإدارة التحديد.

توثق Apple إمكانية استخدام الموارد المُنشأة في SwiftUI، بما في ذلك Text، ومن خلال مُهيّئ Foundation String(localized:). إذا كانت واجهة Mac الحالية تتطلب String محلولًا، فحوّل المورد المُنشأ عند تلك الحدود. تطبيق عملي: استكشاف التوطين باستخدام Xcode

على سبيل المثال، هذه دالة مساعدة كاملة يمكنك إضافتها إلى هدف التطبيق نفسه بعد إنشاء الفهرس:

import Foundation

func selectionSummary(
    selectedCount: Int,
    availableCount: Int
) -> String {
    String(
        localized: .Workbench.subtitle(
            selectedCount: selectedCount,
            availableCount: availableCount
        )
    )
}

إن إعادة LocalizedStringResource من واجهتك الخاصة تحفظ المورد لإجراء البحث لاحقًا؛ أما إعادة String فتحلّه عند تشغيل المُهيّئ. اختر وفقًا لما تحتاج إليه الواجهة المستقبلة. تصف وثائق Foundation من Apple هذا التمييز بين البحث المؤجل والفوري. LocalizedStringResource

تمت مراجعة الأمثلة بالاستناد إلى الوثائق التي جرى استرجاعها. ولم تُترجم هنا لأن البيئة المتاحة لا تتضمن Swift أو Xcode قابلًا للتنفيذ.

لماذا تهم النقطة في البداية وتسميات الوسائط؟

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

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

تندرج التسميتان selectedCount: وavailableCount: ضمن استدعاء الدالة. يميز Swift بين تسميات الوسائط التي تظهر في موضع الاستدعاء وأسماء المعلمات المستخدمة داخل الدالة. عندما تتطلب المعلمة تسمية، يجب على المستدعي تقديمها. الدوال — تسميات وسائط الدوال وأسماء المعلمات

تساعد التسميات الواضحة على تجنب الأخطاء، لكن نوع الوسيطين هنا واحد. ويظل تبديل القيمتين الصحيحتين صالحًا في Swift. لذلك يكمل عقد الرسالة والتحقق من المخرجات الظاهرة عمل المترجم.

ترحيل المفاتيح الحالية مع الحفاظ على معناها

توفر Apple سير عمل لإعادة الهيكلة للسلاسل القابلة للتوطين الحالية. حدد الإدخالات في فهرس السلاسل، وانقر عليها مع الضغط على Control، واختر Refactor > Convert Strings to Symbols. افحص المعاينة، وعدّل أسماء الرموز أو المعلمات المقترحة عند الحاجة، ثم اختر Convert. استخدام الرموز القابلة للتوطين المُنشأة في التعليمات البرمجية

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

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

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

التحقق من الترحيل بتسلسل تشخيصي صغير

استخدم الفحوص التالية على نافذة العينة. فهي تفصل بين حماية المترجم وصحة الرسالة وتكامل الموارد.

  1. أنشئ المثال دون تغيير للتأكد من وجود خط أساس يعمل.
  2. أخطئ مؤقتًا في كتابة عضو العنوان وأنشئ التطبيق. ينبغي أن يؤدي العضو غير الموجود إلى تشخيص من المترجم. ثم أعده إلى صيغته الصحيحة.
  3. مرّر مؤقتًا قيمة من نوع String حيث يتطلب العنوان الفرعي قيمة من نوع Int. أنشئ التطبيق للتحقق من عدم تطابق النوع، ثم أعد القيمة الصحيحة.
  4. شغّل التطبيق مع ضبط selectedCount على 3 وضبط availableCount على 12. تحقق من ظهور الأرقام في مواضعها المقصودة.
  5. غيّر قيمة عنوان الفهرس وحدها إلى Current selection، وأعد إنشاء التطبيق، وتحقق من العنوان المعروض. تأكد من بقاء التوقيع المُنشأ هو نفسه الذي تستخدمه تعليماتك البرمجية.

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

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

لإجراء فحص مبكر للتخطيط، يوفر Xcode أيضًا Double-Length Pseudolanguage، الذي يطيل النص القابل للتوطين لكشف مشكلات القياس. افحص الملخص عند عرض نافذة ضيق؛ فالترجمة الناجحة لا تثبت أن النص يتسع. اختبار التوطينات

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

المصادر