मुख्य सामग्री पर जाएं

प्रलेखन उपकरण

प्रलेखन का निर्माण Docusaurus का उपयोग करके किया गया है और यह documentation फ़ोल्डर में स्थित है। प्रलेखन को GitHub Pages पर होस्ट किया जाता है और इसे अब डॉकर कंटेनर छवि में शामिल नहीं किया जाता है।

फ़ोल्डर संरचना​

documentation/
├── docs/              # Documentation markdown files (English source)
│   ├── api-reference/
│   ├── development/
│   ├── installation/
│   ├── migration/
│   ├── release-notes/
│   └── user-guide/
├── i18n/              # Translations (auto-generated by translation workflow)
│   ├── de/            # German
│   ├── es/            # Spanish
│   ├── fr/            # French
│   ├── hi/            # Hindi
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   ├── landing/       # Homepage HTML + CSS (English source; locale copies in landing/i18n/)
│   ├── pages/         # Additional pages (homepage shell, 404)
│   └── theme/         # Swizzled theme (navbar)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
└── package.json       # Dependencies and scripts

अंतरराष्ट्रीयकरण (i18n)​

प्रलेखन डिफ़ॉल्ट लोकेल के रूप में अंग्रेज़ी के साथ डॉकुसॉरस की बिल्ट-इन i18n प्रणाली का उपयोग करता है। अनुवादित सामग्री i18n/{locale}/docusaurus-plugin-content-docs/current/ में रहती है, जो docs/ फ़ोल्डर की संरचना को दर्पित करती है।

  • स्रोत फ़ाइलें: docs/**/*.md (अंग्रेज़ी)
  • अनुवादित फ़ाइलें: i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • यूआई अनुवाद: i18n/{locale}/docusaurus-theme-classic/*.json और अन्य JSON फ़ाइलें
  • स्थानीयकृत स्क्रीनशॉट: i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets, जिसे बेसडायर में pnpm take-screenhots द्वारा उत्पन्न किया गया है।

pnpm write-translations कमांड UI स्ट्रिंग्स (Docusaurus थीम और कस्टम कॉम्पोनेंट्स से) को JSON अनुवाद फ़ाइलों में निकालता है। pnpm translate स्क्रिप्ट (documentation/ से, जो रेपो रूट को डेलिगेट करता है) ai-i18n-tools.config.json के अनुसार मार्कडाउन, JSON, SVGs और लैंडिंग HTML का अनुवाद करने के लिए ai-i18n-tools चलाता है।

डॉक्स होमपेज src/pages/index.tsx द्वारा रैप किया गया src/landing/landing.html है। कॉपी के लिए HTML फ़ाइल संपादित करें; लोकेल कॉपीज़ src/landing/i18n/ के अंतर्गत रहती हैं और pnpm i18n:translate:docs द्वारा जनरेट की जाती हैं।

important

केवल docs/ में मौजूद फ़ाइलों, लैंडिंग सोर्स src/landing/landing.html और i18n/en-GB/ में मौजूद सोर्स JSON फ़ाइलों को ही संपादित करें। i18n/{other-locales}/ के अंतर्गत ट्रांसलेटेड मार्कडाउन और src/landing/i18n/ के अंतर्गत लैंडिंग कॉपीज़ अपने आप जनरेट होती हैं और इन्हें मैन्युअल रूप से संपादित नहीं किया जाना चाहिए।

समर्थित लोकेल​

लोकेलभाषानिर्देशिका
en-GBअंग्रेज़ी (डिफ़ॉल्ट)docs/ (स्रोत)
deजर्मनi18n/de/docusaurus-plugin-content-docs/current/
esस्पेनिशi18n/es/docusaurus-plugin-content-docs/current/
frफ्रेंचi18n/fr/docusaurus-plugin-content-docs/current/
hiहिंदीi18n/hi/docusaurus-plugin-content-docs/current/
pt-BRब्राजीलियाई पुर्तगालीi18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-Hansसरलीकृत चीनीi18n/zh-Hans/docusaurus-plugin-content-docs/current/

प्रलेखन का अनुवाद करें​

प्रलेखन एक एआई-संचालित अनुवाद प्रणाली का उपयोग करता है जो सामग्री (मार्कडाउन फ़ाइलें) और यूआई स्ट्रिंग्स (डॉकुसॉरस और कस्टम घटकों से) दोनों का अनुवाद करता है। स्रोत सामग्री अंग्रेज़ी में है (docs/), और जर्मन, फ्रेंच, स्पेनिश, ब्राजीलियाई पुर्तगाली, हिंदी, और सरलीकृत चीनी के लिए अनुवाद उत्पन्न किए जाते हैं।

अनुवाद कैसे काम करता है​

  1. डॉकुसॉरस यूआई स्ट्रिंग्स: pnpm write-translations थीम/कस्टम स्ट्रिंग्स को i18n/en/*.json में निकालता है।
  2. एआई अनुवाद (OpenRouter; कॉन्फ़िग ai-i18n-tools.config.json में रेपो रूट पर): documentation/ से, pnpm translate रूट i18n:translate स्क्रिप्ट चलाता है (यूआई स्ट्रिंग्स, एसवीजी, डॉकुसॉरस मार्कडाउन/JSON, और डिफ़ॉल्ट अधिसूचना टेम्पलेट) को documentation/i18n/, src/locales/, और src/locales/templates/ में जैसा कॉन्फ़िगर किया गया है।
  3. निर्माण: pnpm build documentation/build/ के अधीन सभी लोकेल के लिए स्थैतिक HTML उत्पन्न करता है।

अनुवाद चल रहा है​

cd documentation
pnpm translate          # Same as repo root: i18n:translate (ui + svg + docs + json)
pnpm translate:docs
pnpm translate:json
pnpm translate:svg
pnpm translate:ui
pnpm translate:status

सीएलआई झंडियाँ ai-i18n-tools द्वारा परिभाषित की गई हैं; रेपो रूट से pnpm exec ai-i18n-tools --help चलाएं या अनुवाद कार्यप्रवाह देखें।

मैनुअल अनुवाद ओवरराइड​

documentation/glossary-user.csv संपादित करें (और वैकल्पिक रूप से रेपो रूट पर .translation-cache/ के तहत स्टेल प्रविष्टियां साफ़ करें), फिर संबंधित pnpm translate:* कमांड पुनः चलाएं।

सामान्य कमांड​

सभी कमांड को documentation निर्देशिका से चलाया जाना चाहिए:

विकास​

किसी विशिष्ट लोकेल के लिए हॉट-रीलोड के साथ विकास सर्वर प्रारंभ करें:

cd documentation
pnpm start:en    # English (default)
pnpm start:fr    # French
pnpm start:de    # German
pnpm start:es    # Spanish
pnpm start:pt-br # Brazilian Portuguese

साइट http://localhost:3000/duplistatus/ पर उपलब्ध होगी (या अगला उपलब्ध पोर्ट)। /duplistatus/ पथ गिटहब पेजेस baseUrl और ऐप के भीतर सहायता बटन लिंक्स से मेल खाता है।

बिल्ड​

उत्पादन के लिए दस्तावेज़ीकरण साइट बनाएं:

cd documentation
pnpm build

यह documentation/build निर्देशिका में स्थैतिक एचटीएमएल फ़ाइलें उत्पन्न करता है।

सर्व करें उत्पादन बिल्ड​

स्थानीय रूप से उत्पादन बिल्ड का पूर्वावलोकन करें:

cd documentation
pnpm serve

यह documentation/build निर्देशिका से बनाई गई साइट को सर्व करता है।

अन्य उपयोगी कमांड​

  • pnpm clear - डोकुसॉरस कैश साफ़ करें
  • pnpm typecheck - टाइपस्क्रिप्ट टाइप जांच चलाएं
  • pnpm write-heading-ids - डोकुसॉरस एमडीएक्स टिप्पणी सिंटैक्स का उपयोग करके मार्कडाउन में स्पष्ट {/* #id */} शीर्षक एंकर लिखें (अनुवादों के पार स्थिर लिंक के लिए documentation/ से चलाएं)। सीएलआई h1 शीर्षकों को छोड़ देता है, जिसका उपयोग डोकुसॉरस साइडबार लेबल के रूप में करता है।

