एक उपयोगी अनुवादक टिप्पणी बताती है कि किसी लेबल का क्या अर्थ है, वह कहाँ दिखाई देता है और कोई उसका उपयोग करता है तो क्या होता है। यह मार्गदर्शिका कृत्रिम अंग्रेज़ी लेबलों का उपयोग करके, एक सरल Mac आकार ब्राउज़र के लिए Xcode में ऐसी टिप्पणियाँ लिखने और जोड़ने का तरीका बताती है।

अनुवादक टिप्पणी में क्या समझाना चाहिए?

उस निर्णय से शुरुआत करें जो अनुवादक को लेना है। Round जैसा छोटा लेबल अपनी व्याकरणिक भूमिका और इच्छित अर्थ स्पष्ट नहीं करता। टिप्पणी यह पहचान सकती है कि यह आकार की श्रेणी बताने वाला विशेषण है और समझा सकती है कि यह पूर्वावलोकनों के समूह के ऊपर दिखाई देता है। Apple ऐसी टिप्पणियों की अनुशंसा करता है जो स्पष्ट करें कि इंटरफ़ेस में कोई स्ट्रिंग कहाँ और कैसे उपयोग होती है। स्ट्रिंग कैटलॉग खोजें

Mac ऐप के लेबलों को अनुवाद के लिए तैयार करने वाले व्यक्ति का ठोस काम हर अस्पष्ट स्ट्रिंग को एक छोटी, अपने आप में पूरी व्याख्या में बदलना है। अनुवादक को स्रोत कोड देखे बिना उसका उद्देश्य समझ आना चाहिए।

लेखन में मदद के लिए इन चार हिस्सों का उपयोग करें। यह Apple के मार्गदर्शन से निकली संपादकीय विधि है, Apple द्वारा निर्धारित टिप्पणी का प्रारूप नहीं:

हिस्सा किस प्रश्न का उत्तर दें उदाहरण का विवरण
अर्थ स्रोत में लिखे शब्द किस चीज़ को संदर्भित करते हैं? Round घुमावदार बाहरी रेखाओं वाले आकारों का वर्णन करता है।
UI की भूमिका यह किस प्रकार का इंटरफ़ेस पाठ है? आकारों के पूर्वावलोकनों के ऊपर एक श्रेणी शीर्षक।
व्यवहार या स्थान क्या होता है, या इसके आसपास क्या है? Expand पूर्वावलोकन के नीचे विवरण दिखाता है।
परिवर्तनीय सामग्री डाली गई हर वैल्यू में क्या हो सकता है? पहली वैल्यू आकार का नाम है; दूसरी वैल्यू संग्रह का नाम है।

केवल उन्हीं हिस्सों को शामिल करें जो अर्थ समझने में मदद करते हैं। स्थिर शीर्षक के लिए किसी कार्रवाई की व्याख्या ज़रूरी नहीं। बटन के लिए यह स्पष्ट बताना उपयोगी है कि उसे क्लिक करने पर क्या होता है। दो डाले गए नामों वाले संदेश में उन नामों के बीच का संबंध बताना ज़रूरी है।

Apple विशेष रूप से इंटरफ़ेस तत्व, उसके आसपास के इंटरफ़ेस और प्लेसहोल्डर से दर्शाई गई सामग्री को समझाने की सलाह देता है। इन विवरणों को अनुवाद के लिए व्यावहारिक संदर्भ मानें। कोड के साथ अभ्यास: Xcode में लोकलाइज़ेशन देखें

अस्पष्ट टिप्पणियों को संदेश के उपयोगी अनुबंध में बदलें

नीचे दिए गए उदाहरण एक उदाहरणात्मक Mac आकार ब्राउज़र के हैं। हर बेहतर टिप्पणी इंटरफ़ेस के एक स्पष्ट, माने हुए व्यवहार का वर्णन करती है; शब्दों का उपयोग करने से पहले उसे वास्तविक नियंत्रण के व्यवहार के अनुसार ढालें।

स्रोत लेबल कमज़ोर टिप्पणी अधिक उपयोगी टिप्पणी
Shapes आकारों के लिए लेबल। साइडबार का नेविगेशन आइटम, जो ज्यामितीय आकारों की सूची खोलता है। बहुवचन संज्ञा।
Round आकार का पाठ। घुमावदार बाहरी रेखाओं वाले आकारों के पूर्वावलोकनों के ऊपर श्रेणी शीर्षक। आकारों का वर्णन करने वाला विशेषण।
Expand बटन का शीर्षक। आकार के पूर्वावलोकन के नीचे का बटन, जो पूर्वावलोकन के नीचे उसका विवरण दिखाता है। कार्रवाई बताने वाली क्रिया।
Selected चयन का लेबल। उस आकार के पास स्थिति, जिसे फिलहाल पूर्वावलोकन के लिए चुना गया है। आकार की मौजूदा स्थिति बताता है।

