इस पृष्ठ पर

Guidedog / दस्तावेज़ 0.2.0

अंतरराष्ट्रीयकरण

संरचना बनाए रखकर व्याख्या का अनुवाद करें। Guidedog संदेश कैटलॉग निकालता, अनुवाद मिलाता और चुनी भाषा में बिल्ड करता है। स्रोत पाठ संदर्भ रहता है। अनुवाद न हो तो स्रोत दिखता है, नया पाठ नहीं गढ़ा जाता।

काम का क्रम

1. gettext बिल्डर से संदेश टेम्पलेट लिखें:

   guidedog build gettext
   

   हर टेक्स्ट डोमेन का एक टेम्पलेट (.pot) _build/gettext में बनता है। दस्तावेज़ का हर अनुच्छेद, शीर्षक, सूची मद, तालिका सेल, कैप्शन, सूचना, शब्द और फ़ील्ड एक संदेश बनता है। साथ में मूल फ़ाइल और पंक्ति भी दर्ज होती है।

2. sphinx-intl update की तरह हर भाषा के कैटलॉग बनाएँ या अपडेट करें:

   guidedog intl update -l de -l fr
   

   कैटलॉग locales/de/LC_MESSAGES/*.po में बनते हैं। अगली बार कमांड msgmerge की तरह नए टेम्पलेट मिलाता है। अनुवाद बने रहते हैं। मूल संदेश बदलने पर पुराने अनुवाद को समीक्षा के लिए fuzzy चिह्न मिलता है। हटे हुए संदेश अंत में अप्रचलित (#~) रूप में रहते हैं, ताकि लौटने पर अनुवाद मिल सके।

3. हर msgstr भरें। अनुवाद सही होने पर संदेश की #, fuzzy पंक्ति हटाएँ। fuzzy अनुवाद इस्तेमाल नहीं होते।

   msgid "Hello *world*, see the site_."
   msgstr "Hallo *Welt*, siehe site_."
   

4. sphinx-intl stat की तरह अनुवाद का हाल देखें:

   guidedog intl stat -l de
   

5. उस भाषा में बिल्ड करें:

   guidedog build html -D language=de
   guidedog build pdf -D language=de
   

   या conf.toml में language = "de" रखें।

   हर पुस्तक के नाम में भाषा जुड़ती है: manual.pdf से manual-de.pdf बनता है। एक बिल्ड पूरा आउटपुट प्रकाशित करता है; कई संस्करण रखने के लिए अलग लक्ष्य फ़ोल्डर चुनें। जैसे जर्मन के लिए guidedog build -b pdf docs build/books/de -D language=de और अंग्रेज़ी के लिए guidedog build -b pdf docs build/books/en -D language=en।

अन्य इनपुट की तरह केवल बदले कैटलॉग वाले दस्तावेज़ फिर पढ़ते हैं। कैटलॉग जोड़ने या हटाने पर सभी फिर पढ़ते हैं।

guidedog intl में sphinx-intl के विकल्प हैं: टेम्पलेट के लिए -p DIR (डिफ़ॉल्ट _build/gettext), भाषा के लिए बार-बार दिया जा सकने वाला -l LANG (डिफ़ॉल्ट प्रोजेक्ट की भाषा), कैटलॉग के लिए -d DIR (डिफ़ॉल्ट locale_dirs की पहली प्रविष्टि), पंक्ति चौड़ाई के लिए -w N (डिफ़ॉल्ट 76), और --no-obsolete।

अनुवाद लिखना

संदेश पैराग्राफ़, शीर्षक या अन्य तत्व का स्रोत पाठ है, मार्कअप सहित। .rst में reStructuredText और .md में Markdown है। अनुवाद उसी मार्कअप में पढ़ता है, इसलिए मूल की तरह ज़ोर, लिंक और संदर्भ दे सकता है।

संदर्भ समान रहने चाहिए। हर संदर्भ का वही रूप रखें; केवल आसपास का पाठ और उसका शीर्षक बदलें:

msgid "See :ref:`install` and the site_."
msgstr "Siehe :ref:`Installation <install>` und die site_."

अनुवाद से संदर्भ हटे तो बिल्ड Sphinx की तरह चेतावनी (inconsistent references in translated message) देता है और अनुवाद इस्तेमाल करता है। मूल में न मौजूद संदर्भ जोड़ने पर वह हल नहीं हो सकता; तब चेतावनी देकर मूल पाठ रखा जाता है। रीडर अनुवाद का मार्कअप अस्वीकार करे तो भी मूल रहता है और चेतावनी में अनुवाद दिखता है।

खंड एंकर भाषा से नहीं बदलते। अनूदित शीर्षक मूल एंकर रखता है, इसलिए भीतर और बाहर के लिंक चलते रहते हैं।

सेटिंग्स

मानक विकल्प Sphinx के नाम और डिफ़ॉल्ट रखते हैं। अनूदित न होने वाले संदर्भ परिशिष्ट के लिए Guidedog केवल निष्कर्षण पर लागू बहिष्करण भी देता है।

विकल्प	अर्थ
language	बिल्ड की भाषा, जैसे "de" या "pt_BR"।
locale_dirs	सोर्स फ़ोल्डर के सापेक्ष कैटलॉग की जगह। हर जगह LANGUAGE/LC_MESSAGES/DOMAIN.po (या संकलित .mo) होता है। डिफ़ॉल्ट ["locales"] है। कई जगह हों तो संदेश का अनुवाद देने वाली पहली जगह चुनी जाती है।
gettext_compact	तय करता है कि दस्तावेज़ के संदेश किस कैटलॉग में जाएँ। true (डिफ़ॉल्ट): शीर्ष स्तर के हर दस्तावेज़ का अपना कैटलॉग; एक फ़ोल्डर के दस्तावेज़ साझा करते हैं (guide/usage.rst का guide.po)। false: हर दस्तावेज़ का अलग कैटलॉग। कोई नाम दें तो सभी दस्तावेज़ उसी नाम का कैटलॉग साझा करते हैं।
gettext_location	संदेश का स्थान (#: ../../index.rst:12) लिखें। डिफ़ॉल्ट true।
gettext_uuid	हर संदेश के हर स्थान का पहचानकर्ता लिखें। Guidedog दस्तावेज़, संदेश और स्थान से इसे बनाता है, इसलिए हर बिल्ड में समान है।
gettext_auto_build	हर .po को साथ के .mo में कम्पाइल करें, दूसरे टूल के लिए। डिफ़ॉल्ट true है। Guidedog खुद .po पढ़ता है।
gettext_additional_targets	और अनुवाद सामग्री: index (इंडेक्स प्रविष्टियाँ), literal-block, doctest-block, raw और image (वैकल्पिक पाठ)।
gettext_allow_fuzzy_translations	fuzzy अनुवाद भी इस्तेमाल करें। डिफ़ॉल्ट false।
gettext_exclude_patterns	केवल POT निष्कर्षण से हटने वाले दस्तावेज़ पथ पैटर्न, जैसे ["api/**"]। डिफ़ॉल्ट []। दस्तावेज़ HTML और PDF में बने रहते हैं।
gettext_last_translator, gettext_language_team	टेम्पलेट हेडर के Last-Translator और Language-Team।
figure_language_filename	बिल्ड की भाषा में चित्र की फ़ाइल। डिफ़ॉल्ट "{root}.{language}{ext}" है। language = "de" हो तो img/logo.png की जगह img/logo.de.png लिया जाता है, यदि वह मौजूद हो। फ़ील्ड हैं {root}, {path}, {basename}, {ext}, {docpath} और {language}।
translation_progress_classes	अनूदित तत्वों को translated और बाकी को untranslated क्लास दें (true)। केवल एक भी चुन सकते हैं ("translated" या "untranslated"), ताकि स्टाइलशीट बचा हुआ काम दिखा सके।

Guidedog के इंटरफ़ेस के शब्द

Guidedog कुछ पाठ खुद बनाता है: सूचना के शीर्षक, "Added in version 2.1", "Fig. 1", "Contents", पेज के "Previous", "Next", "Navigation", "Search", खोज और सूचकांक के पेज, और पुस्तक का "Version"। ये guidedog टेक्स्ट डोमेन से इस क्रम में खोजे जाते हैं:

1. परियोजना की locales/LANGUAGE/LC_MESSAGES/guidedog.po।
2. परियोजना की locales/LANGUAGE/LC_MESSAGES/sphinx.po, जैसे Sphinx पढ़ता है।
3. Guidedog का बिल्ट-इन कैटलॉग: जर्मन, स्पेनिश, फ़्रेंच, जापानी, ब्राज़ीलियाई पुर्तगाली, रूसी और सरलीकृत चीनी के लिए।

अंग्रेज़ी शब्द संदेश पहचानकर्ता हैं। Sphinx में वही शब्द हो तो उसका पहचानकर्ता भी वही है, इसलिए प्रोजेक्ट का sphinx.po चलता रहता है। अपना guidedog.po किसी शब्द को बदल सकता है या नई भाषा जोड़ सकता है।

टेम्पलेट Sphinx की तरह _(), gettext() और ngettext() से अनुवाद करते हैं:

<small>{{ _('Previous') }}</small>
{{ _('Last updated on %s.')|format(last_updated) }}

conf.toml में न दिए हों तो numfig_format, html_title और html_short_title भाषा के अनुसार बदलते हैं।

तारीख़

|today|, पुस्तक की तारीख और पेज का last_updated Sphinx के नियम से बनते हैं। today_fmt और html_last_updated_fmt में strftime प्रारूप होता है; महीने और दिन के नाम language से आते हैं। %b %d, %Y अंग्रेज़ी में "Sep 29, 2026" और जर्मन में "Sept. 29, 2026" है। खाली प्रारूप _('%b %d, %Y') है, जिसे कैटलॉग अनुवाद कर सकता है। ऊपर की भाषाओं के नाम Unicode CLDR से आते हैं। बाकी में अंग्रेज़ी इस्तेमाल होती है, जैसे Babel को भाषा न पता होने पर Sphinx करता है।

तारीख स्थानीय समय क्षेत्र की होती है। SOURCE_DATE_EPOCH (1970 से बीते सेकंड, UTC में) सेट करने पर हर मशीन पर समान तारीख के साथ पुनरुत्पाद्य बिल्ड बनता है।