समस्या निवारण

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

कुछ भी अनुवादित नहीं होता — हर वाक्यांश स्रोत भाषा में ही रहता है

जब हर जगह स्रोत टेक्स्ट दिखे, तो लगभग निश्चित है कि SDK इनिशियलाइज़ नहीं हो पाया। इसे जानबूझकर चुपचाप विफल होने के लिए बनाया गया है (आपका UI कभी नहीं टूटना चाहिए), इसलिए एकमात्र स्पष्ट संकेत ब्राउज़र कंसोल में मिलता है — पहले उसे देखें। आम कारण, संभावना के क्रम में:

CORS। SDK का पहला अनुरोध authorize-project होता है; अगर आपका API ऐप के ओरिजिन को allowlist नहीं करता, तो ब्राउज़र उसे ब्लॉक कर देता है और init वहीं रुक जाता है। याद रखें कि ओरिजिन ठीक-ठीक scheme + host + port होता है — localhost:5173 और localhost:5174 अलग-अलग ओरिजिन हैं, और जब डेव सर्वर का सामान्य पोर्ट व्यस्त होता है तो वे दूसरे पोर्ट पर चले जाते हैं। जिन-जिन पोर्ट पर आप वास्तव में डेवलपमेंट करते हैं, उन सभी को allowlist करें।
गलत क्रेडेंशियल। प्रोजेक्ट आईडी / API की न होने या गलत टाइप होने पर वही ऑथराइज़ कॉल विफल हो जाती है। कंसोल में विफल हुआ अनुरोध और URL दिखता है।
आप बेस लोकेल देख रहे हैं। बेस लोकेल में "अनुवाद" ही स्रोत टेक्स्ट होता है — इसलिए कुछ भी बदला हुआ नहीं दिखता। जाँचने के लिए किसी टारगेट लोकेल पर स्विच करें।

CORS की विफलता और उसका समाधान

# The SDK's first call is an authorize-project request.
# If the browser blocks it, NOTHING translates. Check the console for:
Access to fetch at 'https://your-api/api/authorize-project/...'
from origin 'http://localhost:5173' has been blocked by CORS policy

# Fix: allowlist the app's EXACT origin (scheme + host + port) on the API.
CORS_ALLOWED_ORIGINS=http://localhost:5173,https://app.example.com

एक वाक्यांश का अनुवाद नहीं हो रहा (पर बाकी हो रहे हैं)

आपके कोड में मौजूद फ़्रेज़ ही लुकअप कुंजी है — फ़्रेज़ ही कुंजी है। अगर कोई एक फ़्रेज़ स्रोत टेक्स्ट के रूप में दिखता है जबकि उसके आसपास के फ़्रेज़ अनुवादित हैं, तो वह कुंजी प्रोजेक्ट के कैटलॉग में नहीं है:

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

अनुपलब्ध फ़्रेज़ त्रुटि क्यों नहीं देते?

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

डेवलपमेंट में राइट की (key), प्रोडक्शन में सिर्फ़ रीड-ओनली की

# Development — write key: new phrases are discovered,
# registered, and machine-translated as you build.
VITE_LANGSYS_API_KEY=write-key

# Production — read-only key: fetches the finished catalog only.
# Unregistered phrases silently render their source text.
VITE_LANGSYS_API_KEY=read-only-key

मेरा प्लेसहोल्डर जस का तस दिख रहा है — "Hi %name%" या "Hi {name}"

t() कॉल में, प्लेसहोल्डर सिंगल-ब्रेस {name} होते हैं, और इंटरपोलेशन तभी चलता है जब आप पैरामीटर पास करते हैं: t('Hello, {name}!', 'Greetings', { name })।
React, Vue या Svelte में <Translate>/<Phrase> मार्कअप के अंदर प्लेसहोल्डर %name% रूप में लिखें। फ़्रेमवर्क कंपाइलर बिना किसी चिह्न वाले {name} को एक एक्सप्रेशन मानकर SDK के देखने से पहले ही उसे प्रोसेस कर लेता है; %name% कंपाइलेशन के बाद भी बना रहता है और SDK कैप्चर के समय उसे वापस {name} में सामान्य कर देता है। सादे HTML में सामान्य {name} ठीक है, क्योंकि वहाँ टकराने वाला कोई टेम्पलेट सिंटैक्स नहीं होता।
Params नहीं मिले? अगर कोई params नहीं दिए गए हैं, तो टेम्पलेट जैसा है वैसा ही रेंडर होता है — यही वह शाब्दिक %name% है जो आपको दिख रहा है।

