दस्तावेज़
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 Starlight | init -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: दस्तावेज़ों के लिए आरंभ करें
ai-i18n-tools init -t ui-docusaurus -P openaiएस्ट्रो स्टारलाइट दस्तावेज़ साइटों के लिए:
ai-i18n-tools init -t ui-starlight -P cheaperinferenceवाइटप्रेस दस्तावेज़ साइटों के लिए:
ai-i18n-tools init -t ui-vitepress -P anthropicनेविगेशन/साइडबार/फ़ुटर स्ट्रिंग के लिए docsOutput.vitepressThemeCatalog सेट करें - वाइटप्रेस इंटीग्रेशन देखें।
नेक्स्ट्रा दस्तावेज़ साइटों के लिए:
ai-i18n-tools init -t ui-nextra -P geminiथीम डिक्शनरी स्ट्रिंग के लिए docs[].nextraDictionaryPath सेट करें - नेक्स्ट्रा इंटीग्रेशन देखें। साइडबार _meta.ts लेबल स्वचालित रूप से एकत्र किए जाते हैं।
फ़ुमाडॉक्स दस्तावेज़ साइटों के लिए:
ai-i18n-tools init -t ui-fumadocs -P groqUI ओवरराइड के लिए docsOutput.fumadocsUiCatalog सेट करें - फ़ुमाडॉक्स इंटीग्रेशन देखें। साइडबार meta.json लेबल स्वचालित रूप से एकत्र किए जाते हैं।
सादे एस्ट्रो वेबसाइट UI के लिए (कोई स्टारलाइट नहीं):
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: दस्तावेज़ों का अनुवाद करें
ai-i18n-tools translate-docsयह प्रत्येक docs[] ब्लॉक के contentPaths (और Docusaurus कैटलॉग JSON जब docusaurusCatalogDir सेट हो) में सभी फ़ाइलों को सभी प्रभावी दस्तावेज़ स्थानीयकरणों में अनुवादित करता है। पहले से अनुवादित खंड SQLite कैश से परोसे जाते हैं - केवल नए या बदले गए खंड LLM को भेजे जाते हैं।
एकल स्थानीयकरण का अनुवाद करने के लिए:
ai-i18n-tools translate-docs --locale deयह जांचने के लिए कि क्या अनुवाद करने की आवश्यकता है:
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 की रिपोर्ट करता है।
यह देखने के लिए कि कौन से खंड विफल हुए, कितनी बार, और संग्रहीत गुणवत्ता / त्रुटि संदेश, अनुवाद डैशबोर्ड के विफलताएं टैब का उपयोग करें (अनुवाद डैशबोर्ड → विफलताएं)।