Skip to content

दस्तावेज़ ​

translate-docs के लिए संदर्भ, Markdown, MDX, .astro, और docs[] कॉन्फ़िग ब्लॉक में सूचीबद्ध सादे HTML पृष्ठों के लिए पाइपलाइन। प्रत्येक ब्लॉक का contentPaths फ़ील्ड अनुवाद करने के लिए फ़ाइलों या फ़ोल्डरों को सूचीबद्ध करता है। वे फ़ाइलें sourceLocale में लिखी जाती हैं, जो कोई भी भाषा हो सकती है। उदाहरणों में अंग्रेज़ी केवल एक नमूना है। पहली बार किसी साइट में भाषाएँ जोड़ रहे हैं? किसी वेबसाइट या दस्तावेज़ साइट में i18n जोड़ें से शुरू करें। एक रिपॉजिटरी README और अन्य Markdown फ़ाइलें, जो आमतौर पर किसी ऐप के बगल में होती हैं: अपने README और Markdown दस्तावेज़ों में i18n जोड़ें। सादे HTML पृष्ठ (प्रति स्थानीय एक फ़ाइल) HTML पृष्ठ में वर्णित हैं।

फ़्रेमवर्क शेल स्ट्रिंग (navbar, sidebar, theme) एक ही रन में अनुवादित होते हैं, किसी अलग पाइपलाइन द्वारा नहीं। नीचे दी गई तालिका में फ़्रेमवर्क गाइड बताते हैं कि प्रत्येक इसे कैसे करता है: Docusaurus के लिए docusaurusCatalogDir, VitePress के लिए docsOutput.vitepressThemeCatalog, Nextra के लिए docs[].nextraDictionaryPath, Fumadocs के लिए docsOutput.fumadocsUiCatalog। Nextra _meta.ts और Fumadocs meta.json साइडबार लेबल स्वचालित रूप से एकत्र किए जाते हैं। Astro Starlight कई स्थानीय भाषाओं के लिए अंतर्निहित UI स्ट्रिंग के साथ आता है, और वैकल्पिक ओवरराइड docs[] ब्लॉक पर jsonPathTemplate का उपयोग कर सकते हैं।

मार्कडाउन में एम्बेडेड PNG और अन्य रास्टर छवियों के लिए, छवियां और स्क्रीनशॉट देखें। translate-docs केवल वैकल्पिक टेक्स्ट का अनुवाद करता है; यह रास्टर फ़ाइलों की प्रतिलिपि नहीं बनाता है।

README या दस्तावेज़ों में एक वैकल्पिक भाषा स्विचर ब्लॉक के लिए, docsOutput.style को "flat" पर सेट करें - भाषा स्विचर देखें।

SVG फ़ाइलें translate-svg के माध्यम से अनुवादित की जाती हैं जब features.translateSVG सक्षम होता है - docs[] / contentPaths के माध्यम से नहीं।

एक दस्तावेज़ फ्रेमवर्क के शेल/थीम स्ट्रिंग से असंबंधित मनमानी नेस्टेड UI JSON बंडल JSON पाइपलाइन में होते हैं, न कि docs[] में।

प्रत्येक UI ब्लॉक में डिफ़ॉल्ट रूप से दस्तावेज़ीकरण के लिए शब्दावली संकेतों के रूप में इसका strings.json शामिल होता है (uiGlossary, डिफ़ॉल्ट true)। translate-docs उन अनुवादों का पुन: उपयोग LLM प्रॉम्प्ट में संकेतों के रूप में करता है जब किसी सेगमेंट में मेल खाने वाले शब्द दिखाई देते हैं। उस कैटलॉग पर uiGlossary को false पर सेट करें जिसे दस्तावेज़ प्रॉम्प्ट से बाहर रखना चाहिए। वैकल्पिक glossary.userGlossary उत्पाद शब्दों के लिए CSV ओवरराइड जोड़ता है (translate-ui और proofread-ui के साथ साझा किया गया)। संकीर्ण कॉलम में फिट होने के लिए उपयोग किए जाने वाले संक्षिप्त UI-लेबल संक्षेपाक्षर (उदाहरण के लिए Size → Tam) UI अनुवाद के लिए उपलब्ध रहते हैं लेकिन दस्तावेज़ शब्दावली संकेतों से छोड़ दिए जाते हैं। glossary-generate के साथ एक स्टार्टर CSV जनरेट करें, अनुवाद डैशबोर्ड शब्दावली टैब में पंक्तियाँ संपादित करें, या कॉन्फ़िगरेशन — glossary और शब्दावली देखें।

