उत्तम अभ्यास

वेब के लिए

Markdown पैटर्न का उपयोग पठनीयता बढ़ाता है और रखरखाव को आसान बनाता है, अनुवादक और आपकी वेबसाइट स्क्रिप्ट दोनों के लिए जो सामग्री को निकालेगी।
बहुभाषी साइट में नामित एंकर के लिए, एक दिलचस्प तरीका Markdown डिज़ाइन के साथ लिंक को सीधे कोड करना है।
उदाहरण: एंकर के साथ <h2/> टैग के लिए

वर्तमान भाषा में लेबल

LLM लिंक को सुरक्षित रखने में इंसानों से ज़्यादा प्रभावी होते हैं, और LSDE आपको विभिन्न भाषाई संस्करणों के बीच समस्याओं का पता लगाने में मदद करता है।
इस प्रकार, आप एक ऐसा लिंक साझा कर सकते हैं जो सभी भाषाओं में काम करेगा और एक अप्रचलित एंकर के प्रतिस्थापन को प्रबंधित करने के लिए LSDE का उपयोग कर सकते हैं।


कोड की अस्पष्टता

डेटा-उन्मुख मॉडल के साथ काम करते समय अस्पष्टताओं से बचें।
उदाहरण :
बुरी प्रथा : 'key' शब्द स्पष्ट नहीं है और इसकी खोज को कठिन बनाता है।

ts
const PRODUCTS: Product[] = [
	{
\t\tid: 'fcf7o',
\t\tlogo: '/icons/fcf7o-icon-40.webp',
\t\tlabel: 'FCF7O',
\t\tkey: 'game:fcf7o.words.game_title',
\t},
\t{
\t\tid: 'lsde',
\t\tlogo: '/icons/lsde-icon-40.webp',
\t\tlabel: '<c1>LSDE</c1>',
\t\tkey: 'software:lsde.name',
\t},
\t{
\t\tid: 'lsge',
\t\tlogo: '/icons/lsge.webp',
\t\tlabel: 'LSGE',
\t\tkey: 'software:lsge.name',
\t},
];


अच्छी प्रथा : एक अद्वितीय और सुसंगत कन्वेंशन अपनाएं।
'i18nKey' शब्द बहुत स्पष्ट है और नियमित अभिव्यक्ति (Regex) के माध्यम से इस मान की सटीक खोज की अनुमति देता है।
ts
const PRODUCTS: Product[] = [
	{
\t\tid: 'fcf7o',
\t\tlogo: '/icons/fcf7o-icon-40.webp',
\t\tlabel: 'FCF7O',
\t\ti18nKey: 'game:fcf7o.words.game_title',
\t},
\t{
\t\tid: 'lsde',
\t\tlogo: '/icons/lsde-icon-40.webp',
\t\tlabel: '<c1>LSDE</c1>',
\t\ti18nKey: 'software:lsde.name',
\t},
\t{
\t\tid: 'lsge',
\t\tlogo: '/icons/lsge.webp',
\t\tlabel: 'LSGE',
\t\ti18nKey: 'software:lsge.name',
\t},
];




आलस्य

बुरी आदतें आलस्य से जन्म लेती हैं।

सामग्री को पुनः प्राप्त करने के लिए संचालन करके कुंजियों को बचाने की कोशिश न करें।
उदाहरण :
javascript
const [title, subtitle] = t( 'game:game.title' ).split( /[:：]/ );

यह एक गलत अच्छी सोच है, क्योंकि कुछ भाषाओं में वर्ण भिन्न हो सकते हैं और शब्दों का क्रम बदल सकता है।



टैग का प्रारूप

डिज़ाइन के लिए सीधे टेक्स्ट में कोड को यथासंभव कम करें, ताकि इसे कोडबेस से नियंत्रित किया जा सके।
उदाहरण के लिए, आप एक छवि का स्थान इंगित कर सकते हैं, लेकिन उसकी शैली या उसे कैसे प्रस्तुत किया जाना चाहिए, यह नहीं।
यदि आपको डिज़ाइन में बदलाव करने हैं, तो आप एक टैग की शैली बदलने के लिए 10 भाषाओं में एक टेक्स्ट का पुन: अनुवाद करने के लिए मजबूर नहीं होना चाहेंगे!

