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

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

फ़ॉलबैक अनुबंध में क्या सुनिश्चित होना चाहिए?

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

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

अपेक्षित परिणाम तय करते समय नीचे दी गई निर्णय तालिका का उपयोग करें। यह संसाधन चयन को संदेश लुकअप से अलग रखती है, बजाय इसके कि हर अनुपलब्ध अनुवाद को एक ही स्थिति माना जाए।

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

यह तालिका Apple के संसाधन-चयन नियमों को Swift initializer के दस्तावेज़ित डिफ़ॉल्ट-वैल्यू व्यवहार के साथ जोड़ती है। यह उन API से निकली कार्यान्वयन नीति है, String Catalogs की कोई अलग फ़ॉलबैक सुविधा नहीं। सफल लुकअप में अनुपयुक्त पाठ होने पर initializer की उस दस्तावेज़ित शर्त को पूरा नहीं किया जाता जिसके तहत उसका डिफ़ॉल्ट इस्तेमाल होता है: लुकअप का विफल होना। String.init(localized:defaultValue:table:bundle:locale:comment:)।

हर स्वामी टार्गेट में अंग्रेज़ी स्रोत संसाधन कॉन्फ़िगर करें

इस उदाहरण के लिए, मौजूदा Xcode इंस्टॉलेशन, macOS 13 या बाद के संस्करण को लक्ष्य बनाने वाला macOS SwiftUI ऐप, और PanelKit नाम का एम्बेडेड डायनामिक Swift फ़्रेमवर्क टार्गेट इस्तेमाल करें। उस फ़्रेमवर्क को ऐप में लिंक और एम्बेड करें। ये उदाहरण परियोजना की पूर्वापेक्षाएँ हैं; फ़्रेमवर्क का नाम किसी मौजूदा उत्पाद की पहचान नहीं करता।

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

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

नीचे दिया गया कोड जोड़ने के बाद Product > Build चुनें। Xcode पहचाने गए लोकलाइज़ किए जा सकने वाले कॉल को कैटलॉग में निकालता है। पुष्टि करें कि workspace.title ऐप कैटलॉग में और panel.ready फ़्रेमवर्क कैटलॉग में, अपेक्षित अंग्रेज़ी स्रोत मानों के साथ दिखाई देता है। कैटलॉग साइडबार के जोड़ने वाले बटन से समर्थित भाषाएँ जोड़ें और संबंधित संदेशों के अनुवाद दर्ज करें। स्ट्रिंग कैटलॉग से टेक्स्ट का लोकलाइज़ेशन और रूपांतरण।

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

हर संदेश को बंडल, की, टेबल और डिफ़ॉल्ट दें

स्थिर उदाहरण कीज़ और पढ़ने योग्य अंग्रेज़ी डिफ़ॉल्ट इस्तेमाल करें। defaultValue स्वीकार करने वाला Swift initializer, प्रदर्शित स्रोत टेक्स्ट से अलग की का समर्थन करता है। बंडल में लोकलाइज़ की गई स्ट्रिंग ढूँढ़ने का लुकअप विफल होने पर उसका डिफ़ॉल्ट लौटाया जाता है। table पैरामीटर स्ट्रिंग टेबल चुनता है; इसे छोड़ने पर Localizable चुना जाता है। String.init(localized:defaultValue:table:bundle:locale:comment:)।

फ़्रेमवर्क के संदेश फ़्रेमवर्क में रखें

यह पूरी Swift स्रोत फ़ाइल डायनामिक PanelKit फ़्रेमवर्क टार्गेट में जोड़ें। मार्कर क्लास उसी टार्गेट में परिभाषित है, ताकि Bundle(for:) उसके बंडल की पहचान करे। Apple इस क्लास-आधारित तरीके को मौजूदा #bundle मैक्रो के विकल्प के रूप में दस्तावेज़ित करता है। अपने ऐप के टेक्स्ट को अनुवाद के लिए तैयार करना।

import Foundation

private final class PanelBundleAnchor: NSObject {}

public enum PanelText {
    public static var resourceBundle: Bundle {
        Bundle(for: PanelBundleAnchor.self)
    }

    public static var ready: String {
        String(
            localized: "panel.ready",
            defaultValue: "Panel ready",
            table: "Localizable",
            bundle: resourceBundle,
            comment: "Status label above the framework panel."
        )
    }
}