यह काम करता है, लेकिन लोकेल बार-बार बदलने के बाद टूट जाता है

SDK को अपडेट करें। इस क्षेत्र के असली, ठीक किए जा चुके बग: शुरुआती/SSR लोकेल पर लौटने पर पिछला कैटलॉग सक्रिय रह जाता था (langsys-js-typescript 0.2.2 में ठीक किया गया), और कंटेंट-ब्लॉक Translate/Phrase के उपयोगकर्ता सर्वर-सीडेड कैटलॉग पर हमेशा के लिए अटक सकते थे (0.2.3 में ठीक किया गया)। अगर आपको पुरानी लोकेल की स्ट्रिंग या ऐसे ब्लॉक दिखें जो कभी रिज़ॉल्व नहीं होते, तो अपना कोड डीबग करने से पहले अपना इंस्टॉल किया हुआ वर्शन बेस SDK के चेंजलॉग से मिलाकर देखें।

सर्वर-साइड: पेज सुचारु रूप से काम करने के बजाय 500 एरर दे देता है

PHP SDK का क्लाइंट क्रेडेंशियल के बिना बनाने पर एरर देता है — इसलिए जिस Laravel (या सादे PHP) ऐप में LANGSYS_API_KEY खाली हो, वह कंटेनर रेज़ोल्यूशन पर ही फ़ेल हो जाता है, किसी भी अनुवाद के चलने से पहले। क्रेडेंशियल सेट करें (या, यदि ऐप को उनके बिना भी बूट होना है, तो डेमो ऐप्स की तरह एक स्टैंड-इन क्लाइंट बाइंड करें)। क्रेडेंशियल होने के बाद, रनटाइम API विफलताओं में सुचारु गिरावट होती है: पहुँच से बाहर या इनकार करने वाला API सोर्स टेक्स्ट दिखाता है और एक्सेप्शन रिपोर्ट करता है — वह पेज को कभी बंद नहीं करता।

सर्वर-साइड: पहला अनुरोध अटक जाता है, फिर सब कुछ तेज़ चलता है

PHP SDK का HTTP टाइमआउट 30 सेकंड है, और निष्क्रिय अवस्था से जागने वाला API इंस्टेंस पहली ही कॉल पर इसके करीब पहुँच सकता है। वह अनुरोध या तो धीरे-धीरे पूरा होता है (और कैटलॉग कैश को वार्म कर देता है — इसके बाद सब कुछ कैश से परोसा जाता है) या टाइमआउट हो जाता है और स्रोत टेक्स्ट दिखाता है। अगर कुछ देर की निष्क्रियता के बाद आपका पहला पेज लोड धीमा है, तो यही कारण है; यह API के वार्म-अप होने की वजह से है, आपके इंटीग्रेशन की वजह से नहीं।

सर्वर-साइड: मैंने राइट की के साथ रेंडर किया, लेकिन वाक्यांश डैशबोर्ड में नहीं है

खोजे गए फ़्रेज़ अनुरोध के दौरान कतार में रखे जाते हैं और रिस्पॉन्स भेजे जाने के बाद भेजे जाते हैं — यह Laravel का terminable middleware है। पेज लोड होने के कुछ क्षण बाद डैशबोर्ड रीफ़्रेश करें, लोड होने के दौरान नहीं। लंबे समय तक चलने वाले वर्कर रनटाइम (Octane, FrankenPHP, RoadRunner) पर सुनिश्चित करें कि आप SDK के दिए गए इंटीग्रेशन का उपयोग कर रहे हैं — सामान्य PHP शटडाउन हुक वर्कर अनुरोधों के बीच कभी नहीं चलता।

सर्वर रेंडरिंग: एक अनुरोध के अनुवाद दूसरे अनुरोध में रिस जाते हैं

JS बेस SDK एक समय में एक लोकेल का कैटलॉग रखता है — यह मॉड्यूल-स्तर का सिंगलटन है। अलग-अलग लोकेल के लिए एक साथ आने वाले अनुरोधों को रेंडर करने वाले Node सर्वर में रेस की स्थिति बन जाएगी। हर अनुरोध पर कैटलॉग फ़ेच करें और उसी से क्लाइंट को सीड करें, जैसा Next.js, Nuxt और SvelteKit गाइड में दिया गया है, या हर प्रोसेस में एक ही लोकेल चलाएँ।

अब भी समस्या है? SDK के रिपॉज़िटरी में एक इश्यू खोलें — typescript, react, vue, svelte, php या laravel — और साथ में विफल हुए अनुरोध का कंसोल आउटपुट (या सर्वर लॉग) दें। या [email protected] पर लिखें।