टैग में एक पहचानकर्ता (ID) शामिल हो सकता है, लेकिन अतिरिक्त जानकारी जोड़ना आमतौर पर दृढ़ता से हतोत्साहित किया जाता है और एक बुरी प्रथा है।
उदाहरण : ऐसा न करें
<img src='url' left />
बल्कि ऐसा करें
<img id=1 />
फिर आप कोडबेस में आवश्यक शैलियों को लागू करने के लिए छवि टैग का ID पुनः प्राप्त करेंगे।
ID का उपयोग शाब्दिक रूप से किया जाना चाहिए, न कि उनके अनुक्रमणिका (index) के माध्यम से।
वास्तव में, विभिन्न भाषाओं में, टैग स्थानांतरित हो सकते हैं और प्रारंभिक अनुक्रमणिका से मेल नहीं खा सकते हैं।
प्राकृतिक अनुक्रमणिका का उपयोग डेवलपर के लिए जटिलता भी पैदा करता है; यह अनुमान लगाने की कोशिश करना कि छवि या टैग किस अनुक्रमणिका से मेल खाता है, एक वास्तविक सिरदर्द है।
इसलिए, जब आप उन्हें इंटरपोलेशन के बाद अनुकूलित करना चाहते हैं तो पहचानकर्ता वाले टैग का उपयोग करें।



CSS

किसी साइट के अनुवाद के लिए, जब आपके पास पैराग्राफ होते हैं, तो भाषा बदलने पर दृश्य विस्थापन से बचने के लिए अनुवाद के बाद न्यूनतम ऊंचाई (`min-height`) का विकल्प चुनें।
उदाहरण: `mih={'3lh'}`
यह आपको उस भाषा के आधार पर न्यूनतम ऊंचाई निर्धारित करने की अनुमति देता है जो सबसे अधिक पंक्तियाँ लेती है, जिससे एक सुसंगत और संयमित उपयोगकर्ता अनुभव (UX) सुनिश्चित होता है।

नेमस्पेस


अपनी अनुवाद कुंजियों में हमेशा 'नेमस्पेस' शामिल करें, भले ही आपके पास केवल एक ही क्यों न हो।
यह आपकी कुंजियों को खोजने के लिए Regex पैटर्न स्थापित करना बहुत आसान बनाता है।
उदाहरण: game:a.b.c, common:a.b.c

GIT वर्जन कंट्रोल

.lsde प्रोजेक्ट्स JSON फॉर्मेट की फाइलें हैं, जो Git जैसे टूल के साथ उनके वर्जनिंग को आसान बनाती हैं।
पूर्ण इतिहास और बेहतर सुरक्षा का लाभ उठाने के लिए अपने प्रोजेक्ट को Git रिपॉजिटरी में सहेजना (save करना) दृढ़ता से अनुशंसित है।
हालाँकि LSDE का अपना बैकअप सिस्टम है, फिर भी आपकी डेटा फ़ाइलों के प्रबंधन के लिए Git सबसे अच्छा समाधान है।

संदर्भ और लेखन

प्रत्येक कुंजी (key) के लिए स्पष्ट संदर्भ प्रदान करें
एक स्पष्ट संदर्भ कुंजी के नाम, उसके पथ (hierarchy), उसके आस-पास की कुंजियों (parent/child keys) या उसके मेटाडेटा में हो सकता है।
अस्पष्ट कुंजियों से बचें जो अटकलों की गुंजाइश छोड़ती हैं। यदि किसी कुंजी को समझने के लिए कोड में उसकी उपयोगिता की जांच करने की आवश्यकता पड़ती है, तो इसका मतलब है कि आपके डेटा आर्किटेक्चर में सुधार की आवश्यकता है।