ऐप को String लौटाने से पहले फ़्रेमवर्क अपना संदेश ढूँढ़ता है। इससे स्वामित्व की स्पष्ट सीमा बनती है: फ़्रेमवर्क की कोड, स्रोत टेक्स्ट, टेबल और संसाधन बंडल नियंत्रित करता है। ऐप को प्रदर्शित करने के लिए तैयार टेक्स्ट मिलता है।

ऐप और फ़्रेमवर्क के संदेश साथ दिखाएँ

बने हुए ऐप एंट्री-पॉइंट फ़ाइल को इस पूरे उदाहरण से बदलें। यह मानता है कि लिंक किए गए फ़्रेमवर्क मॉड्यूल का नाम PanelKit है और उसमें पिछली फ़ाइल मौजूद है। ऐप टार्गेट में केवल एक ऐप एंट्री पॉइंट रखें।

import Foundation
import SwiftUI
import PanelKit

@main
struct FallbackDemoApp: App {
    var body: some Scene {
        WindowGroup {
            VStack(alignment: .leading, spacing: 12) {
                Text(verbatim: String(
                    localized: "workspace.title",
                    defaultValue: "Workspace",
                    table: "Localizable",
                    bundle: .main,
                    comment: "Heading for the main workspace."
                ))

                Text(verbatim: PanelText.ready)
            }
            .padding(24)
        }
    }
}

ऐप का लुकअप स्पष्ट रूप से .main का इस्तेमाल करता है; फ़्रेमवर्क लुकअप अपना संसाधन बंडल इस्तेमाल करता है। दोनों अंग्रेज़ी डिफ़ॉल्ट देते हैं। यह Apple के दस्तावेज़ित बंडल चयन और डिफ़ॉल्ट-वैल्यू पैरामीटर के अनुरूप है। पूरे टार्गेट कॉन्फ़िगरेशन को सत्यापित करने के लिए Xcode में परियोजना बनाएँ और चलाएँ; इन उदाहरणों को यहाँ निष्पादित नहीं किया गया है। String.init(localized:defaultValue:table:bundle:locale:comment:)।

Bundle.localizedString(forKey:value:table:) का उपयोग करने वाले मौजूदा कार्यान्वयन में, यदि अनुपलब्ध की मिलने पर पढ़ने योग्य परिणाम चाहिए, तो एक गैर-खाली और पढ़ने योग्य value दें। Apple दस्तावेज़ित करता है कि value अनुपस्थित या खाली होने पर अनुपलब्ध की स्वयं लौटाई जाती है, और उसके गैर-खाली होने पर value लौटाया जाता है। इसलिए panel.ready जैसी की के लिए स्पष्ट फ़ॉलबैक ज़रूरी है, यदि उस पहचानकर्ता को दिखाना संदेश अनुबंध का उल्लंघन करता हो। localizedString(forKey:value:table:)।

तय करें कि फ़्रेमवर्क अलग भाषाएँ चुन सकते हैं या नहीं

सही बंडल पास करने से यह तय होता है कि कहाँ खोज करनी है। मिश्रित-लोकलाइज़ेशन कॉन्फ़िगरेशन यह प्रभावित करता है कि लोकलाइज़ेशन चयन का संबंध उसमें शामिल ऐप से कैसे है। फ़्रेमवर्क से लोकलाइज़ की गई स्ट्रिंग पाने के लिए Apple CFBundleAllowMixedLocalizations नाम का Boolean विकल्प उपलब्ध कराता है, जो Localized resources can be mixed के रूप में दिखता है। CFBundleAllowMixedLocalizations।

Swift Forums में इस व्यवहार की व्याख्या के अनुसार, ऐप की Info.plist में यह की सक्षम करने से दूसरे बंडल मुख्य ऐप द्वारा समर्थित भाषाओं से आगे के लोकलाइज़ेशन चुन सकते हैं। इस विकल्प के बिना, मुख्य बंडल उनके चयन को सीमित करता है। यह पुरानी व्याख्यात्मक चर्चा है, जो Apple के मौजूदा की संदर्भ के साथ उपयोगी है। Swift पैकेज मैनेजर लोकलाइज़ेशन।

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

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

इस String initializer के locale आर्ग्युमेंट को अनुवाद-भाषा बदलने के स्विच के रूप में इस्तेमाल न करें। Apple स्पष्ट रूप से दस्तावेज़ित करता है कि यह इंटरपोलेट किए गए मानों, जैसे संख्याओं, के लोकलाइज़ेशन को नियंत्रित करता है और लोकलाइज़ की गई स्ट्रिंग ढूँढ़ने में इस्तेमाल होने वाली लोकेल नहीं बदलता। इस काम के लिए समर्थित भाषा कॉन्फ़िगरेशन और जाँच प्रक्रियाएँ इस्तेमाल करें। String.init(localized:defaultValue:table:bundle:locale:comment:)।

