संदेशों या अनुवादों को खोए बिना स्ट्रिंग कैटलॉग की कुंजियों का नाम बदलें

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

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

कुंजी बदलने पर क्या-क्या जस का तस रहना चाहिए?

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

संपादन से पहले, प्रभावित हर प्रविष्टि के लिए निम्नलिखित दर्ज करें। ये काल्पनिक उदाहरण नाम बदलने का तरीका दिखाते हैं; ये मापे गए परिणाम नहीं हैं।

घटक	पहले	इच्छित परिणाम
लुकअप कुंजी	`Open collection`	`collection.open`
स्रोत संदेश	`Open collection`	अपरिवर्तित
टेबल	`Localizable`	अपरिवर्तित
बंडल	मुख्य ऐप बंडल	अपरिवर्तित
अनुवादक के लिए संदर्भ	बटन जो चुना हुआ संग्रह खोलता है	सुरक्षित रखा गया
मौजूदा अनुवाद	हर लोकलाइज़ेशन में मौजूदा मान	सुरक्षित रखे गए
काउंट आर्ग्युमेंट, यदि हों	पूर्णांक काउंट	वही प्रकार और अर्थ
बहुवचन या डिवाइस वैरिएंट	मौजूदा शाखाएँ	सुरक्षित रखी गईं

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

कैटलॉग संपादित करने से पहले स्रोत ढूँढ़ें

Xcode के Project navigator में मौजूदा कैटलॉग खोलें। Editor > Assistant चुनें, फिर स्रोत देखने के लिए प्रविष्टि चुनें। Apple संदर्भ ढूँढ़ने के अन्य तरीकों के रूप में कुंजी के पास वाले तीर और Attributes inspector में दिए गए उदाहरण उपयोग भी बताता है। एक्सट्रैक्ट की गई स्ट्रिंग के लिए, स्रोत में बदलाव के बाद कैटलॉग सिंक्रोनाइज़ करने हेतु Product > Build चुनें। स्ट्रिंग कैटलॉग के साथ टेक्स्ट को लोकलाइज़ और वैरिएट करना

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

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

एक्सट्रैक्ट की गई स्ट्रिंग के लिए Xcode का कन्वर्ज़न रीफ़ैक्टर इस्तेमाल करें

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

बिल्ड सेटिंग में जाँचें कि Generate String Catalog Symbols को Yes पर सेट किया गया है, यदि मौजूदा प्रोजेक्ट में इसे सक्षम करना आवश्यक हो।
कैटलॉग एडिटर में मौजूदा कुंजी चुनें, उस पर Control-click करें, और Refactor > Convert Strings to Symbols चुनें।
कैटलॉग कुंजी में बदलाव और प्रभावित स्रोत स्थान दिखाने वाले प्रीव्यू की जाँच करें।
कन्वर्ज़न इंटरफ़ेस में प्रस्तावित अर्थपूर्ण नाम और, जहाँ लागू हो, आर्ग्युमेंट के नाम संपादित करें।
हाइलाइट किए गए प्रीव्यू में मौजूदा और संशोधित कोड की तुलना करें, फिर Convert पर क्लिक करें।
बिल्ड करें और परिणामी प्रविष्टि की अपने चेकपॉइंट से तुलना करें; अनुवाद और वैरिएंट भी जाँचें।

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

यह रीफ़ैक्टर विशेष रूप से एक्सट्रैक्ट की गई स्ट्रिंग से जनरेट किए गए सिंबल में जाने के लिए है। उद्धृत दस्तावेज़ हर हाथ से प्रबंधित प्रविष्टि या हर बाहरी संदर्भ के लिए कोई सार्वभौमिक नाम बदलने की प्रक्रिया स्थापित नहीं करता। यदि प्रीव्यू में कोई आवश्यक संदर्भ छूट जाए, तो पुरानी कुंजी हटाने से पहले उसे स्पष्ट रूप से ठीक करें।

यदि आप कोड में कुंजियाँ और डिफ़ॉल्ट मान रखना चाहते हैं, तो एक्सट्रैक्शन जारी रखें

आप कोड-चालित एक्सट्रैक्शन बनाए रख सकते हैं। Apple String(localized:defaultValue:...) के ज़रिए अलग लुकअप कुंजियों और स्रोत संदेशों का स्पष्ट रूप से समर्थन करता है: पहला आर्ग्युमेंट कुंजी देता है, और defaultValue स्रोत स्ट्रिंग देता है। उदाहरण के लिए, अर्थपूर्ण कुंजी के साथ Open collection को डिफ़ॉल्ट संदेश के रूप में रखा जा सकता है। अनुवाद के लिए अपने ऐप का टेक्स्ट तैयार करना

यह पूरा ऐप स्रोत उदाहरण एक स्थिर लेबल और एक पूर्णांक काउंट के साथ इस पैटर्न को दिखाता है। macOS 12 या उसके बाद के डिप्लॉयमेंट टारगेट वाला macOS SwiftUI ऐप टारगेट इस्तेमाल करें, और दूसरा @main डिक्लेरेशन जोड़ने के बजाय ऐप की मौजूदा एंट्री स्रोत फ़ाइल बदलें। ऐप टारगेट में Localizable.xcstrings जोड़ें। उदाहरण को Apple के API के संदर्भ में देखा गया था; यहाँ इसे कंपाइल नहीं किया गया, क्योंकि 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 रनटाइम आर्ग्युमेंट है; इसे स्थिर कुंजी का हिस्सा नहीं बनना चाहिए।

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

व्याकरण की दृष्टि से काउंट वाले संदेशों के लिए, एक्सट्रैक्ट की गई काउंट प्रविष्टि चुनें, उस पर Control-click करें, और 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 स्कीम के ज़रिए इस परीक्षण वर्कफ़्लो का दस्तावेज़ देता है। ऐप चलाते समय लोकलाइज़ेशन की जाँच करना

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