स्पष्ट कुंजियों के उदाहरण:
game:.scenes.001.events.001.1
game:.scenes.001.events.001.2
game:.scenes.the-ice-land.events.the-lost-house.1
game:.scenes.the-ice-land.events.the-lost-house.2
game:.ui.menus.new-game.label
game:.ui.menus.new-game.description

ये कुंजियाँ तुरंत समझने में मदद करती हैं कि वे संवाद (dialogues) या इंटरफ़ेस तत्वों की ओर इशारा कर रही हैं।
पहली दो संख्यात्मक आईडी (IDs) का उपयोग करती हैं: यह उन एक्शन गेम्स के लिए एक प्रभावी तरीका है जहाँ कलात्मक दिशा (DA) लचीली होती है और तकनीकी संरचना को प्रभावित किए बिना विकसित हो सकती है।
अगली दो सिमेंटिक IDs का उपयोग करती हैं: यह उन नैरेटिव गेम्स के लिए अनिवार्य है जहाँ सामग्री कोड के साथ गहराई से जुड़ी होती है। यह कहानी और गेम लॉजिक के बीच के जुड़ाव को बनाए रखता है।
अंतिम दो स्पष्ट रूप से मेनू तत्वों (label और description) का वर्णन करती हैं।

गलत अभ्यासों के उदाहरण:
game:events.001.1 (बहुत अस्पष्ट: इस इवेंट का उपयोग कहाँ किया जाता है?)
game:.scenes-events-the-lost-house.1 (पथ में दोहराव/Redundancy)
game:.ui-menus.new-game-label (अनावश्यक कॉन्सटेनेशन/Concatenation)

पथों (paths) में दोहराव से बचें। यदि आपको सर्च को आसान बनाने की आवश्यकता है, तो अपने JSON डेटा की संरचना को खराब करने के बजाय कॉन्सटेनेटेड कुंजियों वाली टाइप फाइल एक्सपोर्ट करें।

अंतर्निहित संदर्भ (implicit context) पर निर्भरता से बचें
किसी स्ट्रिंग को समझने के लिए कभी भी किसी बाहरी तत्व (स्क्रीन पर स्थिति, रंग, आइकन) पर निर्भर नहीं होना चाहिए।
उदा. : इससे बचें
"जारी रखने के लिए यहाँ क्लिक करें"
इसे प्राथमिकता दें
"भुगतान के लिए आगे बढ़ें"
टेक्स्ट अपने यूजर इंटरफेस (UI) से बाहर निकाले जाने पर भी समझने योग्य होना चाहिए।
कुछ भाषाओं में संभवतः अनुवाद उपलब्ध न हो या क्रिया और टेक्स्ट के स्थान के आधार पर अलग-अलग शब्द विन्यास हो सकते हैं।
एक्शन टेक्स्ट में क्रिया और वस्तु का वर्णन होना चाहिए: "भुगतान पर जाएँ", "PDF रिपोर्ट डाउनलोड करें" न कि बिना किसी स्पष्टता के "यहाँ क्लिक करें" या "अधिक जानें"।

खंडित वाक्यों (segmented sentences) और अत्यधिक मॉडुलैरिटी से बचें
i18n सामग्री के लेखन में प्रोग्रामिंग सिद्धांतों (जैसे S.O.L.I.D.) को लागू न करें। लेखन और कोडिंग अलग-अलग विषय हैं।
टुकड़ों के बजाय पूर्ण वाक्यों को प्राथमिकता दें, क्योंकि प्रत्येक भाषा का अपना सिंटैक्स होता है।
हालाँकि `i18next` जैसे फ्रेमवर्क "nesting" का समर्थन करते हैं, लेकिन यह अक्सर अनावश्यक जटिलता पैदा करता है। यदि किसी बदलाव की आवश्यकता है, तो वाक्य को पूरी तरह से फिर से लिखें। इंटरपोलेशन को नाम या संख्या जैसे सरल वेरिएबल्स तक सीमित रखें।

