ai-i18n-tools

Appearance

एंकर लिंक ​

जब docsOutput.style = "flat" होता है, तो आउटपुट प्रत्येक स्थान-विशेष के लिए पृष्ठों के बीच सापेक्ष पथों को फिर से लिखता है (guide.md → guide.de.md)। एंकर लिंक — पथ के बाद # के साथ सामान्य मार्कडाउन इनलाइन फ़ॉर्म — लक्ष्य फ़ाइल के अंदर एक अनुभाग पर कूदते हैं:

markdown
Read the [installation checklist](setup.md#first-run) before you deploy.

यहां लिंक लक्ष्य setup.md है, और #first-run एंकर है: इसे उस फ़ाइल के अंदर सही शीर्षक पर स्क्रॉल करना चाहिए।

एंकर लिंक पर ध्यान देने की आवश्यकता क्यों है ​

  • rewriteRelativeLinks प्रत्येक स्थान-विशेष के लिए फ़ाइल नाम को ठीक करता है (setup.md → setup.de.md)।
  • कई रेंडरर दृश्यमान शीर्षक टेक्स्ट से # स्लग प्राप्त करते हैं। अनुवाद के बाद, शीर्षक प्रति स्थान-विशेष भिन्न होते हैं, इसलिए एक स्वतः-जनित स्लग बदल सकता है जबकि फिर से लिखा गया लिंक अभी भी #first-run कह सकता है — या आपका अंग्रेजी #… एंकर अब उस स्लग से मेल नहीं खाता है जिसे रेंडरर अनुवादित शीर्षक से बनाता है।
  • परिणाम: पाठक सही फ़ाइल पर उतरते हैं लेकिन गलत लाइन पर, या ब्राउज़र को कोई मिलान शीर्षक नहीं मिलता है।

क्या करें ​

Docusaurus साइटें (पसंदीदा) ​

डॉक्यूसौरस दस्तावेज़ (docsOutput.style = "docusaurus") पर, ai-i18n-tools write-heading-ids से HTML एंकर के बजाय डॉक्यूसौरस के मूल शीर्षक ID को प्राथमिकता दें:

  1. Docusaurus के क्लासिक {#…} प्रत्यय (CommonMark) या MDX टिप्पणी {/* #… */} (.mdx के लिए अनुशंसित) के साथ शीर्षक पंक्ति पर एक स्पष्ट आईडी जोड़ें, उदाहरण के लिए ## TLS configuration {#tls-configuration} या ## TLS configuration {/* #tls-configuration */}। translate-docs के दौरान, केवल दृश्यमान शीर्षक टेक्स्ट मॉडल को भेजा जाता है — आईडी प्रत्यय को पहले हटा दिया जाता है और अनुवादित शीर्षक पंक्ति के अंत में वापस जोड़ दिया जाता है (Docusaurus उस {/* #id */} को अनदेखा कर देता है जो शीर्षक के मध्य में आ जाता है)।
  2. उन शीर्षकों पर आईडी जोड़ने या रीफ्रेश करने के लिए अपने Docusaurus प्रोजेक्ट रूट (अक्सर package.json में जुड़े होने पर pnpm run write-heading-ids) से docusaurus write-heading-ids चलाएँ जिनमें ये नहीं हैं — {/* #… */} रूप के लिए --syntax mdx-comment का उपयोग करें। वैकल्पिक रूप से, उसी docs[] / contentPaths पर ai-i18n-tools write-heading-ids --slug-style mdx-comment चलाएँ। यह कमांड मौजूदा अनुवादित फ़ाइलों में उसी अंग्रेज़ी आईडी को पुनः स्थानांतरित भी करती है (यह अनुवादित शीर्षक को स्लग नहीं करती है) और जब सेगमेंट संख्या मेल खाती है तो मेल खाते हुए कैश्ड सेगमेंट को अपडेट करती है, ताकि बाद का sync --force-update सुधारी गई आईडी को बनाए रखे। शीर्षकों का नाम बदलने के बाद इसे पुनः चलाएँ ताकि पुरानी आईडी वर्तमान शीर्षकों से मेल खा सकें।

अपने मार्कडाउन एंकर लिंक को उन स्थिर ID पर इंगित करें, जैसे [label](other.md#tls-configuration), जहाँ फ़्रैगमेंट {#…} या {/* #… */} ID से मेल खाता है — केवल अंग्रेजी शब्दों से अनुमानित स्लग से नहीं। इस पैटर्न का उपयोग करने वाले प्रतिबद्ध दस्तावेज़ों के लिए examples/docusaurus-docs देखें।

अन्य लेआउट (फ्लैट, स्टारलाइट, वाइटप्रेस, आदि) ​

जब आप Docusaurus पर नहीं हैं, या आपको {#…} / {/* #… */} प्रत्ययों के बजाय HTML एंकर की आवश्यकता है:

  1. translate-docs से पहले अपने स्रोत .md / .mdx पर ai-i18n-tools write-heading-ids चलाएँ (हमेशा की तरह समान docs[] / contentPaths)। यह प्रत्येक शीर्षक से पहले वाली पंक्ति पर स्पष्ट HTML एंकर्स डालता है ताकि id मान प्रत्येक अनुवादित प्रति द्वारा साझा किए जाएँ, और यह उन समान अंग्रेज़ी आईडी को मौजूदा अनुवादित फ़ाइलों में कॉपी करता है। जब सेगमेंट संख्या मेल खाती है, तो मेल खाता हुआ कैश्ड सेगमेंट भी अपडेट हो जाता है, ताकि बाद का sync --force-update सुधारी गई आईडी को बनाए रखे। शीर्षकों का नाम बदलने के बाद इसे पुनः चलाएँ ताकि पुरानी एंकर आईडी रीफ्रेश होकर वर्तमान शीर्षक से मेल खा सकें।
  2. अपने मार्कडाउन एंकर लिंक्स को उन स्थिर आईडी की ओर इंगित करें, उदाहरण के लिए [label](other.md#section-id), जहाँ section-id उस एंकर से मेल खाता है जो टूल ने लिखा है — न कि केवल अंग्रेज़ी शब्दों से लगाया गया अनुमान।

उदाहरण ​

Docusaurus {#…} / {/* #… */} प्रत्यय ​

docs/overview.md:

markdown
See [TLS setup](security.md#tls-configuration) for certificate steps.

docs/security.md (अंग्रेजी स्रोत, क्लासिक):

markdown
## TLS configuration {#tls-configuration}

Your CA and cert steps…

या MDX-पसंदीदा टिप्पणी फ़ॉर्म:

markdown
## TLS configuration {/* #tls-configuration */}

Your CA and cert steps…

translate-docs के बाद, लिंक खंड प्रत्येक स्थान-विशेष में #tls-configuration रहता है; केवल शीर्षक टेक्स्ट और लिंक लेबल बदलते हैं:

markdown
Siehe [TLS-Einrichtung](security.md#tls-configuration) für die Zertifikatsschritte.

HTML एंकर (write-heading-ids) ​

docs/overview.md:

markdown
See [TLS setup](security.md#tls-configuration) for certificate steps.

write-heading-ids के बाद docs/security.md (सरलीकृत):

markdown
<a id="tls-configuration"></a>

---

# TLS configuration

Your CA and cert steps…

translate-docs के बाद, फ़ाइल पथ और #… एंकर प्रत्येक स्थान-विशेष फ़ाइल में संरेखित रहते हैं, उदाहरण के लिए:

markdown
Siehe [TLS-Einrichtung](security.de.md#tls-configuration) für die Zertifikatsschritte.

सभी लोकेल में #tls-configuration एंकर समान है क्योंकि id स्रोत में निश्चित है; केवल हेडिंग टेक्स्ट और लिंक लेबल का अनुवाद किया जाता है।

यदि अनुवाद के बाद भी लिंक विफल होते हैं, तो समस्या निवारण देखें।

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

कॉपीराइट © वाल्डेमार स्कुडेलर जूनियर।