कमज़ोर टिप्पणियाँ वही दोहराती हैं जो अनुवादक पहले से देख सकता है। बेहतर टिप्पणियाँ छूटे हुए संबंध बताती हैं: विशेषण किस वस्तु का वर्णन करता है, बटन कौन-सी सामग्री दिखाता है, या किस आइटम की कोई विशेष स्थिति है।

अंग्रेज़ी में संज्ञा किसी चीज़ का नाम बताती है, विशेषण किसी चीज़ का वर्णन करता है और आज्ञार्थक क्रिया किसी कार्रवाई का निर्देश देती है। ये अंतर संक्षिप्त इंटरफ़ेस शब्दावली समझाने में मदद करते हैं। उदाहरण के लिए, इस उदाहरण में Selected पहले से मौजूद स्थिति का वर्णन करता है; बटन पर Select कार्रवाई करने का अनुरोध होगा। बताएँ कि इंटरफ़ेस को किस अर्थ की ज़रूरत है।

टिप्पणियाँ ठोस रखें। Expand के लिए बताएँ कि नियंत्रण विवरण-पाठ दिखाता है, पूर्वावलोकन बड़ा करता है या साइडबार समूह खोलता है। यह कहना कि इससे कोई चीज़ बड़ी होती है, कार्रवाई का नाम बताने जितना उपयोगी नहीं है।

अंग्रेज़ी के अनावश्यक फ़ॉर्मैटिंग नियम न थोपें। अगर इंटरफ़ेस को संक्षिप्त श्रेणी शीर्षक चाहिए, तो यह बात बताएँ। कोई निश्चित अक्षर-सीमा न गढ़ें और अनुवाद में अंग्रेज़ी के शब्द-क्रम को बनाए रखने की माँग न करें। वास्तविक लेआउट की बाधा तभी दर्ज करें जब आपको मालूम हो कि वह लागू होती है।

SwiftUI में अनुवादक टिप्पणियाँ जोड़ें

Apple, Text पर comment: पैरामीटर को अनुवाद संकेत शामिल करने का तरीका बताता है। जब किसी नियंत्रण का सुविधाजनक स्ट्रिंग इनिशियलाइज़र आपको ज़रूरी टिप्पणी देने की सुविधा न दे, तो स्पष्ट Text व्यू के साथ उसका कंटेंट बिल्डर उपयोग करें। Apple Label के लिए यह तरीका दिखाता है और समझाता है कि SwiftUI के कई नियंत्रण इसे सपोर्ट करते हैं। लोकलाइज़ेशन के लिए व्यू तैयार करना

नीचे दिया गया पूरा उदाहरण macOS का एक छोटा SwiftUI ऐप है। Xcode में SwiftUI का उपयोग करके macOS ऐप प्रोजेक्ट बनाएँ, डिप्लॉयमेंट टार्गेट 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)
    }
}

इस उदाहरण की दस्तावेज़ीकृत API विधियों से तुलना करके जाँच की गई है; इसे यहाँ कंपाइल या चलाया नहीं गया, क्योंकि उपलब्ध वातावरण में Swift टूलचेन नहीं है।

SwiftUI व्यू के बाहर उपयोगकर्ता को दिखने वाली स्ट्रिंग बनाने के लिए, Apple String(localized:comment:) को दस्तावेज़ीकृत करता है। संदेश के साथ संदर्भ जोड़ने के लिए लोकलाइज़ेशन API के टिप्पणी तर्क का उपयोग करें। ज़रूरत पड़ने पर 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 फ़िल्टर करें, Resource के अंतर्गत String Catalog चुनें और डिफ़ॉल्ट नाम Localizable के साथ फ़ाइल बनाएँ।
  3. लोकलाइज़ की जा सकने वाली स्ट्रिंग निकालने के लिए Product > Build चुनें।
  4. Project navigator में Localizable.xcstrings चुनें।
  5. Editor > Assistant चुनें, फिर किसी की को चुनकर स्रोत को कैटलॉग के बगल में देखें। स्ट्रिंग कैटलॉग के साथ पाठ को लोकलाइज़ करना और उसके रूप बदलना

