पुनः उपयोग योग्य macOS लेबल के लिए, स्थानीयकृत किए जा सकने वाले संदेश LocalizedStringResource के रूप में स्वीकार करें, शाब्दिक टेक्स्ट के लिए अलग verbatim: पथ रखें, और स्थानीयकरण होने तक इंटरपोलेशन को जस का तस रखें। यह ट्यूटोरियल डेस्कटॉप आइटम काउंटर के लिए यह अनुबंध बनाता है और डिस्प्ले से अलग एक्सट्रैक्शन की जाँच करता है।

पुनः उपयोग योग्य टेक्स्ट API को क्या वादा करना चाहिए?

मान लें कि Mac ऐप को एक संक्षिप्त सारांश चाहिए, जो आइटम की गिनती और Sample Set जैसे कृत्रिम संग्रह लेबल को दिखाए। पुनः उपयोग योग्य घटक को तीन इनपुट में अंतर करना होगा: अनुवाद की आवश्यकता वाला ऐप-लेखित संदेश, मौजूदा SwiftUI स्थानीयकरण कुंजी, और ऐसा टेक्स्ट जो दिए गए रूप में बिल्कुल वैसा ही दिखना चाहिए।

Apple, कस्टम व्यू और अन्य Swift कोड में स्थानीयकृत किए जा सकने वाले स्ट्रिंग को दर्शाने और आगे भेजने के लिए LocalizedStringResource की अनुशंसा करता है। उसके मौजूदा मार्गदर्शन में दिखाया गया है कि इस प्रकार की कस्टम व्यू प्रॉपर्टी को Text के साथ डिस्प्ले किया जाता है। नया घटक डिज़ाइन करते समय इसे प्राथमिक संदेश अनुबंध के रूप में इस्तेमाल करें। अपने ऐप के टेक्स्ट को अनुवाद के लिए तैयार करना।

नीचे दी गई निर्णय तालिका, दस्तावेज़ित व्यवहारों के आधार पर तैयार किया गया एक API डिज़ाइन है। स्पष्ट आर्ग्युमेंट लेबल से कॉलर की मंशा की समीक्षा की जा सकती है और दो प्रतिस्पर्धी, बिना लेबल वाले स्ट्रिंग ओवरलोड पर निर्भर नहीं रहना पड़ता।

कॉलर की मंशा प्रस्तावित एंट्री पॉइंट रेंडरिंग पथ
वैकल्पिक संदर्भ के साथ अनुवाद योग्य संदेश देना SummaryLabel(localized:) Text(resource)
SwiftUI इंटरपोलेशन सहित SwiftUI कुंजी देना SummaryLabel(key:) Text(key, tableName:bundle:)
ठीक वैसा ही लेबल दिखाना SummaryLabel(verbatim:) Text(verbatim:)
कॉलर द्वारा पहले से तैयार किया गया टेक्स्ट देना SummaryLabel(text:) दिए गए Text को स्टोर करें

जब घटक को खास तौर पर SwiftUI का कुंजी-आधारित व्यवहार चाहिए, तब LocalizedStringKey उपलब्ध रखें। Apple के दस्तावेज़ बताते हैं कि Text को सीधे दिया गया स्ट्रिंग लिटरल स्थानीयकरण कुंजी बनाता है, जबकि String वैरिएबल सामान्यतः ऐसे पथ पर जाता है जो स्थानीयकरण को बायपास करता है। इसलिए केवल String स्वीकार करने वाला रैपर दिखने में समान कॉल का अर्थ बदल देता है। LocalizedStringKey।

स्पष्ट एंट्री पॉइंट के साथ पूरा घटक बनाएँ

