Xcode 26 और बाद के संस्करणों में, String Catalogs ऐसे Swift एक्सेसर्स जनरेट कर सकते हैं जो हाथ से टाइप की गई लोकलाइज़ेशन कुंजियों की जगह लेते हैं। यह गाइड एक छोटे Mac ऐप के चयन सारांश को टाइप्ड प्रॉपर्टीज़ और फ़ंक्शन्स में माइग्रेट करती है, फिर जाँचती है कि कंपाइलर वास्तव में किस चीज़ की सुरक्षा करता है।

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

लोकलाइज़ेशन एक्सेसर को कंपाइल-टाइम पर सत्यापित क्या बनाता है?

Apple ने Xcode 26 में नेटिव String Catalog प्रतीक जनरेशन शुरू किया। बिना प्लेसहोल्डर वाली प्रविष्टि एक स्टैटिक प्रॉपर्टी बनाती है; प्लेसहोल्डर वाली प्रविष्टि टाइप्ड पैरामीटर वाला फ़ंक्शन बनाती है। दोनों LocalizedStringResource लौटाते हैं। नए Xcode 26 प्रोजेक्ट्स में जनरेशन डिफ़ॉल्ट रूप से सक्षम है; मौजूदा प्रोजेक्ट्स में बिल्ड सेटिंग सक्षम करनी पड़ सकती है। Code-along: Explore localization with Xcode

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

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

एक छोटा Mac ऐप और उसका संदेश अनुबंध सेट अप करें

Xcode 26 या बाद का संस्करण और macOS SwiftUI ऐप टार्गेट इस्तेमाल करें। इस उदाहरण के लिए, डिप्लॉयमेंट टार्गेट macOS 15 या बाद का रखें। मूल LocalizedStringResource टाइप macOS 13 से उपलब्ध है; उदाहरण का ऊँचा टार्गेट इस चुनाव की पूर्वशर्त है, उस टाइप का न्यूनतम संस्करण नहीं। कोई रिसोर्स ऐसे लोकलाइज़ किए जा सकने वाले टेक्स्ट को दर्शाता है जिसका लुकअप ज़रूरत पड़ने तक टाला जा सकता है। LocalizedStringResource

File > New > File from Template के ज़रिए कैटलॉग जोड़ें। Resource के अंतर्गत String Catalog चुनें, उसका नाम Workbench रखें, और उसे ऐप टार्गेट में शामिल करें। Apple के अनुसार, हर कैटलॉग एक टेबल दर्शाता है; यहाँ अलग टेबल इस्तेमाल करने से उदाहरण के दोनों संदेश साथ रहते हैं। Localizing and varying text with a string catalog

प्रोजेक्ट एडिटर में Build Settings खोलें, Generate String फ़िल्टर करें, और टार्गेट के प्रभावी कॉन्फ़िगरेशन के लिए Generate String Catalog Symbols को Yes पर सेट करें। पुराने प्रोजेक्ट्स के लिए यही दस्तावेज़ीकृत स्विच है। Using generated localizable symbols in your code

Workbench.xcstrings में अंग्रेज़ी स्रोत लोकलाइज़ेशन चुनें। कैटलॉग एडिटर के टूलबार के + बटन से ये दो प्रविष्टियाँ जोड़ें। टिप्पणियाँ संदेशों का अर्थ बताती हैं, जिनमें आर्ग्युमेंट की भूमिकाएँ भी शामिल हैं।

कुंजी अंग्रेज़ी स्रोत मान टिप्पणी
TITLE Selection overview चयन सारांश के ऊपर का शीर्षक।
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available चयन सारांश। selectedCount चयनित वस्तुओं की संख्या है; availableCount उपलब्ध वस्तुओं की कुल संख्या है, जिसमें चयनित वस्तुएँ भी शामिल हैं।

SUBTITLE के लिए, आप Xcode के कोड-कम्प्लीशन मेनू से हर प्लेसहोल्डर दर्ज कर सकते हैं: % टाइप करें, पूर्णांक प्लेसहोल्डर चुनें, और उसका नाम selectedCount या availableCount रखें। Apple इन फ़ॉर्मैट स्पेसिफ़ायर के लिए नामित वेरिएबल और जनरेट किए गए पैरामीटर दस्तावेज़ीकृत करता है। हर प्रविष्टि चुनें और Attributes इंस्पेक्टर में Generate Swift Symbol तथा Example Usages देखें। Using generated localizable symbols in your code

इच्छित अनुबंध में एक शीर्षक प्रॉपर्टी और दो Int मान स्वीकार करने वाला सबटाइटल फ़ंक्शन है। आगे बढ़ने से पहले इंस्पेक्टर में जनरेट की गई वास्तविक वर्तनी जाँचें: Apple के अनुसार प्रतीक नाम में कुंजी और उसका मान—दोनों शामिल होते हैं। नीचे दिए गए उदाहरण .Workbench.title और .Workbench.subtitle(selectedCount:availableCount:) का उपयोग करते हैं, जो Apple के दस्तावेज़ीकृत अपरकेस-कुंजी पैटर्न के अनुरूप है। Code-along: Explore localization with 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 चयनित; 12 उपलब्ध दिखना चाहिए। चयन प्रबंधन कोड जोड़े बिना आर्ग्युमेंट की जगह जाँचने के लिए गणनाएँ तय रखी गई हैं।

Apple जनरेट किए गए रिसोर्स को SwiftUI में, Text सहित, और Foundation के String(localized:) इनिशियलाइज़र के ज़रिए उपयोग करने का तरीका दस्तावेज़ीकृत करता है। यदि मौजूदा Mac इंटरफ़ेस को हल की गई String चाहिए, तो उस सीमा पर जनरेट किए गए रिसोर्स को रूपांतरित करें। Code-along: Explore localization with Xcode

