لإعادة تسمية مفتاح في كتالوج السلاسل في Xcode، احتفِظ برسالة المصدر على نحو منفصل، وحدّث مراجعها في الشيفرة، وتحقّق من كل ترجمة ومتغير موجود. بالنسبة إلى السلاسل المستخرجة، يوفّر Xcode 26 إعادة هيكلة للتحويل؛ ولا يكفي تغيير مفتاح البحث وحده.

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

ما الذي يجب أن يبقى دون تغيير عند تعديل المفتاح؟

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

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

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

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

اعثر على المصدر قبل تعديل الكتالوج

افتح الكتالوج الموجود في مستعرض المشاريع في Xcode. اختر Editor > Assistant، ثم حدّد المُدخل لفحص مصدره. وتوثّق Apple أيضًا أن السهم بجانب المفتاح وأمثلة الاستخدام في مفتش السمات يساعدان في تحديد المراجع. بالنسبة إلى السلاسل المستخرجة، اختر Product > Build بعد تغييرات المصدر لمزامنة الكتالوج. توطين النص وتغيير صيغته باستخدام كتالوج السلاسل

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

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

استخدم إعادة هيكلة التحويل في Xcode للسلاسل المستخرجة

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

  1. في إعدادات البناء، تحقّق من أن Generate String Catalog Symbols مضبوطة على Yes إذا كان المشروع الحالي يحتاج إلى تفعيلها.
  2. في محرر الكتالوج، حدّد المفتاح الموجود، وانقر عليه مع الضغط على Control، واختر Refactor > Convert Strings to Symbols.
  3. افحص المعاينة التي تعرض تغيير مفتاح الكتالوج ومواضع المصدر المتأثرة.
  4. عدّل الاسم الدلالي المقترح، وأسماء الوسيطات عند الاقتضاء، في واجهة التحويل.
  5. قارن الشيفرة الحالية والمعدّلة باستخدام المعاينة المظللة، ثم انقر على Convert.
  6. أنشئ البناء وقارن المُدخل الناتج بنقطة الحفظ، بما في ذلك الترجمات والمتغيرات.

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

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

أبقِ الاستخراج مفعّلًا إذا كنت تفضّل المفاتيح والقيم الافتراضية في الشيفرة

يمكنك أيضًا الإبقاء على الاستخراج المُدار بالشيفرة. تدعم Apple صراحةً استخدام مفاتيح البحث ورسائل المصدر المنفصلة عبر String(localized:defaultValue:...): إذ توفّر الوسيطة الأولى المفتاح، وتوفّر defaultValue سلسلة المصدر. مثلًا، يمكن لمفتاح دلالي أن يحتفظ بـ Open collection بوصفها الرسالة الافتراضية. إعداد نص تطبيقك للترجمة

يوضّح مصدر التطبيق الكامل التالي هذا النمط باستخدام تسمية ثابتة واحدة وعدد صحيح واحد. استخدم هدف تطبيق macOS بـ SwiftUI، واجعل الحد الأدنى للإصدار المستهدف macOS 12 أو أحدث، واستبدل مصدر إدخال التطبيق الموجود بدلًا من إضافة تصريح @main ثانٍ. أضف Localizable.xcstrings إلى هدف التطبيق. فُحص المثال وفق واجهات Apple، لكنه لم يُصرّف هنا لعدم توفر سلسلة أدوات Swift.

import Foundation
import SwiftUI

@main
struct CatalogRenameDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogRenameDemoView()
        }
    }
}

struct CatalogRenameDemoView: View {
    private let itemCount: Int = 7

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(verbatim: String(
                localized: "collection.open",
                defaultValue: "Open collection",
                comment: "Label for opening the selected collection."
            ))

            Text(verbatim: String(
                localized: "collection.itemCount",
                defaultValue: "\(itemCount) items",
                comment: "Number of items in the selected collection."
            ))
        }
        .padding()
    }
}

هنا، تحل String(localized:...) النص الموطّن قبل عرض السلسلة الناتجة. وتُظهر Text(verbatim:) خطوة العرض بوضوح. تميّز Apple بين توطين السلسلة فورًا وLocalizedStringResource، الذي يمثّل عملية بحث يمكن تأجيلها. توصي Apple بنوع قابل للتوطين مثل LocalizedStringResource للواجهات القابلة لإعادة الاستخدام التي تمرر رسائل غير محلولة بين المشاهد. LocalizedStringResource، إعداد نص تطبيقك للترجمة

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

ما الفرق بين الاستخراج والتنسيق وقت التشغيل؟

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

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

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

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

تحقّق من بقاء المحتوى قبل إزالة المُدخل القديم

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

الفحص النتيجة المتوقعة ما ينبغي التحقق منه عند الإخفاق
نص المصدر يطابق نقطة الحفظ قيمة افتراضية مفقودة أو معدّلة
الترجمات الموجودة تظل كل القيم السابقة متاحة تحت المفتاح الجديد نقل غير مكتمل أو وجهة خاطئة
بنية المتغيرات تبقى جميع فروع الجمع والجهاز السابقة نُسخت القيمة الأعلى مستوى فقط
تسمية وقت التشغيل تعرض الرسالة المقصودة عدم تطابق المفتاح أو الجدول أو الحزمة أو التوطين
الأعداد الاصطناعية 0 و1 و7 تُدرج القيم على النحو الصحيح وتعمل فروع الجمع المطلوبة عدم تطابق الوسيطة أو المتغير
المراجع القديمة لا يبقى أي استخدام مطلوب ترحيل غير مكتمل

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

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

المصادر