इस उदाहरण के लिए Xcode 26 या उसके बाद के संस्करण में macOS SwiftUI ऐप प्रोजेक्ट इस्तेमाल करें और उसका डिप्लॉयमेंट टारगेट macOS 26 पर सेट करें। जनरेट की गई ऐप और कंटेंट-व्यू घोषणाओं को नीचे दिए गए पूरे प्रोग्राम से बदलें; टारगेट में केवल एक @main घोषणा रखें। सभी लेबल और गिनतियाँ कृत्रिम हैं। कोड को दस्तावेज़ित API के आधार पर जाँचा गया है, लेकिन यहाँ कंपाइल नहीं किया गया क्योंकि इस परिवेश में Swift कंपाइलर उपलब्ध नहीं है।

import Foundation
import SwiftUI

struct SummaryLabel: View {
    private let text: Text

    init(localized resource: LocalizedStringResource) {
        text = Text(resource)
    }

    init(
        key: LocalizedStringKey,
        tableName: String? = nil,
        bundle: Bundle? = nil,
        comment: StaticString? = nil
    ) {
        text = Text(
            key,
            tableName: tableName,
            bundle: bundle,
            comment: comment
        )
    }

    init(verbatim value: String) {
        text = Text(verbatim: value)
    }

    init(text: Text) {
        self.text = text
    }

    var body: some View {
        text
            .font(.callout)
            .padding(8)
    }
}

struct ContentView: View {
    @State private var itemCount = 2
    private let collectionLabel = "Sample Set"

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Stepper(value: $itemCount, in: 0...12) {
                Text("Item count")
            }

            SummaryLabel(
                localized: LocalizedStringResource(
                    "summary.item-count",
                    defaultValue: "\(itemCount) items",
                    comment: "Summary below the item-count control. The integer is the number of items."
                )
            )

            SummaryLabel(
                key: "Collection: \(collectionLabel)"
            )

            SummaryLabel(verbatim: collectionLabel)

            SummaryLabel(
                text: Text(
                    "Preview",
                    comment: "Heading for a preview of the current item selection."
                ).bold()
            )
        }
        .padding(20)
        .frame(minWidth: 320)
    }
}

@main
struct TextContractDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

रिसोर्स इनिशियलाइज़र स्थिर कुंजी summary.item-count को उसके डिफ़ॉल्ट संदेश \(itemCount) items से जानबूझकर अलग रखता है। Apple इस इनिशियलाइज़र के लिए स्थिर कुंजी, स्थानीयकृत किया जा सकने वाला डिफ़ॉल्ट मान, टेबल, लोकेल, बंडल और अनुवादक टिप्पणी का दस्तावेज़ देता है। निर्दिष्ट टेबल में कुंजी न होने पर उसका डिफ़ॉल्ट मान इस्तेमाल होता है। LocalizedStringResource इनिशियलाइज़र।

verbatim: इनिशियलाइज़र उतना ही स्पष्ट वादा करता है: दी गई स्ट्रिंग को स्थानीयकरण किए बिना दिखाएँ। यह लिटरल आर्ग्युमेंट और वैरिएबल, दोनों के साथ काम करता है। जब कृत्रिम संग्रह लेबल की वर्तनी ही डिस्प्ले की जाने वाली सामग्री हो, तब इस पथ का इस्तेमाल करें। Text.init(verbatim:)।

text: एंट्री पॉइंट से कॉलर टेक्स्ट तैयार कर सकता है—स्थानीयकृत या स्टाइल किया हुआ—और फिर उसे इस घटक को दे सकता है। यह घटक साझा टाइपोग्राफ़ी और स्पेसिंग जोड़ता है; संदेश का अर्थ कॉलर ही चुनता है। Text पास करना एक वैकल्पिक रास्ता है, इसलिए जो घटक अधिक सीमित अनुबंध लागू करना चाहता हो, वह इस इनिशियलाइज़र को छोड़ सकता है।

एक्सट्रैक्शन और रनटाइम फ़ॉर्मैटिंग में क्या अंतर है?