उदाहरण के लिए, कैटलॉग मौजूद होने के बाद उसी ऐप टार्गेट में जोड़ने के लिए यह एक पूरा हेल्पर फ़ंक्शन है:

import Foundation

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

अपने इंटरफ़ेस से LocalizedStringResource लौटाने पर रिसोर्स बाद में लुकअप के लिए बना रहता है; String लौटाने पर इनिशियलाइज़र चलते समय उसका मान हल हो जाता है। प्राप्तकर्ता इंटरफ़ेस की ज़रूरत के अनुसार चुनें। Apple Foundation दस्तावेज़ में लुकअप को टालने और तुरंत करने के बीच का यह अंतर बताता है। LocalizedStringResource

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

शुरुआती डॉट और आर्ग्युमेंट लेबल क्यों मायने रखते हैं

शुरुआती डॉट Swift का इम्प्लिसिट मेंबर सिंटैक्स है। जब आसपास का संदर्भ Swift को टाइप का अनुमान लगाने देता है, तो यह टाइप सदस्य तक पहुँचने का संक्षिप्त रूप है। यह सामान्य Swift सिंटैक्स है, स्ट्रिंग-कुंजी के लिए कोई विशेष ऑपरेटर नहीं। Expressions — Implicit Member Expression

जनरेट किए गए लोकलाइज़ेशन प्रतीकों के लिए, डिफ़ॉल्ट Localizable टेबल सीधे सदस्यों को उपलब्ध कराती है, जबकि नामित टेबल एक टेबल नेमस्पेस जोड़ती है। इसी कारण इस उदाहरण में सदस्य नाम से पहले .Workbench आता है। Apple दोनों रूपों का दस्तावेज़ीकरण करता है। Using generated localizable symbols in your code

selectedCount: और availableCount: लेबल फ़ंक्शन कॉल का हिस्सा हैं। Swift कॉल साइट पर दिखने वाले आर्ग्युमेंट लेबल और फ़ंक्शन के अंदर इस्तेमाल होने वाले पैरामीटर नामों में अंतर करता है। जब किसी पैरामीटर के लिए लेबल आवश्यक हो, तो कॉलर को वह देना पड़ता है। Functions — Function Argument Labels and Parameter Names

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

मौजूदा कुंजियों को उनका अर्थ बनाए रखते हुए माइग्रेट करें

मौजूदा लोकलाइज़ किए जा सकने वाले स्ट्रिंग्स के लिए Apple एक रीफ़ैक्टरिंग वर्कफ़्लो देता है। String Catalog में प्रविष्टियाँ चुनें, Control-click करें, और Refactor > Convert Strings to Symbols चुनें। प्रीव्यू देखें, ज़रूरत हो तो प्रस्तावित प्रतीक या पैरामीटर नाम समायोजित करें, और Convert चुनें। Using generated localizable symbols in your code

पहले एक संगत समूह माइग्रेट करें, जैसे इस विंडो का शीर्षक और सारांश। प्रीव्यू स्वीकार करने से पहले पुराने संदेश और नए अनुबंध की तुलना करें: क्या वे एक ही टेबल इस्तेमाल करते हैं, एक ही इंटरफ़ेस तत्व का वर्णन करते हैं, और हर प्लेसहोल्डर को वही अर्थ देते हैं? कुंजी बदलने से प्रभावित मौजूदा लोकलाइज़ किए गए मानों की समीक्षा करें; यह न मानें कि रीफ़ैक्टरिंग उनकी शुद्धता साबित करती है।

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

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

छोटे निदान क्रम से माइग्रेशन सत्यापित करें

नमूना विंडो पर ये जाँच करें। ये कंपाइलर सुरक्षा, संदेश की शुद्धता और रिसोर्स एकीकरण को अलग-अलग परखती हैं।

  1. काम कर रहा आधार स्थापित करने के लिए बिना बदलाव वाले उदाहरण का बिल्ड करें।
  2. शीर्षक सदस्य की वर्तनी अस्थायी रूप से गलत करें और बिल्ड करें। गैर-मौजूद सदस्य पर कंपाइलर निदान मिलना चाहिए। उसे वापस ठीक करें।
  3. जहाँ सबटाइटल को Int चाहिए, वहाँ अस्थायी रूप से String मान दें। टाइप असंगति जाँचने के लिए बिल्ड करें, फिर पूर्णांक वापस रखें।
  4. selectedCount को 3 पर और availableCount को 12 पर सेट करके चलाएँ। पुष्टि करें कि संख्याएँ अपनी इच्छित जगह पर हैं।
  5. कैटलॉग का केवल शीर्षक मान बदलकर Current selection करें, दोबारा बिल्ड करें, और प्रदर्शित शीर्षक की पुष्टि करें। जाँचें कि जनरेट किया गया सिग्नेचर वही है जिसका उपयोग आपका कोड करता है।

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

अंत में, वास्तविक इंटरफ़ेस जाँचें। Apple का दस्तावेज़ीकृत तरीका है Product > Scheme > Edit Scheme, फिर Run > Options, जहाँ आप चलाने से पहले App Language चुन सकते हैं। अपने प्रोजेक्ट द्वारा समर्थित लोकलाइज़ेशन के लिए इसे दोहराएँ। Testing localizations when running your app

शुरुआती लेआउट जाँच के लिए, Xcode में Double-Length Pseudolanguage भी है, जो आकार संबंधी समस्याएँ दिखाने के लिए लोकलाइज़ किए जा सकने वाले टेक्स्ट को फैलाता है। संकीर्ण विंडो चौड़ाई पर सारांश देखें; सफल कंपाइलेशन यह सुनिश्चित नहीं कर सकता कि टेक्स्ट ठीक से समाएगा। Test localizations

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

स्रोत