Manual:जादुई शब्द

This page is a translated version of the page Manual:Magic words and the translation is 90% complete.

Outdated translations are marked like this.

Extensions:

जादुई शब्द कई विकिटेक्स्ट स्ट्रिंग्स को एक ID से मानचित्रित करने की तकनीक है जिसे एक फ़ंक्शन से संबद्ध किया जाता है। वेरिएबल्स और पार्सर फ़ंक्शन्स, दोनों इस तकनीक का इस्तेमाल करते हैं। उस ID पर मानचित्रित सभी टेक्स्ट को फ़ंक्शन के लौटाए वैल्यू से बदल दिया जाएगा। टेक्स्ट स्ट्रिंग्स और ID के बीच का मानचित्रण $wgExtensionMessagesFiles[] की मदद से लोड किए जाने वाले एक फ़ाइल के $magicWords वेरिएबल में रखा जाता है।

डिफ़ॉल्ट जादुई शब्द CoreParserFunctions.php में लागू किए जाते हैं।

जादुई शब्द कैसे काम करते हैं

जब भी मीडियाविकि को दो धनुकोष्ठकों ({{XXX ...}}) के अंदर टेक्स्ट मिलती है, इसे तय करना होगा कि XXX वेरिएबल होगी, पार्सर फ़ंक्शन होगी, या कोई साँचा होगा। ऐसा करने के लिए यह कुछ प्रश्न पूछता है।

क्या इसका कोई संबद्ध जादुई शब्द ID है? {{XXX...}} मार्कअप रूप को सुलझाने के पहले चरण पर मीडियाविकि 'XXX' को एक जादुई शब्द ID में बदलने की कोशिश करता है। अनुवाद टेबल को $magicWords से परिभाषित किया जाता है।
- अगर 'XXX' से कोई जादुई शब्द ID संबद्ध नहीं होता है, 'XXX' को एक साँचा मान लिया जाता है।
क्या यह एक वेरिएबल है? अगर जादुई शब्द ID मिल जाती है, मीडियाविकि जाँचता है कि इसमें कोई पैरामीटर है कि नहीं।
- अगर कोई पैरामीटर नहीं मिलते, मीडियाविकि जाँचता है कि जादुई शब्द ID को एक वेरिएबल ID के रूप में घोषित किया गया है कि नहीं। इसे जाँचने के लिए यह MagicWord::getVariableIDs() कॉल करके जादुई शब्द सेवाओं की सूची प्राप्त करता है। इस विधि में वेरिएबल ID, वेरिएबल ID-ओं की एक ठोस सूची (Help:Variables देखें) और MagicWordwgVariableIDs हुक से जुड़े सभी फ़ंक्शन्स द्वारा प्रदत्त अनुकूलित वेरिएबल ID-ओं की सूची से प्राप्त किए जाते हैं।
  - अगर जादुई शब्द ID को एक वेरिएबल के रूप में वर्गीकृत किया गया है, वेरिएबल के नाम से संबद्ध वैल्यू प्राप्त करने के लिए मीडियाविकि ParserGetVariableValueSwitch फ़ंक्शन को कॉल करता है।
क्या यह एक पार्सर फ़ंक्शन है? अगर कोई पैरामीटर हैं या फिर जादुई शब्द ID वेरिएबल जादुई शब्द ID-ओं की सूची में मौजूद नहीं है, मीडियाविकि मान लेता है कि जादुई शब्द एक पार्सर फ़ंक्शन या साँचा है। अगर जादुई शब्द ID $wgParser->setFunctionHook($magicWordId, $renderingFunctionName) से घोषित पार्सर फ़ंक्शन्स की सूची में मिल जाती है, इसे एक पार्सर फ़ंक्शन माना जाता है और $renderingFunctionName नामक फ़ंक्शन से रेंडर किया जाता है। वरना इसे साँचा मान लिया जाता है। If the magic word ID is found in the list of parser functions declared via a call to $wgParser->setFunctionHook($magicWordId, $renderingFunctionName), it is treated as a parser function and rendered using the function named $renderingFunctionName. Otherwise, it is presumed to be a template.

प्रथाओं के अनुसार:

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

मगर यह बस एक प्रथा है और इसे (ऐतिहासिक कारणों से) हमेशा लागू नहीं किया जाता है।

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

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

परम्पराओं का पालन करने पर इससे ज़्यादा टकराव नहीं आएँगे।

जादुई शब्द परिभाषित करना

ताकि जादुई शब्द अपना जादू दिखा सके, हमें दो चीज़ें परिभाषित करनी होंगी:

विकिटेक्स्ट और जादुई शब्द ID के बीच मानचित्रण
जादुई शब्द ID और उस जादुई शब्द का विवेचन करने वाले किसी PHP फ़ंक्शन के बीच मानचित्रण।

विकिटेक्स्ट को जादुई शब्द ID-ओं से मानचित्रित करना

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

इस ऐरे का पहले तत्व एक पूर्णांक चिप्पी है जो बताती है कि जादुई शब्द केस-संवेदनशील है कि नहीं। बाकी के तत्व टेक्स्ट की सूची बनाते हैं जिन्हें जादुई शब्द ID से मानचित्रित किया जाएगा। अगर केस-संवेदनशील चिप्पी 0 होती है, ऐरे के नामों को किसी भी प्रकार के केस में पहचाना जाएगा। अगर केस-संवेदनशील चिप्पी 1 होती है, सिर्फ केस के सटीक मेल ही जादुई शब्द ID से संबद्ध किए जाएँगे। अर्थात् प्रारूप है $magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];