स्थानीयकरण की दो अलग जाँचें करें। बिल्ड के दौरान Xcode स्थानीयकृत किए जा सकने वाले सोर्स एक्सप्रेशन खोजता है और String Catalog को अपडेट करता है। ऐप चलते समय संदेश का समाधान करता है और उसके आर्ग्युमेंट बदलकर डालता है। Apple का String Catalog सत्र स्पष्ट रूप से बताता है कि कस्टम-व्यू कॉल साइट पर LocalizedStringResource बनाने के लिए इस्तेमाल किए गए लिटरल पहचाने जाते हैं। उसमें Use Compiler to Extract Swift Strings बिल्ड सेटिंग का भी उल्लेख है। String Catalog खोजें।

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

यह डायग्नोस्टिक अंश इस अंतर को दिखाता है; यह दूसरा ऐप नहीं है। अंश में इस्तेमाल किए गए सभी मान स्थानीय रूप से परिभाषित हैं।

import SwiftUI

let count = 2

// Ordinary String interpolation has already produced "2 items".
let completed: String = "\(count) items"
let exactDisplay = Text(completed)

// Looks up the completed value as a key.
// This does not restore a count placeholder.
let completedValueLookup = Text(LocalizedStringKey(completed))

// Preserves localization-aware interpolation from the beginning.
let messageKey: LocalizedStringKey = "\(count) items"
let interpolatedDisplay = Text(messageKey)

वैरिएबल से LocalizedStringKey बनाना रनटाइम लुकअप माँगने का एक दस्तावेज़ित तरीका है। जब वैरिएबल में जानबूझकर कोई ज्ञात कुंजी रखी गई हो, तब यह उपयोगी है। इससे यह साबित नहीं होता कि Xcode ने उस वैरिएबल के हर संभावित मान को कैटलॉग में एक्सट्रैक्ट किया है। जानबूझकर इस्तेमाल की गई डायनामिक कुंजियों का स्पष्ट रखरखाव करें या ऐप के सीमित संदेशों के लिए लिटरल रिसोर्स घोषणाएँ इस्तेमाल करें। लुकअप व्यवहार और फ़ॉलबैक का दस्तावेज़ Text.init(_:tableName:bundle:comment:) में है।

विराम-चिह्नों और प्लेसहोल्डर की स्थितियों सहित पूरा संदेश एक ही स्थानीयकृत किए जा सकने वाले एक्सप्रेशन में रखें। इस उदाहरण के लिए, Collection: \(collectionLabel) को एक साथ रखें। अलग-अलग हल किए गए हिस्सों से तैयार संदेश बनाने पर उनका क्रम और स्पेसिंग कॉलर को संभालनी पड़ेगी।

कैटलॉग जोड़ें और बहुवचन व्यवहार कॉन्फ़िगर करें

पहले, File > New > File from Template के ज़रिए String Catalog जोड़ें, String Catalog चुनें और उसका नाम Localizable रखें। फिर Product > Build चुनें। Apple के दस्तावेज़ के मुताबिक, बिल्ड स्थानीयकरण API से कैटलॉग भरता है और सोर्स संदेश बदलने पर उसे अपडेट करता है। स्ट्रिंग कैटलॉग के साथ टेक्स्ट का स्थानीयकरण और रूप बदलना।

इस नमूने के लिए summary.item-count एंट्री और उसके इंटरपोलेट किए गए पूर्णांक की जाँच करें। एंट्री पर कंट्रोल-क्लिक करें और Vary by Plural चुनें। अंग्रेज़ी सोर्स स्थानीयकरण में One को %lld item और Other को %lld items पर सेट करें; Xcode द्वारा दिए गए पूर्णांक प्लेसहोल्डर को बनाए रखें। अन्य स्थानीयकरण जोड़ते समय आवश्यक रूप शामिल करें; बहुवचन श्रेणियाँ भाषा पर निर्भर करती हैं। स्ट्रिंग कैटलॉग के साथ टेक्स्ट का स्थानीयकरण और रूप बदलना।

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

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