डिस्प्ले की सीमाएं (UI constraints) बताएं
यदि इंटरफ़ेस में कैरेक्टर की सीमा या लंबाई की कोई बाधा है, तो इसे मेटाडेटा में स्पष्ट करें और एक विज़ुअल (स्क्रीनशॉट या मॉकअप) प्रदान करें।
एक अनुवादक के लिए अपने टेक्स्ट को एक प्रतिबंधित इंटरफ़ेस के अनुसार ढालना, एक प्रोग्रामर द्वारा दुनिया की सभी भाषाओं के लिए UI को डायनेमिक बनाने की तुलना में अधिक सरल है। इस प्रबंधन को लेखक को सौंपना एक बेहतर यूजर एक्सपीरियंस (UX) सुनिश्चित करता है।

अनियंत्रित इमोजी (emojis) का निषेध
अपने टेक्स्ट में सीधे विशेष कैरेक्टर या इमोजी न डालें।
कोड के माध्यम से उनके रेंडरिंग को नियंत्रित करने के लिए वेरिएबल्स (उदा. : <t title=) का उपयोग करें। इमोजी का रेंडरिंग उपयोगकर्ता के ऑपरेटिंग सिस्टम और वातावरण के आधार पर काफी भिन्न होता है।

सांस्कृतिक रूपकों (cultural metaphors) से बचें
जेनेरिक स्ट्रिंग्स में मुहावरों, शब्दों के खेल और स्थानीय रूपकों के उपयोग से बचना चाहिए।
जो एक भाषा में स्पष्ट है, वह दूसरी भाषा में बेतुका या अनुवाद के अयोग्य हो सकता है।

मान लें कि अनुवादक एप्लिकेशन को नहीं देख पा रहा है
ऐसे लिखें जैसे अनुवादक के पास न तो कोड है और न ही UI तक पहुंच।
समझने के लिए जो कुछ भी आवश्यक है वह कुंजी, उसकी पदानुक्रम (hierarchy) या उसके मेटाडेटा में मौजूद होना चाहिए।

I18n तकनीक


नामित और स्पष्ट प्लेसहोल्डर्स (Named and explicit placeholders)
पोजीशनल इंडेक्स (`{0}`, `{1}`) के बजाय नामित प्लेसहोल्डर्स (`{username}`, `{count}`) को प्राथमिकता दें। LSDE वेरिएबल्स के संदर्भ को परिभाषित करने और आपके प्रोजेक्ट के भीतर उनकी ट्रैसेबिलिटी (traceability) सुनिश्चित करने के लिए एक समर्पित सेक्शन प्रदान करता है।

प्रति कॉन्सेप्ट एक प्लेसहोल्डर
प्रत्येक प्लेसहोल्डर एटॉमिक (atomic) होना चाहिए और एक एकल डेटा (नाम, तारीख, संख्या) का प्रतिनिधित्व करना चाहिए। जेनेरिक (generic) या पॉलीमॉर्फिक (polymorphic) वेरिएबल्स से बचें जो अनुवाद और व्याख्या को कठिन बनाते हैं।

RTL (Right-to-Left) कम्पैटिबिलिटी
दाएं-से-बाएं लिखी जाने वाली भाषाओं के लिए डिस्प्ले का पूर्वानुमान लगाएं। स्ट्रिंग में मैन्युअल बदलाव की आवश्यकता के बिना रेंडरिंग (rendering) सहज और संरचनात्मक रूप से सही होनी चाहिए।

कॉन्कैटेनेशन (Concatenation) का निषेध
कई ट्रांसलेशन कीज़ (translation keys) को जोड़कर कभी भी वाक्य न बनाएं। प्रत्येक भाषा के विशिष्ट सिंटैक्स और व्याकरणिक नियमों का सम्मान करने के लिए, हर पूर्ण वाक्य की एक ही विशिष्ट कुंजी (unique key) होनी चाहिए।