अनुपलब्ध भाषाओं और अनुपलब्ध संदेशों की अलग-अलग जाँच करें

Product > Scheme > Edit Scheme के ज़रिए लोकलाइज़ेशन जाँचें। Run चुनें, Options खोलें, App Language चुनें, डायलॉग बंद करें और Mac ऐप फिर चलाएँ। Apple पूरे सिस्टम की सेटिंग बदले बिना लोकलाइज़ेशन आज़माने के लिए यह प्रक्रिया दस्तावेज़ित करता है। केवल भाषा से जुड़ी समस्या की जाँच करते समय क्षेत्र का चयन अपरिवर्तित रखें। ऐप चलाते समय लोकलाइज़ेशन की जाँच करना।

नीचे दी गई परीक्षण मैट्रिक्स को परियोजना-विशिष्ट निदान सहायता के रूप में इस्तेमाल करें। बंडल-रूटिंग की जाँच के लिए, समर्थित गैर-स्रोत लोकलाइज़ेशन में अस्थायी रूप से अलग-अलग अंग्रेज़ी परीक्षण चिह्न रखें, जैसे App translation sample और Framework translation sample। ये निदान के लिए सामग्री हैं, अनुवाद या भाषा पहचानकर्ता नहीं।

  1. स्रोत व्यवहार जाँचें। अंग्रेज़ी चयनित रखकर चलाएँ। Workspace और Panel ready अपेक्षित हैं।
  2. अनुवादित संसाधनों की रूटिंग जाँचें। समर्थित परीक्षण लोकलाइज़ेशन चुनें। दोनों स्वामी कैटलॉग के अलग-अलग चिह्न अपेक्षित हैं।
  3. अनुपलब्ध संदेश का डिफ़ॉल्ट जाँचें। अलग रखे गए परीक्षण संपादन में, फ़्रेमवर्क लुकअप की को panel.ready.probe में बदलें, defaultValue को अपरिवर्तित रखें और सुनिश्चित करें कि जाँच वाली प्रविष्टि परीक्षण कैटलॉग में शामिल न हो। लुकअप विफल होने पर Panel ready अपेक्षित है। इसके बाद मूल की वापस रखें।
  4. असमर्थित भाषा चयन जाँचें। ऐसी पसंदीदा भाषाओं की सूची आज़माएँ जिसमें कोई समर्थित भाषा मेल न खाती हो। जाँचें कि दोनों स्वामी बंडल अपने अंग्रेज़ी डेवलपमेंट संसाधन इस्तेमाल करते हैं। पहली पसंद असमर्थित और उसके बाद दूसरी पसंद समर्थित होने की स्थिति भी जाँचें, क्योंकि उसका अपेक्षित परिणाम अलग है।
  5. मिश्रित लोकलाइज़ेशन सक्षम होने पर उसकी जाँच करें। ऐसी भाषा आज़माएँ जो केवल फ़्रेमवर्क में उपलब्ध हो। अपेक्षित व्यवहार दर्ज करें और ऐप की मिश्रित-लोकलाइज़ेशन सेटिंग को उसके अनुसार जाँचें।

तीसरी जाँच विफल लुकअप को अलग करती है; चौथी भाषा-मिलान को। केवल बिना अनुवाद वाली कैटलॉग पंक्ति की जाँच करने से ये स्थितियाँ धुँधली हो सकती हैं, क्योंकि परिणामी संसाधन कॉन्फ़िगरेशन भी लुकअप को प्रभावित करता है। अनुपलब्ध की का अपेक्षित परिणाम Swift initializer से आता है, जबकि पसंदीदा भाषा चयन बंडल नियमों के अनुसार होता है। String.init(localized:defaultValue:table:bundle:locale:comment:), बंडल की सामग्री तक पहुँचना।

परिणाम अलग हों, तो वास्तविक स्वामी बंडल की जाँच करें। developmentLocalization CFBundleDevelopmentRegion से मेल खाने वाला मान दिखाता है; preferredLocalizations भाषा प्राथमिकताओं के क्रम में उपलब्ध लोकलाइज़ेशन दिखाता है। इन गुणों की तुलना Bundle.main और PanelText.resourceBundle पर करें। ये कॉन्फ़िगरेशन के निदान में मदद करते हैं, लेकिन हर लुकअप की अंतिम जाँच प्रदर्शित संदेश ही हैं। developmentLocalization, preferredLocalizations।

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

स्रोत