यह संबद्धता $wgExtensionMessagesFiles[] की मदद से पंजीकृत एक फ़ाइल में $magicWords की मदद से बनाई जाती है।

नीचे के उदाहरण में एक स्पेनी मीडियाविकि स्थापना में जादुई शब्द ID 'MAG_CUSTOM' को "personalizado", "custom", "PERSONALIZADO", "CUSTOM" और केस के सभी प्रकारों के साथ संबद्ध किया जाएगा। किसी अंग्रेज़ी मीडियाविकि पर सिर्फ "custom" को ही केस के कई प्रकारों में 'MAG_CUSTOM' से मानचित्रित किया जाएगा:

फ़ाइल Example.i18n.magic.php:

<?php

$magicWords = [];

$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, 'custom' ],
];

$magicWords['es'] = [
	'MAG_CUSTOM' => [ 0, 'personalizado' ],
];

extension.json फ़ाइल के हिस्से में:

"ExtensionMessagesFiles": {
	"ExampleMagic": "Example.i18n.magic.php"
}

ध्यान रखें कि "ExampleMagic" उस कुँजी से अलग है जो आप सादे अंतर्राष्ट्रीयकरण फ़ाइल के लिए इस्तेमाल करेंगे (आम तौर पर सिर्फ एक्सटेंशन का शीर्षक, यानी "Example")। "Magic" को जानबूझकर जोड़ा गया है ताकि एक कुँजी दूसरे को ओवर्राइट न कर दे।

इनलाइन PHP में

आप i18n फ़ाइल की जगह इनलाइन PHP के ज़रिए जादुई शब्दों को संबद्ध कर सकते हैं। यह LocalSettings.php में हुक्स परिभाषित करते हुए काम आता है मगर इसका इस्तेमाल एक्सटेंशनों में नहीं किया जाना चाहिए।

MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];

जादुई शब्द ID को एक PHP फ़ंक्शन से मानचित्रित करना

जादुई शब्द ID-ओं को रेंडरिंग फ़ंक्शन्स से मानचित्रित करने का तंत्र इस बात पर निर्भर होता है कि जादुई शब्द का इस्तेमाल एक पार्सर फ़ंक्शन के रूप में किया जाएगा या फिर एक वेरिएबल के रूप में। अधिक जानकारी के लिए कृपया देखें:

स्थानीयकरण

सहायता के लिए Help:जादुई शब्द#स्थानीयकरण देखें।

आप स्थानीयकरण के लिए जादुई शब्दों की परिभाषाओं और प्रयोग के बारे में Manual:Messages API और Manual:Language#Namespaces पर अधिक पढ़ सकते हैं; संदेशों में {{SITENAME}} का इस्तेमाल न करें।

स्वभाव बदलाव (दो अंडरस्कोर वाले जादुई शब्द)

स्वभाव बदलाव जादुई शब्दों के एक विशिष्ट प्रकार हैं। इन्हें उनके दो अंडरस्कोर्स के (न कि दो धनुकोष्ठकों के) उपयोग से पहचाना जा सकता है। उदाहरण: __NOTOC__

ये जादुई शब्द आम तौर पर कोई सामग्री आउटपुट नहीं करते, मगर किसी पृष्ठ का स्वभाव बदलते हैं और/या पृष्ठ पर कोई गुणधर्म सेट करते हैं। इन जादुई शब्दों को MagicWordFactory::mDoubleUnderscoreIDs पर और Help:जादुई शब्द#स्वभाव बदलाव पर सूचीबद्ध किया गया है। ज़्यादातर मानक स्वभाव बदलावों के प्रभावों को Parser::handleDoubleUnderscore() में परिभाषित किया गया है। अगर कोई विशिष्ट प्रभाव परिभाषित नहीं किया जाता है, जादुई शब्द page_props टेबल पर पृष्ठ का एक गुणधर्म जोड़ देगा। इसे जाँचने के लिए यह जाँचा जा सकता है कि $parser->getOutput()->getPageProperty( 'MAGIC_WORD' ) null है या खाली स्ट्रिंग

अनुकूलित स्वभाव बदलाव

यह रहा एक अनुकूलित __CUSTOM__ स्वभाव बदलाव को लागू करने वाला एक एक्सटेंशन

custom/extension.json - यह काफ़ी गौण है, एक असली एक्सटेंशन इससे ज़्यादा फ़ील्ड्स भर देता।

{
	"name": "Custom",
	"type": "parserhook",
	"AutoloadClasses": {
		"MyHooks": "MyHooks.php"
	},
	"Hooks": {
		"GetDoubleUnderscoreIDs": [
			"MyHooks::onGetDoubleUnderscoreIDs"
		],
		"ParserAfterParse": [
			"MyHooks::onParserAfterParse"
		]
	},
	"ExtensionMessagesFiles": {
		"CustomMagic": "custom.i18n.php"
	},
	"manifest_version": 1
}

custom/custom.i18n.php

<?php
$magicWords = [];
$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];

custom/MyHooks.php

<?php
class MyHooks {
	public static function onGetDoubleUnderscoreIDs( &$ids ) {
		$ids[] = 'MAG_CUSTOM';
	}

	public static function onParserAfterParse( Parser $parser, &$text, StripState $stripState ) {
		if ( $parser->getOutput()->getPageProperty( 'MAG_CUSTOM' ) !== null ) {
			// Do behavior switching here ...
			// e.g. If you wanted to add some JS, you would do $parser->getOutput()->addModules( 'moduleName' );
		}
	}
}

ये भी देखें

Help:Magic words - {{PAGENAME}} और {{SERVER}} जैसे वेरिएबलों की सूची
Manual:MagicWord.php