कोड, लिंक या फ्रंट मैटर को तोड़े बिना मार्कडाउन फ़ाइलों का अनुवाद कैसे करें

मार्कडाउन फ़ाइल का अनुवाद करने के लिए, गद्य का अनुवाद करें और मशीनरी को अकेला छोड़ दें: फ्रंट मैटर कुंजियाँ, कोड, URL, लिंक लेबल, कंपोनेंट टैग, और फ़ुटनोट लेबल बाइट-दर-बाइट वापस आने चाहिए। फिर तीन चीज़ों की जाँच करें जिन्हें सावधान अनुवाद भी तोड़ देता है: शीर्षकों के लिंक, कोड टिप्पणियाँ, और चीनी, जापानी या कोरियाई में, बोल्ड टेक्स्ट और संख्या श्रेणियों के आसपास का स्थान।

हमने एक 73-पंक्ति वाले MDX पृष्ठ का स्थानीय मॉडल से नौ बार सरलीकृत चीनी में अनुवाद किया, तीन अलग-अलग प्रॉम्प्ट का उपयोग करके, और हर परिणाम को एक स्क्रिप्ट से जाँचा। जिन हिस्सों की लोग आमतौर पर चिंता करते हैं, वे सभी नौ रन में बच गए: कोड, इनलाइन कोड, URL, तालिका, JSX कंपोनेंट, और कार्य सूची। तीन अन्य चीज़ें गलत हो गईं। शीर्षक के लिंक सभी नौ रन में टूट गए। कोड टिप्पणियों का अनुवाद उन सभी छह रन में किया गया जिन्होंने पूरी फ़ाइल भेजी थी, जिनमें तीन रन ऐसे थे जहाँ प्रॉम्प्ट ने कोड को छूने से मना किया था। और जिस प्रॉम्प्ट ने सिंटैक्स को प्लेसहोल्डर्स के पीछे छिपाया, जो सबसे सुरक्षित विकल्प जैसा लगता है, उसने अपने सभी तीन रन में फ्रंट मैटर को तोड़ दिया।

त्वरित उत्तर: क्या अनुवाद करें और क्या छोड़ दें

बाकी सब सामान्य गद्य है: पैराग्राफ, सूची आइटम, टेबल सेल और ब्लॉककोट।

हमने क्या परखा

हमने sample-source.mdx लिखा, जो Shelfmark नामक एक काल्पनिक रीडिंग ऐप के लिए एक दस्तावेज़ीकरण पृष्ठ है। यह Docusaurus और इसी तरह की दस्तावेज़ीकरण साइटों में प्रयुक्त MDX शैली में लिखा गया है, जिसमें ऊपर की तालिका में प्रत्येक संरचना का एक उदाहरण है, साथ ही दो-स्पेस का हार्ड लाइन ब्रेक, एक बोल्ड लिंक, कोष्ठक में समाप्त होने वाला एक बोल्ड वाक्यांश, एन डैश के साथ लिखी गई दो संख्या श्रेणियाँ, और शीर्षक "Keep one glossary for the whole book" के लिए एक इन-पेज लिंक है।

फिर हमने एक स्थानीय मॉडल से इसे तीन तरीकों से सरलीकृत चीनी में अनुवाद करने को कहा:

1. पूरी फ़ाइल। पूरी फ़ाइल पेस्ट करें और अनुवादित फ़ाइल वापस माँगें।
2. निर्देशित। वही, साथ में छह नियम: फ्रंट मैटर कुंजियाँ रखें, कोड के अंदर कुछ न बदलें, URL और संदर्भ परिभाषाएँ रखें, इम्पोर्ट, टैग और टिप्पणियाँ रखें, फुटनोट लेबल और एडमोनिशन मार्कर रखें, और शीर्षक, लिंक टेक्स्ट, alt टेक्स्ट और title एट्रिब्यूट का अनुवाद करें।
3. संरक्षित। कोड, इनलाइन कोड, URL, टैग, टिप्पणियाँ, फुटनोट लेबल, एडमोनिशन मार्कर और फ्रंट मैटर पंक्तियों को ⟦12⟧ जैसे क्रमांकित प्लेसहोल्डर से बदलें, बाकी का अनुवाद करें, फिर मूल को वापस रखें। title और description मान अनुवाद के लिए खुले छोड़े गए थे, और जैसा कि निकला, फ्रंट मैटर की --- पंक्तियाँ और समापन उद्धरण चिह्न भी खुले छूट गए थे।