प्रति-स्थानीय मॉडल ओवरराइड ​

translate-docs और sync का डॉक्स स्टेप मॉडल को प्रति टारगेट लोकेल रिज़ॉल्व करते हैं: कॉन्फ़िगर होने पर पहले localeModels(locale), फिर प्रोवाइडर की ग्लोबल translationModels चेन. इसका उपयोग तब करें जब किसी खास भाषा को आपकी डिफ़ॉल्ट फ़ॉलबैक सूची से अलग मॉडल की ज़रूरत हो - उदाहरण के लिए, pt-BR डॉक्यूमेंटेशन के लिए Gemini को प्राथमिकता देना जब ग्लोबल चेन को पुर्तगाली के साथ संघर्ष करना पड़ता है. AI मॉडल और कॉन्फ़िगरेशन - localeModels देखें.

कौन सी गाइड पढ़ें ​

आपका सेटअपयहां से शुरू करें
Docusaurus साइटinit -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus
VitePress साइटinit -t ui-vitepress + थीम के लिए vitepressThemeCatalog - VitePress
Nextra साइटinit -t ui-nextra + डिक्शनरी के लिए nextraDictionaryPath (साइडबार _meta.ts स्वचालित है) - Nextra
Fumadocs साइटinit -t ui-fumadocs + UI के लिए fumadocsUiCatalog (साइडबार meta.json स्वचालित है) - Fumadocs
Astro Starlightinit -t ui-starlight - Astro Starlight
सादे HTML पृष्ठinit -t docs-plain-html - HTML पृष्ठ
फ़्लैट दस्तावेज़ (README, चेंजलॉग, आदि)अपने README और Markdown दस्तावेज़ों में i18n जोड़ें — init -t docs-markdown या --with-readme। लेआउट: आउटपुट लेआउट, भाषा स्विचर
जहाँ अनुवादित फ़ाइलें आती हैंआउटपुट लेआउट
क्रॉस-पेज #anchor लिंकएंकर लिंक
लिंक और एसेट URL रीराइटिंग (regexAdjustments)लिंक रीराइटिंग
दस्तावेज़ों में स्क्रीनशॉटछवियाँ और स्क्रीनशॉट
उत्पाद शब्दावली और यूआई/दस्तावेज़ सुसंगतताकॉन्फ़िगरेशन — glossary, शब्दावली
translate-docs फ़्लैग और कैशCLI विकल्प

चरण 1: दस्तावेज़ों के लिए आरंभ करें ​

bash
ai-i18n-tools init -t ui-docusaurus -P openai

एस्ट्रो स्टारलाइट दस्तावेज़ साइटों के लिए:

bash
ai-i18n-tools init -t ui-starlight -P cheaperinference

वाइटप्रेस दस्तावेज़ साइटों के लिए:

bash
ai-i18n-tools init -t ui-vitepress -P anthropic

नेविगेशन/साइडबार/फ़ुटर स्ट्रिंग के लिए docsOutput.vitepressThemeCatalog सेट करें - वाइटप्रेस इंटीग्रेशन देखें।

नेक्स्ट्रा दस्तावेज़ साइटों के लिए:

bash
ai-i18n-tools init -t ui-nextra -P gemini

थीम डिक्शनरी स्ट्रिंग के लिए docs[].nextraDictionaryPath सेट करें - नेक्स्ट्रा इंटीग्रेशन देखें। साइडबार _meta.ts लेबल स्वचालित रूप से एकत्र किए जाते हैं।

फ़ुमाडॉक्स दस्तावेज़ साइटों के लिए:

bash
ai-i18n-tools init -t ui-fumadocs -P groq

UI ओवरराइड के लिए docsOutput.fumadocsUiCatalog सेट करें - फ़ुमाडॉक्स इंटीग्रेशन देखें। साइडबार meta.json लेबल स्वचालित रूप से एकत्र किए जाते हैं।

सादे एस्ट्रो वेबसाइट UI के लिए (कोई स्टारलाइट नहीं):

bash
ai-i18n-tools init -t ui-astro-website -P ollama

