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

ما الذي ينبغي أن يوضحه تعليق المترجم؟

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

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

استخدم هذا الدليل الكتابي المؤلف من أربعة أجزاء. فهو منهج تحريري مستمد من إرشادات Apple، وليس تنسيقًا إلزاميًا لتعليقات Apple:

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

أدرج فقط الأجزاء التي تؤثر في التفسير. لا يحتاج العنوان الثابت إلى شرح إجراء. أما الزر فيستفيد من توضيح ما يفعله النقر عليه. وتحتاج الرسالة التي تتضمن اسمين مُدرجين إلى بيان العلاقة بينهما.

تنصح Apple تحديدًا بشرح عنصر الواجهة والواجهة المحيطة به والمحتوى الذي تمثله العناصر النائبة. تعامل مع هذه التفاصيل بوصفها سياقًا عمليًا للترجمة. تطبيق عملي: استكشاف التوطين باستخدام Xcode

حوّل التعليقات المبهمة إلى أوصاف مفيدة للرسائل

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

التسمية المصدرية تعليق ضعيف تعليق أكثر فائدة
Shapes تسمية للأشكال. عنصر تنقل في الشريط الجانبي يفتح قائمة الأشكال الهندسية. اسم جمع.
Round نص عن شكل. عنوان فئة يظهر فوق معاينات الأشكال ذات الحدود المنحنية. صفة تصف الأشكال.
Expand عنوان زر. زر أسفل معاينة شكل، يعرض تفاصيله أسفل المعاينة. فعل يعبّر عن إجراء.
Selected تسمية التحديد. حالة تظهر بجانب الشكل المحدد حاليًا للمعاينة. تصف الحالة الراهنة للشكل.

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

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

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

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

أضف تعليقات للمترجم في SwiftUI

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

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

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

تمت مراجعة هذا المثال وفق أنماط واجهات برمجة التطبيقات الموثقة؛ ولم يُترجم أو يُشغّل هنا لعدم توفر سلسلة أدوات Swift في البيئة المتاحة.

بالنسبة إلى السلاسل النصية الموجّهة للمستخدم التي تُنشأ خارج عرض SwiftUI، توثّق Apple String(localized:comment:). استخدم وسيطة التعليق في واجهة برمجة التطبيقات الخاصة بالتوطين لإرفاق السياق بالرسالة. وتدعم Apple أيضًا مفتاح بحث منفصلًا وقيمة مصدر افتراضية عند الحاجة إلى اختلافهما. إعداد نص تطبيقك للترجمة

وضّح القيم المُدرجة حسب معناها وعلاقتها

يحتوي التعليق في المثال على استيفاءين من Swift: \(shapeName) و\(collectionName). يُدرج استيفاء Swift قيم التعبيرات في سلسلة نصية حرفية. تنتمي أسماء المتغيرات إلى الشفرة المصدرية؛ لكن ينبغي أن يظل الشرح مفهومًا لمن لا يستطيع رؤية تلك الأسماء. السلاسل النصية والمحارف

في القيم الافتراضية المعروضة، تُقرأ التسمية الإنجليزية Circle A in Shape Set A. ويوضح تعليقها ترتيب القيم المُدرجة والعلاقة بينها: إحداها اسم الشكل، والأخرى اسم المجموعة التي يحتويه. وهذا يوفر معلومات عملية أكثر من مجرد وصف وسيطتين من نوع سلسلة نصية.

عند مراجعة رسالة تتضمن استيفاءً، اطرح ثلاثة أسئلة:

  1. ما نوع المحتوى الذي يمكن أن يظهر في كل موضع: اسم، أم عدد، أم نوع آخر من القيم؟
  2. ما العلاقة بين القيم؟
  3. هل يظل التعليق دقيقًا لكل قيمة يمكن للتطبيق تقديمها؟

وضّح أن الأمثلة توضيحية. فهنا يبيّن Circle A وShape Set A دورَي الوسيطتين. وهما لا يحددان ترجمة مطلوبة أو قائمة شاملة بالأسماء المحتملة.

تتطلب الأعداد قرارًا منفصلًا بشأن التنفيذ. إذا أضفت لاحقًا تعليقًا مثل 3 shapes، فيمكن للتعليق أن يوضح ما الذي يُعَدّ، لكن الصيغ النحوية المختلفة مكانها في الكتالوج. توثّق Apple استخدام Vary by Plural مع الأعداد المُدرجة، بما في ذلك صيغ إنجليزية منفصلة مثل 1 item و2 items. توطين النصوص وتنويعها باستخدام كتالوج السلاسل النصية

اعثر على التعليقات وافحصها في Xcode

لربط التعليقات المصدرية بالكتالوج، اتبع سير العمل الموثق من Apple:

  1. اختر File > New > File from Template.
  2. صفِّ النتائج باستخدام string، وحدد String Catalog ضمن Resource، وأنشئه بالاسم الافتراضي Localizable.
  3. اختر Product > Build لاستخراج السلاسل النصية القابلة للتوطين.
  4. حدد Localizable.xcstrings في متصفح المشروع.
  5. اختر Editor > Assistant، ثم حدد مفتاحًا لفحص مصدره بجوار الكتالوج. توطين النصوص وتنويعها باستخدام كتالوج السلاسل النصية

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

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

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

قرر ما إذا كان يمكن لتسميتين متطابقتين مشاركة السياق

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

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

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

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

المصادر