मॉडल था Qwen 3.6 27B (Q4_K_M) LM Studio में, थिंकिंग बंद और तापमान 0.3, 64 GB मेमोरी वाले Apple M4 Max पर। हमने प्रत्येक स्थिति को तीन बार चलाया, कुल नौ रन, 25 अक्टूबर 2026 को। स्क्रिप्ट है run_llm_markdown_test.py, और सभी नौ आउटपुट बिना संपादन के प्रकाशित हैं; README में हर फ़ाइल सूचीबद्ध है। यदि आपने कभी स्थानीय मॉडल सेट नहीं किया है, तो हमारी स्थानीय LLM अनुवाद मार्गदर्शिका सेटिंग्स को कवर करती है।

यह एक मॉडल, एक भाषा युग्म और एक पृष्ठ का छोटा परीक्षण था। यह दिखाता है कि कौन सी समस्याएँ होती हैं और उन्हें कैसे पकड़ा जाए। यह मॉडलों या प्रॉम्प्टों को रैंक नहीं करता।

परिणाम: सिंटैक्स बच गया; लिंक और निर्णय नहीं बचे

हमने हर आउटपुट को check_markdown_translation.py से जाँचा और प्रत्येक को remark और MDX कंपाइलर से रेंडर किया। पूरा चेकर आउटपुट check-results.txt में है, और results.csv में प्रति रन एक पंक्ति है।

पहली पंक्तियाँ अच्छी खबर हैं। जब हमने पूरी फ़ाइल पेस्ट की, तो इस मॉडल ने Markdown सिंटैक्स को बरकरार रखा; हमें कोड, URL या तालिकाओं में ठीक करने के लिए कुछ नहीं मिला। अंतिम चार पंक्तियाँ वहाँ हैं जहाँ काम है, और साइट बनाते समय उनमें से कोई भी त्रुटि के रूप में नहीं दिखता।

1. अनुवादित शीर्षक उनके लिंक तोड़ देते हैं