वह टेम्पलेट केवल UI एक्सट्रैक्शन को सक्षम करता है। पृष्ठ HTML अनुवाद के लिए, features.translateDocs भी सेट करें और एक docs[] ब्लॉक जोड़ें (Astro वेबसाइट पृष्ठ (पार्स-और-बदलें) देखें)। examples/astro-website कॉन्फ़िग दोनों पाइपलाइन एक साथ दिखाता है।

जनरेट किए गए ai-i18n-tools.config.json को संपादित करें:

  • provider और providers — init -P <provider> उस प्रीसेट को स्कैफ़ोल्ड करता है; translate-docs या sync से पहले इसकी API कुंजी सेट करें (Ollama को किसी कुंजी की ज़रूरत नहीं है). प्रोवाइडर और API कुंजी, LLM प्रोवाइडर, और AI मॉडल देखें.
  • sourceLocale - स्रोत भाषा (docusaurus.config.js में defaultLocale से मेल खाना चाहिए).
  • targetLocales - BCP-47 लोकेल कोड का ऐरे (उदा. ["de", "fr", "es"]).
  • cacheDir - सभी पाइपलाइनों के लिए साझा SQLite कैश डायरेक्टरी (और --write-logs के लिए डिफ़ॉल्ट लॉग डायरेक्टरी).
  • docs - दस्तावेज़ ब्लॉकों का सरणी। प्रत्येक ब्लॉक में वैकल्पिक description, contentPaths (स्ट्रिंग या सरणी; फ़ाइल, निर्देशिका, या ग्लोब), outputDir, वैकल्पिक docusaurusCatalogDir, docsOutput, वैकल्पिक segmentSplitting, translateFrontmatterFields, protectAttributes, protectKeys, targetLocales, addFrontmatter, आदि होते हैं।
  • docs[].description - रखरखावकर्ताओं के लिए वैकल्पिक छोटा नोट। जब सेट किया जाता है, तो यह translate-docs हेडलाइन और status अनुभाग शीर्षकों में दिखाई देता है।
  • docs[].contentPaths - मार्कडाउन/MDX/.astro स्रोत (और डोक्यूसौरस शेल JSON के लिए वैकल्पिक docusaurusCatalogDir)।
  • docs[].outputDir - उस ब्लॉक के लिए अनुवादित आउटपुट रूट।
  • docs[].docsOutput.style - "nested" (डिफ़ॉल्ट), "flat", "doc-system", या उपनाम "docusaurus" / "astro-starlight" / "vitepress" / "nextra" / "fumadocs" (आउटपुट लेआउट देखें)।
  • ui[].uiGlossary - जब true (डिफ़ॉल्ट), उस ब्लॉक का strings.json दस्तावेज़ सेगमेंट के लिए शब्दावली संकेत प्रदान करता है (कॉन्फ़िगरेशन — ui देखें)।
  • glossary.userGlossary - निश्चित उत्पाद-शब्द अनुवादों के लिए वैकल्पिक CSV; UI पाइपलाइन द्वारा भी उपयोग किया जाता है और शब्दावली डैशबोर्ड टैब में संपादन योग्य है।

प्राथमिक बनाम अनुपूरक: स्थानीयकृत पृष्ठों के लिए contentPaths पर ध्यान दें। जब आपको write-translations से Docusaurus शेल JSON की भी आवश्यकता हो तो docusaurusCatalogDir सेट करें। यदि आप केवल पृष्ठों का अनुवाद करते हैं तो docusaurusCatalogDir को छोड़ दें।

चरण 2: दस्तावेज़ों का अनुवाद करें ​

bash
ai-i18n-tools translate-docs

यह प्रत्येक docs[] ब्लॉक के contentPaths (और Docusaurus कैटलॉग JSON जब docusaurusCatalogDir सेट हो) में सभी फ़ाइलों को सभी प्रभावी दस्तावेज़ स्थानीयकरणों में अनुवादित करता है। पहले से अनुवादित खंड SQLite कैश से परोसे जाते हैं - केवल नए या बदले गए खंड LLM को भेजे जाते हैं।

एकल स्थानीयकरण का अनुवाद करने के लिए:

bash
ai-i18n-tools translate-docs --locale de

यह जांचने के लिए कि क्या अनुवाद करने की आवश्यकता है:

bash
ai-i18n-tools status

फ़्लैग, कैश व्यवहार और बैच प्रॉम्प्ट प्रारूप के लिए, CLI विकल्प देखें।

जटिल मार्कडाउन और विफल गुणवत्ता जांच ​