जनरेटिंग README.md​

प्रोजेक्ट की README.md फ़ाइल स्वचालित रूप से documentation/docs/intro.md से उत्पन्न होती है ताकि गिटहब रिपॉजिटरी का रीडमी डोकुसॉरस दस्तावेज़ीकरण के साथ सिंक्रनाइज़ रहे।

README.md फ़ाइल बनाने या अपडेट करने के लिए:

./scripts/generate-readme-from-intro.sh

यह स्क्रिप्ट:

  • package.json से वर्तमान संस्करण निकालती है और एक संस्करण बैज जोड़ती है
  • documentation/docs/intro.md से सामग्री कॉपी करती है
  • डॉकुसॉरस सलाह (नोट, टिप, चेतावनी, आदि) को गिटहब शैली के अलर्ट में परिवर्तित करती है
  • सभी सापेक्ष डॉकुसॉरस लिंक को निरपेक्ष गिटहब डॉक्स यूआरएल (https://wsj-br.github.io/duplistatus/...) में परिवर्तित करता है
  • गिटहब संगतता के लिए /img/ से documentation/static/img/ के लिए छवि पथ परिवर्तित करता है
  • माइग्रेशन महत्वपूर्ण ब्लॉक को हटा देता है और डॉकुसॉरस डॉक्स पर लिंक के साथ एक माइग्रेशन जानकारी अनुभाग जोड़ता है
  • doctoc का उपयोग करके एक विषय सूची उत्पन्न करता है
  • डॉकर हब संगत प्रारूपण के साथ README_dockerhub.md उत्पन्न करता है (छवियों और लिंक को निरपेक्ष यूआरएल में परिवर्तित करता है, गिटहब अलर्ट को इमोजी आधारित प्रारूप में परिवर्तित करता है)
  • documentation/docs/release-notes/VERSION.md से RELEASE_NOTES_github_VERSION.md (लिंक और छवियों को निरपेक्ष यूआरएल में परिवर्तित करता है) के लिए गिटहब रिलीज नोट्स उत्पन्न करता है

डॉकर हब के लिए रीडमी अपडेट करें​

generate-readme-from-intro.sh स्क्रिप्ट स्वचालित रूप से डॉकर हब संगत प्रारूपण के साथ README_dockerhub.md उत्पन्न करती है। यह:

  • README.md को README_dockerhub.md पर कॉपी करता है
  • सापेक्ष छवि पथ को निरपेक्ष गिटहब रॉ यूआरएल में परिवर्तित करता है
  • सापेक्ष दस्तावेज़ लिंक को निरपेक्ष गिटहब ब्लॉब यूआरएल में परिवर्तित करता है
  • बेहतर डॉकर हब संगतता के लिए गिटहब शैली के अलर्ट ([!NOTE], [!WARNING], आदि) को इमोजी आधारित प्रारूप में परिवर्तित करता है
  • सुनिश्चित करता है कि सभी छवियां और लिंक डॉकर हब पर सही ढंग से काम करें

गिटहब रिलीज नोट्स उत्पन्न करें​

generate-readme-from-intro.sh स्क्रिप्ट चलाए जाने पर स्वचालित रूप से गिटहब रिलीज नोट्स उत्पन्न करती है। यह:

  • documentation/docs/release-notes/VERSION.md से रिलीज नोट्स पढ़ता है (जहां संस्करण package.json से निकाला जाता है)
  • शीर्षक को "# संस्करण xxxx" से "# रिलीज नोट्स - संस्करण xxxxx" में बदल देता है
  • निरपेक्ष मार्कडाउन लिंक को निरपेक्ष गिटहब डॉक्स यूआरएल (https://wsj-br.github.io/duplistatus/...) में परिवर्तित करता है
  • रिलीज विवरण में उचित प्रदर्शन के लिए गिटहब रॉ यूआरएल (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) के लिए छवि पथ परिवर्तित करता है
  • ../ उपसर्ग के साथ सापेक्ष पथ संभालता है
  • निरपेक्ष यूआरएल (http:// और https://) को अपरिवर्तित रखता है
  • प्रोजेक्ट रूट में RELEASE_NOTES_github_VERSION.md बनाता है

उदाहरण:

# This will generate both README.md and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

उत्पन्न रिलीज़ नोट्स फ़ाइल को सीधे GitHub रिलीज़ विवरण में कॉपी और पेस्ट किया जा सकता है। GitHub रिलीज़ संदर्भ में सभी लिंक और छवियाँ सही ढंग से काम करेंगी।

दस्तावेजीकरण के लिए स्क्रीनशॉट लें​

pnpm take-screenshots

या सीधे चलाएं: pnpm take-screenshots (यदि आवश्यक हो तो वातावरण चर के लिए --env-file=.env का उपयोग करें)।

यह स्क्रिप्ट स्वचालित रूप से दस्तावेजीकरण उद्देश्यों के लिए एप्लिकेशन के स्क्रीनशॉट लेती है। यह:

  • ईएनवी और स्वास्थ्य जांच के बाद, चलाता है pnpm exec playwright install ताकि प्लेव्राइट ब्राउज़र मौजूद रहें
  • एक हेडलेस ब्राउज़र (प्लेव्राइट क्रोमियम) लॉन्च करता है
  • एडमिन और सामान्य उपयोगकर्ता के रूप में लॉग इन करता है
  • विभिन्न पृष्ठों के माध्यम से नेविगेट करता है (डैशबोर्ड, सर्वर विवरण, सेटिंग्स, आदि)
  • विभिन्न व्यूपोर्ट आकारों पर स्क्रीनशॉट लेता है
  • स्क्रीनशॉट को documentation/static/assets/ (अंग्रेजी) या documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (अन्य लोकेल) में सहेजता है

आवश्यकताएं:

  • विकास सर्वर http://localhost:8666 पर चल रहा होना चाहिए
  • वातावरण चर सेट किए जाने चाहिए, अपनी .env फ़ाइल में इन्हें जोड़ें या निर्यात करें:
    • ADMIN_PASSWORD: एडमिन खाते के लिए पासवर्ड
    • USER_PASSWORD: सामान्य उपयोगकर्ता खाते के लिए पासवर्ड

विकल्प: --locale एक या अधिक लोकेल (अल्पविराम द्वारा अलग) तक स्क्रीनशॉट सीमित करता है। यदि छोड़ दिया जाता है, तो सभी लोकेल कैप्चर किए जाते हैं। मान्य लोकेल: en-GB, de, fr, es, pt-BR, hi, zh-Hans। उपयोग प्रिंट करने के लिए -h या --help का उपयोग करें।

उदाहरण:

export ADMIN_PASSWORD="your-admin-password"
export USER_PASSWORD="your-user-password"
pnpm take-screenshots
# All locales (default):
pnpm take-screenshots
# Single locale:
pnpm take-screenshots --locale en-GB
# Multiple locales:
pnpm take-screenshots --locale en-GB,de,pt-BR

दस्तावेज़ीकरण को डिप्लॉय करना​

गिटहब पेजेज पर दस्तावेज़ीकरण डिप्लॉय करने के लिए, आपको एक गिटहब व्यक्तिगत पहुंच टोकन उत्पन्न करने की आवश्यकता होगी। गिटहब व्यक्तिगत पहुंच टोकन पर जाएं और repo स्कोप के साथ एक नया टोकन बनाएं।

जब आपके पास टोकन हो, तो इसे गिट क्रेडेंशियल स्टोर में संग्रहीत करें (उदाहरण के लिए git config credential.helper store का उपयोग करके या अपने सिस्टम के क्रेडेंशियल प्रबंधक का उपयोग करके)।

फिर, गिटहब पेजेज पर दस्तावेज़ीकरण को डिप्लॉय करने के लिए, documentation निर्देशिका से निम्नलिखित कमांड चलाएँ:

pnpm run deploy

यह दस्तावेज़ीकरण का निर्माण करेगा और इसे रिपॉजिटरी की gh-pages शाखा पर पुश करेगा, और दस्तावेज़ीकरण https://wsj-br.github.io/duplistatus/ पर उपलब्ध होगा।

दस्तावेज़ीकरण के साथ काम करना​

पूर्ण अनुवाद कार्यप्रवाह (शब्दावली प्रबंधन, एआई अनुवाद, कैश प्रबंधन) के लिए, अनुवाद कार्यप्रवाह देखें।

स्रोत फ़ाइलें​

  • दस्तावेज़ीकरण सामग्री: documentation/docs/ में अंग्रेजी मार्कडाउन फ़ाइलें
  • यूआई अनुवाद: documentation/i18n/en/ में अंग्रेजी JSON फ़ाइलें (pnpm write-translations द्वारा स्वतः उत्पन्न)
  • साइडबार नेविगेशन: documentation/sidebars.ts
  • डोकुसॉरस कॉन्फ़िगरेशन: documentation/docusaurus.config.ts
  • कस्टम रिएक्ट घटक: documentation/src/components/
  • स्थैतिक संपत्तियाँ: documentation/static/
  • मुख्य मुखपृष्ठ: documentation/docs/intro.md (README.md उत्पन्न करने के लिए स्रोत)

नए घटक जोड़ना​

  1. documentation/src/components/ में अपना रिएक्ट घटक बनाएँ
  2. एमडीएक्स में उपलब्ध बनाने के लिए इसे documentation/src/theme/MDXComponents.js से निर्यात करें
  3. यदि घटक में अनुवाद योग्य यूआई स्ट्रिंग्स शामिल हैं, तो उन्हें निकालने के लिए pnpm write-translations चलाएँ
  4. सभी स्थानीय भाषाओं में नई स्ट्रिंग्स का अनुवाद करने के लिए pnpm translate चलाएँ

नए दस्तावेज़ीकरण पृष्ठ जोड़ना​

  1. documentation/docs/ में एक नई .md फ़ाइल बनाएँ (या एक उपनिर्देशिका में)
  2. documentation/sidebars.ts में साइडबार में इसे जोड़ें
  3. अनुवाद फ़ाइल संरचना को अपडेट करने के लिए pnpm write-translations चलाएँ
  4. शीर्षक आईडी (एंकर) उत्पन्न करने के लिए pnpm write-heading-ids चलाएँ
  5. सभी स्थानीय भाषाओं में नए पृष्ठ का अनुवाद करने के लिए pnpm translate चलाएँ
  6. बिल्ड करें और जाँचें: pnpm build

स्थैतिक संपत्तियाँ​

  • छवियाँ: documentation/static/img/ में रखें और मार्कडाउन में /img/filename.png के साथ संदर्भित करें
  • डाउनलोड/पीडीएफ: documentation/static/ में रखें और /filename.pdf के साथ संदर्भित करें
  • स्थानीय भाषा के अनुसार संपत्तियाँ: यदि किसी संपत्ति को स्थानीय भाषा विशिष्ट होने की आवश्यकता है (उदाहरण के लिए, स्क्रीनशॉट), तो इसे documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/ में रखें

बिल्ड और जाँचें​

cd documentation
pnpm build            # Builds all locales
pnpm serve            # Preview the built site locally
pnpm start:en         # Development server for English
pnpm start:pt-br      # Development server for Portuguese

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