जाँच अपेक्षित परिणाम
बिल्ड करें और summary.item-count की जाँच करें पूर्णांक प्रतिस्थापन वाली एक संदेश एंट्री
गिनती को 0 पर सेट करें 0 items
गिनती को 1 पर सेट करें 1 item
गिनती को 2 पर सेट करें 2 items
सटीक-लेबल वाली पंक्ति की जाँच करें Sample Set लिटरल रहता है
संग्रह संदेश की जाँच करें लेबल पूरे संदेश के भीतर एक आर्ग्युमेंट है

छूटी हुई एंट्री और गलत डिस्प्ले की अलग-अलग जाँच करें

अगर कैटलॉग में कोई संदेश नहीं है, तो पहले उसका सोर्स प्रकार देखें। String पैरामीटर स्थानीयकृत किए जा सकने वाले एक्सप्रेशन को घटक तक पहुँचने से पहले मिटा सकता है। कैटलॉग का टारगेट जाँचें, उस कॉल साइट वाला स्कीम बिल्ड करें और Use Compiler to Extract Swift Strings की पुष्टि करें। Apple बताता है कि एक्सट्रैक्शन मौजूदा स्कीम और प्लेटफ़ॉर्म पर काम करता है, इसलिए वही कॉन्फ़िगरेशन देखें जो वास्तव में संदेश को कंपाइल करता है। String Catalog खोजें।

अगर एंट्री मौजूद है लेकिन ऐप कुंजी या फ़ॉलबैक टेक्स्ट दिखाता है, तो लुकअप कॉन्फ़िगरेशन देखें। कुंजी-आधारित Text इनिशियलाइज़र निर्दिष्ट टेबल और बंडल में खोजता है; मान न देने पर डिफ़ॉल्ट टेबल और मुख्य बंडल चुने जाते हैं। कुंजी या टेबल न होने पर कुंजी का स्ट्रिंग रूप मिलता है। इसलिए पढ़ने योग्य फ़ॉलबैक अधूरे लुकअप को छिपा सकता है। Text.init(_:tableName:bundle:comment:)।

घटक को फ़्रेमवर्क या पैकेज में ले जाते समय तय करें कि संदेश कहाँ के होंगे। घटक के अपने संदेशों के लिए घटक का रिसोर्स बंडल चाहिए; कॉलर के रिसोर्स में लुकअप की दी गई जानकारी बनी रहनी चाहिए। Apple का मौजूदा मार्गदर्शन स्थानीयकरण API को #bundle पास करने का समर्थन करता है, ताकि इसमें मौजूद टारगेट का बंडल पहचाना जा सके। नाम वाली टेबल के लिए भी मेल खाते कैटलॉग चाहिए। अपने ऐप के टेक्स्ट को अनुवाद के लिए तैयार करना।

अंत में, यह न मानें कि SwiftUI द्वारा स्वीकार किया गया हर इंटरपोलेशन Foundation रिसोर्स में भी इस्तेमाल किया जा सकता है। LocalizedStringKey के अपने इंटरपोलेशन तरीके हैं, जिनमें फ़ॉर्मैट-शैली और फ़ॉर्मैटर वाले विकल्प शामिल हैं। एक्सप्रेशन लिखने से पहले संदेश का प्रकार चुनें और आर्ग्युमेंट कंपाइल न होने पर उसके समर्थित इंटरपोलेशन तरीकों को देखें। LocalizedStringKey.StringInterpolation।

पुनः उपयोग योग्य टेक्स्ट घटक तब तैयार है जब कॉलर अपनी मंशा साफ़ तौर पर बता सकें और दोनों चरणों पर उसे सत्यापित कर सकें: बिल्ड से अपेक्षित कैटलॉग संदेश बने और चलता हुआ Mac ऐप सही प्रतिस्थापन, बहुवचन रूप या सटीक लेबल दिखाए। घटक बदलने पर इन जाँचों को API अनुबंध के साथ रखें।

स्रोत