नमूना अपने शब्दावली अनुभाग से [glossary section](#keep-one-glossary-for-the-whole-book) के साथ लिंक करता है। प्रत्येक रन ने शीर्षक का अनुवाद किया, जैसा कि होना चाहिए, और प्रत्येक रन ने लिंक लक्ष्य को बनाए रखा, जैसा कि होना चाहिए। परिणाम एक ऐसे ID का लिंक है जो अब मौजूद नहीं है।

अधिकांश Markdown टूल शीर्षक पाठ से शीर्षक ID बनाते हैं। Pandoc का दस्तावेज़ीकरण पहचानकर्ता को "शीर्षक पाठ पर आधारित" बताता है, और Docusaurus चेतावनी देता है कि आप शीर्षक को "मौजूदा ID को अपडेट किए बिना बदलना या अनुवाद करना चाह सकते हैं ताकि लिंक न टूटें।" एक बार शीर्षक 为整本书保留一个术语表 पढ़ा जाए, तो उसका जनरेट किया गया ID चीनी हो जाता है, और #keep-one-glossary-for-the-whole-book कहीं भी स्क्रॉल नहीं करता। पेज अभी भी बनता है, इसलिए कुछ भी आपको नहीं बताता।

आप अनुवाद के बाद लिंक को संपादित करके इसे ठीक नहीं कर सकते। नौ रनों में मॉडल ने एक ही शीर्षक चार अलग-अलग तरीकों से लिखा, इसलिए जनरेट किया गया ID हर पुनःअनुवाद के साथ फिर से बदल जाएगा। समाधान अनुवाद से पहले है: प्रत्येक शीर्षक को जिससे लिंक किया गया है, एक निश्चित ID दें।

• Docusaurus MDX में, ## Keep one glossary for the whole book {/* #keep-one-glossary */} का उपयोग करें। Docusaurus नोट करता है कि पुराना {#id} रूप "अब वैध MDX सिंटैक्स नहीं है," और इसका write-heading-ids कमांड आपके लिए हर दस्तावेज़ में ID जोड़ता है।
• Pandoc में और PHP Markdown Extra का पालन करने वाले Markdown प्रोसेसर में, शीर्षक के अंत में {#keep-one-glossary} का उपयोग करें।

तब ID हर भाषा में समान रहता है, और चेकर इसे लिंक लक्ष्य के रूप में मानता है।

2. कोड टिप्पणियों का अनुवाद हो जाता है, और दृश्यमान स्ट्रिंग का नहीं

नमूने में एक शेल टिप्पणी और एक YAML टिप्पणी है:

library:
  name: "My books"   # shown in the sidebar
  sort: title

पूरी फ़ाइल भेजने वाले सभी छह रनों ने दोनों टिप्पणियों का अनुवाद किया, जिनमें वे तीन भी शामिल हैं जहाँ प्रॉम्प्ट ने कहा था "फेंस्ड कोड ब्लॉक के अंदर कुछ भी न बदलें।" कोड स्वयं सभी नौ रनों में अछूता रहा। इस बीच "My books", जिसे टिप्पणी कहती है कि साइडबार में दिखाया गया है, सभी नौ रनों में अंग्रेज़ी में ही रहा। मॉडल ने वह विपरीत किया जो एक स्थानीयकृत पेज को चाहिए: इसने डेवलपर्स के लिए नोट का अनुवाद किया और पाठकों को दिखने वाला लेबल छोड़ दिया।

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

3. सुरक्षित दिखने वाली विधि ने फ्रंट मैटर को तोड़ दिया

संरक्षित शर्त ने वह किया जो इसने वादा किया था: सभी 32 प्लेसहोल्डर तीनों रनों में वापस आए, इसलिए कोड, URL और टैग पूरी तरह से बहाल हो गए। लेकिन हमारी स्क्रिप्ट ने दो छोटी चीज़ें प्लेसहोल्डर के बाहर छोड़ दीं: फ्रंट मैटर खोलने वाली --- पंक्ति, और अनुवादित शीर्षक और विवरण के बाद बंद होने वाला उद्धरण चिह्न। मॉडल ने उन सभी को तीनों रनों में गिरा दिया। फ़ाइल इस तरह शुरू हुई:

title: "导出您的书库
description: "在更换设备之前，请备份您的笔记和书籍。
slug: export-library

शुरुआती --- के बिना, Markdown पार्सर अब फ्रंट मैटर नहीं देखता। यह छह YAML पंक्तियों और बंद होने वाले --- को एक शीर्षक के रूप में पढ़ता है, इसलिए पेज YAML वाले एक बड़े शीर्षक के साथ खुलेगा। यह अभी भी MDX के रूप में संकलित हुआ। --- वापस रखना भी पर्याप्त नहीं है: YAML पार्सर दो बिना बंद किए उद्धरणों को अस्वीकार करता है।

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

चीनी, जापानी और कोरियाई में बोल्ड टेक्स्ट और रेंज

दो और समस्याएँ हमारे नौ रनों में कभी नहीं आईं, लेकिन उनकी जाँच करना उचित है क्योंकि वे चुपचाप पेज तोड़ देती हैं, और दोनों ने BookTranslator के अपने ब्लॉग को प्रभावित किया है। ब्लॉग MDX में लिखा गया है और 27 भाषाओं में मशीन-अनुवादित है, और एक निर्धारित अनुवाद रन में दो कोरियाई लेख लगातार तीन पुनःप्रयासों में हमारे संरचना जाँच में विफल रहे। कारण नीचे दिए गए दो पैटर्न थे।

विराम चिह्न पर समाप्त होने वाला बोल्ड। CommonMark यह तय करता है कि ** बोल्ड को खोल सकता है या बंद कर सकता है, यह उसके दोनों ओर के अक्षरों को देखकर तय होता है। विराम चिह्न के ठीक बाद आने वाले बंद करने वाले ** के बाद एक स्पेस, विराम चिह्न, या पंक्ति का अंत होना चाहिए; यह राइट-फ्लैंकिंग नियम है। अंग्रेज़ी में वहाँ हमेशा एक स्पेस होता है। चीनी, जापानी और कोरियाई में अक्सर नहीं होता। इसलिए 打开**设置 → 导出（测试版）**并选择 में शाब्दिक तारांकन दिखाई देते हैं, क्योंकि बोल्ड पूर्ण-चौड़ाई वाले कोष्ठक पर समाप्त होता है और उसके ठीक बाद 并 आता है। कोष्ठक के बिना वही पंक्ति बोल्ड में रेंडर होती है, और ** के बाद स्पेस वाली पंक्ति भी। बोल्ड लिंक में भी यही समस्या है, क्योंकि लिंक ) पर समाप्त होता है: 点击**[导出](./export-options.md)**打开 विफल होता है, और कोरियाई **[API](./api.md)**는 भी।

हमारे मॉडल ने संयोग से हर बोल्ड वाक्यांश के दोनों ओर एक स्पेस डाल दिया, इसलिए उसका आउटपुट सही ढंग से रेंडर हुआ। बाद में एक संपादक चीनी टाइपसेटिंग परंपराओं का पालन करने के लिए उन स्पेसों को हटा देता है, तो बग फिर से आ जाता है। आप render-cases.md में सभी सात प्रकारों को आज़मा सकते हैं।

टिल्ड के साथ संख्या सीमाएँ। चीनी और जापानी पाठ अक्सर सीमाओं को 3~5 के रूप में लिखते हैं। remark पर बने GitHub Flavored Markdown साइटें डिफ़ॉल्ट रूप से एकल टिल्ड को स्ट्राइकथ्रू में बदल देती हैं: remark-gfm विकल्प singleTilde true होता है जब तक आप इसे बदल न दें। एक ही पैराग्राफ में दो सीमाएँ, जैसे 需要 3~5 分钟，生成 10~20 MB 的文件夹, उनके बीच के पाठ के साथ स्ट्राइकथ्रू में रेंडर होती हैं। हमारे नमूने में एन डैश का उपयोग किया गया था, और आठ रनों ने उन्हें बनाए रखा जबकि नौवें ने 3 到 5 लिखा। सीमाओं में एन डैश या शब्दों का अनुरोध करें, या अपने remark कॉन्फ़िगरेशन में singleTilde: false सेट करें।

संरचनात्मक चेकर दोनों पैटर्न को चिह्नित करता है। वास्तव में क्या रेंडर होता है, इसकी पुष्टि के लिए, render_check.mjs स्रोत और अनुवाद में बोल्ड, इटैलिक, स्ट्राइकथ्रू, और बचे हुए तारांकनों की गणना करता है, और एक MDX कंपाइल का प्रयास करता है:

npm install @mdx-js/mdx@3 unified@11 remark-parse@11 remark-gfm@4
node render_check.mjs source.mdx translated.mdx

अनुवाद में कम बोल्ड नोड्स या अधिक शाब्दिक तारांकन का अर्थ है कि कुछ ज़ोर बंद होना बंद हो गया।

एक वर्कफ़्लो जो टिकता है

1. पहले हेडिंग आईडी ठीक करें। हर उस हेडिंग में स्पष्ट आईडी जोड़ें जिससे कुछ लिंक करता है, उस सिंटैक्स में जिसे आपका साइट जनरेटर समर्थन करता है। इसे स्रोत भाषा में, एक बार करें, और कुछ भी अनुवादित होने से पहले इसे कमिट करें।

2. फ्रंट मैटर को पेज से बाहर निकालें। केवल पाठक-उन्मुख मानों जैसे title और description का अनुवाद अलग स्ट्रिंग के रूप में करें, और उन्हें मूल YAML में वापस लिखें।

3. कोड नीति तय करें। टिप्पणियाँ अनुवादित हों या नहीं; कॉन्फ़िगरेशन उदाहरणों में प्रदर्शन स्ट्रिंग्स अनुवादित हों या नहीं। इसे अपने अनुवाद शब्दावली में उन उत्पाद नामों के बगल में लिखें जिन्हें नहीं बदलना चाहिए, जैसे हमारे नमूने में Shelfmark।

4. मुख्य भाग का अनुवाद करें। ऐसा उपकरण उपयोग करें जो Markdown को पार्स करता हो, या स्पष्ट नियमों के साथ पूरा पेज भेजें। हमारे परीक्षण में, पूरा पेज भेजने से सिंटैक्स बरकरार रहा; यदि आप प्लेसहोल्डर का उपयोग करते हैं, तो पूर्ण निर्माणों की रक्षा करें और कुछ भी आधा-खुला न छोड़ें।

5. संरचनात्मक जाँच चलाएँ।

   python3 check_markdown_translation.py source.mdx translated.mdx --keep Shelfmark
   

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

6. CJK लक्ष्यों के लिए रेंडरिंग की जाँच render_check.mjs से करें, और विराम चिह्न के बाद आने वाले किसी भी बंद करने वाले ** के बाद एक स्पेस जोड़ें।

7. साइट बनाएँ और लिंक पर क्लिक करें। प्रत्येक भाषा में पेज खोलें, हर इन-पेज लिंक पर क्लिक करें, और कॉन्फ़िगरेशन उदाहरण पढ़ें। सफल बिल्ड केवल यह साबित करता है कि फ़ाइल कंपाइल होती है।

जहाँ सटीकता मायने रखती है, ऐसे दस्तावेज़ीकरण के लिए, हमारे तकनीकी अनुवाद वर्कफ़्लो में दिए गए शब्दावली और समीक्षा चरण इसके ऊपर लागू होते हैं।

BookTranslator कहाँ फिट बैठता है

BookTranslator का TXT अनुवादक .txt, .md, और .mdx फ़ाइलें स्वीकार करता है। उत्पाद पृष्ठ के अनुसार, यह पैराग्राफ, लाइन ब्रेक, विशेष वर्ण, और पाठ संरचना को बनाए रखते हुए उनका अनुवाद करता है, और संदर्भ-जागरूक अनुवाद के लिए बड़ी फ़ाइलों को खंडों में विभाजित करता है, ताकि आप टुकड़ों में पेस्ट करने के बजाय पूरा मैनुअल या Markdown में लिखी पुस्तक अपलोड कर सकें।

उत्पाद पृष्ठ फ्रंट मैटर, कोड ब्लॉकों, या MDX घटकों के लिए विशेष हैंडलिंग का वर्णन नहीं करता, और हमने इस लेख के लिए इस नमूने को BookTranslator के माध्यम से नहीं चलाया। आप जो भी उपकरण उपयोग करें, अनुवाद से पहले चरण 1 से 3 करें और बाद में चरण 5 से 7 करें। निश्चित आईडी के बिना हेडिंग अभी भी अपने लिंक खो देती है, और टिल्ड के साथ लिखी सीमा अभी भी स्ट्राइकथ्रू में बदल जाती है। यदि आप कई भाषाओं में पुस्तक प्रकाशित कर रहे हैं, तो हमारी कई भाषाओं में स्व-प्रकाशन की मार्गदर्शिका उस कार्य के बाकी हिस्से को कवर करती है।

परीक्षण फ़ाइलें प्राप्त करें

इस परीक्षण की सभी चीज़ें पुन: उपयोग के लिए निःशुल्क हैं:

• sample-source.mdx: 73 पंक्तियों का अंग्रेज़ी नमूना;
• check_markdown_translation.py: संरचनात्मक चेकर (केवल Python मानक लाइब्रेरी);
• render_check.mjs और render-cases.md: रेंडरिंग जाँच और सात CJK परीक्षण मामले;
• run_llm_markdown_test.py: किसी भी OpenAI-संगत स्थानीय सर्वर के लिए तीन प्रॉम्प्ट शर्तें;
• outputs फ़ोल्डर में नौ आउटपुट, साथ में check-results.txt और results.csv।