translate-docs जाँचता है कि प्रत्येक अनुवादित खंड मार्कडाउन संरचना (दस्तावेज़ से पार्स किए गए जोर सहित) को संरक्षित करता है और आंतरिक प्लेसहोल्डर टोकन साफ-सुथरे ढंग से पुनर्स्थापित होते हैं। ऐसे पैराग्राफ जो `inline code` के चारों ओर कई bold स्पैन को स्टैक करते हैं, बोल्ड के अंदर बैकटिक को नेस्ट करते हैं (उदाहरण के लिए `fetch(\`/locales/${code}.json\`)` जैसे टेम्पलेट लिटरल), या एक लंबे वाक्य के माध्यम से बोल्ड और कोड को बुनते हैं, नाजुक होते हैं: कुछ लोकेल को अलग शब्द क्रम की आवश्यकता होती है, जो अनुवाद के बाद ** और ` के संरेखण को बदल सकता है और AST mismatch जैसी सीएलआई त्रुटियों को ट्रिगर कर सकता है।

पुनर्स्थापना के बाद, translate-docs उन खंडों को भी अस्वीकार कर देता है जहाँ HTML टैग प्लेसहोल्डर का पुन: उपयोग किया गया था या उन्हें हटा दिया गया था (इसलिए पुनर्स्थापित टैग अब स्रोत मानचित्र से मेल नहीं खाते हैं) या जहाँ मॉडल ने बचे हुए डबल-ब्रेस टोकन का आविष्कार किया था जो स्रोत में नहीं थे (उदाहरण के लिए एक मनगढ़ंत शब्दावली-शैली टोकन)। पुनर्स्थापना-पूर्व जाँचों के लिए {{…}} टोकन के समान मल्टीसेट और संरचनात्मक टोकन ({{HTM_N}}, चेतावनी मार्कर) के समान क्रमबद्ध अनुक्रम की आवश्यकता होती है; सामग्री टोकन जैसे {{ILC_N}}, {{URL_N}}, और जोर मार्कर जैसे {{SE}} प्राकृतिक शब्द क्रम के साथ आगे बढ़ सकते हैं जब प्रत्येक आईडी/प्रकार की संख्या अभी भी मेल खाती हो। वे विफलताएँ बचे हुए आधिकारिक आंतरिक टोकन के समान मॉडल-फ़ॉलबैक पथ का उपयोग करती हैं।

यदि आपको इस तरह की सत्यापन विफलता का सामना करना पड़ता है, तो स्रोत-भाषा पाठ को सरल बनाने को प्राथमिकता दें - पैराग्राफ को विभाजित करें, एक उदाहरण को एक फेंस किए गए कोड ब्लॉक में ले जाएं, या कम स्तरित बोल्ड/कोड जोड़े के साथ उसी विचार का वर्णन करें - बजाय इसके कि हर मॉडल और स्थानीयकरण से घने इनलाइन मार्कअप को पूरी तरह से पुनरुत्पादित करने की उम्मीद करें।

जब किसी सेगमेंट के लिए आज़माए गए मॉडल AST mismatch के साथ विफल हो जाते हैं, तो translate-docs उस सेगमेंट को स्वचालित रूप से छोटे हिस्सों में विभाजित कर सकता है (पहले सूची का मध्य बिंदु, फिर एकल सूची आइटम या छोटे पैराग्राफ के टुकड़े), प्रत्येक भाग को पहले मॉडल से पुनः प्रयास कर सकता है, और परिणाम को मूल सेगमेंट कैश कुंजी के तहत फिर से जोड़ सकता है। एक ही गुणवत्ता त्रुटि तीन बार आने पर मॉडल सूची जल्दी रुक जाती है; एक अलग त्रुटि आने पर जारी रहती है। यह डिफ़ॉल्ट रूप से चालू है (segmentSplitting.qualityRetrySplit); मॉडल सूची समाप्त होने के बाद इसे रोकने के लिए इसे false पर सेट करें। जब यह फ़ॉलबैक चलता है तो रन सारांश Quality split retries की रिपोर्ट करता है।

यह देखने के लिए कि कौन से खंड विफल हुए, कितनी बार, और संग्रहीत गुणवत्ता / त्रुटि संदेश, अनुवाद डैशबोर्ड के विफलताएं टैब का उपयोग करें (अनुवाद डैशबोर्ड → विफलताएं)।

MIT लाइसेंस के तहत जारी किया गया।