कैटलॉग की टिप्पणी की वास्तविक उपयोग से तुलना करें। नमूने में Round को श्रेणी शीर्षक समझाना चाहिए और Expand को विवरण दिखाने की क्रिया बतानी चाहिए। अगर कोई स्ट्रिंग नहीं दिखती, तो देखें कि कोड में लोकलाइज़ेशन API का उपयोग हो रहा है या नहीं और Use Compiler to Extract Swift Strings सक्षम है या नहीं। Apple इस बिल्ड सेटिंग को कंपाइलर के ज़रिए Swift स्ट्रिंग निकालने के लिए ज़रूरी बताता है। स्ट्रिंग कैटलॉग खोजें

Apple, String Catalog के कमेंट कॉलम में सीधे संदर्भ संपादित करने की सुविधा भी देता है। Xcode 26 में स्वचालित टिप्पणी जनरेशन शुरू हुई; मौजूदा दस्तावेज़ में किसी की पर Control-क्लिक करके Generate Comment चुनने का तरीका दिया गया है। अगर आपके सेटअप में यह विकल्प उपलब्ध न हो, तो कोड में टिप्पणी जोड़ें या उसे कैटलॉग में दर्ज करें। कोड के साथ अभ्यास: Xcode में लोकलाइज़ेशन देखें, स्ट्रिंग कैटलॉग के साथ पाठ को लोकलाइज़ करना और उसके रूप बदलना

जेनरेट किए गए शब्दों की इंटरफ़ेस के व्यवहार से तुलना करें। किसी बटन की सही पहचान करने वाले विवरण में भी वस्तु या नतीजे को स्पष्ट करना पड़ सकता है। इस उदाहरण में उपयोगी अंतर यह है कि Expand पूर्वावलोकन के नीचे विवरण वाला वाक्य दिखाता है।

तय करें कि एक जैसे दो लेबल एक ही संदर्भ साझा कर सकते हैं या नहीं

अंग्रेज़ी की वर्तनी एक जैसी होने से यह साबित नहीं होता कि अर्थ भी एक है। मान लें कि कोई दूसरा स्क्रीन Round का उपयोग संख्यात्मक मान को पूर्णांक में बदलने वाली कार्रवाई के रूप में करता है। उस उपयोग को आकार-श्रेणी वाले शीर्षक के साथ जोड़ने पर एक कैटलॉग प्रविष्टि को दो अलग व्याकरणिक भूमिकाएँ समझानी पड़ेंगी।

Apple बताता है कि लोकलाइज़ की जा सकने वाली स्ट्रिंग की एक लुकअप की होती है और वह एक टेबल से जुड़ी होती है; किसी टेबल में की अद्वितीय होती हैं। Apple का Swift दस्तावेज़ अलग की के साथ डिफ़ॉल्ट स्रोत वैल्यू उपयोग करने का समर्थित तरीका भी देता है। जब अर्थों के लिए अलग अनुवाद चाहिए हों, तो अलग की का उपयोग करें, भले ही अंग्रेज़ी में दिखने वाली वैल्यू एक जैसी हों। स्ट्रिंग कैटलॉग खोजें, अपने ऐप के पाठ को अनुवाद के लिए तैयार करना

एक व्यावहारिक नियम यह है कि पूछें: क्या एक टिप्पणी हर उपयोग को सही ढंग से समझा सकती है? अगर अर्थ और UI की भूमिका एक जैसी रहती है, तो साझा संदर्भ उपयुक्त हो सकता है। अगर व्याख्या के लिए असंबंधित कार्रवाइयों का वर्णन करना पड़े, तो की की संरचना पर फिर से विचार करें। यह Apple के की और टेबल मॉडल से निकला डिज़ाइन-संबंधी निष्कर्ष है, यह नियम नहीं कि हर नियंत्रण की अपनी स्ट्रिंग होनी चाहिए।

किसी लेबल को सौंपने से पहले उसकी टिप्पणी को स्रोत कोड के बिना पढ़ें। इससे अनुवादक इच्छित अर्थ पहचान सके, इंटरफ़ेस में पाठ की जगह की कल्पना कर सके और डाली गई किसी भी सामग्री को समझ सके। जब भी लेबल का व्यवहार या भूमिका बदले, टिप्पणी संशोधित करें ताकि वह उपयोगकर्ता को दिखने वाले इंटरफ़ेस का सही वर्णन करती रहे।

स्रोत