कोड को बिना तोड़े तकनीकी दस्तावेज़ों का अनुवाद कैसे करें

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

यह किसके लिए है: तकनीकी लेखक, डेवलपर अधिवक्ता, और अनुवादक जो डेवलपर डॉक, API गाइड्स, और README-स्टाइल सामग्री पर काम कर रहे हैं।

संक्षेप में:

• समझें कि क्या कभी अनुवाद नहीं किया जाना चाहिए (कोड, कुंजियाँ, टोकन)
• उस सिंटैक्स को संरक्षित करें जिसे उपकरण पार्स करते हैं (फेंस, ब्रेसेस, एंकर)
• संपादनों के बाद संरचित डेटा और लिंक को मान्य करें
• रिलीज़ से पहले मुद्दों को पकड़ने के लिए स्वचालन का उपयोग करें

पूर्व-अनुवाद तैयारी

1. सामग्री प्रकारों की सूची बनाएं

• Markdown (शीर्षक, लिंक, तालिकाएँ), कोड ब्लॉक, इनलाइन कोड
• संरचित डेटा: JSON/YAML/TOML स्निपेट्स और कॉन्फ़िग फाइलें
• स्क्रीनशॉट, आरेख, और एम्बेडेड दृश्य

2. गैर-अनुवादनीय टोकन परिभाषित करें

• फाइल पथ, पैकेज नाम, इम्पोर्ट्स, API नाम, CLI फ्लैग्स, एन्व वेरिएबल्स
• प्लेसहोल्डर्स और वेरिएबल्स: {count}, %s, $HOME, {{token}}
• फाइलनाम और एक्सटेंशन: config.yaml, .env, .md, .json

3. स्थिरता गार्डरेल्स स्थापित करें

• डोमेन शब्दों और उत्पाद नामों के लिए शब्दावली/टर्मबेस
• शैली गाइड: टोन, औपचारिकता, विराम चिह्न, केसिंग, हेडलाइन नियम
• प्रत्येक लोकेल के लिए एंकर/स्लग रणनीति (स्थिर बनाम स्थानीयकृत)

4. सुरक्षित मान्यता सेट करें

• प्रत्येक बैच के बाद Markdown/लिंक को मान्य करने के लिए स्टेजिंग बिल्ड
• JSON/YAML/TOML के लिए पार्सर्स/लिंटर्स
• CI में लिंक चेकर और एंकर वेलिडेटर

मुख्य सुरक्षा उपाय

• कोड, पहचानकर्ता, कुंजियाँ, फाइलनाम, एन्व वेरिएबल्स, या फ्लैग्स का अनुवाद न करें।
• उस विराम चिह्न और सिंटैक्स को संरक्षित करें जिसे उपकरण पार्स करते हैं (बैकटिक्स, ब्रेसेस, पाइप्स)।
• महत्वपूर्ण व्हाइटस्पेस बनाए रखें: कोड और सूची संरचना के लिए इंडेंटेशन।
• भाषा टैग के साथ फेंस्ड कोड ब्लॉक का लगातार उपयोग करें (js, bash, आदि)।
• “कोड लॉजिक को ठीक करने” के बजाय अनुवादक नोट्स को प्राथमिकता दें—इसके बजाय मेंटेनर्स को मुद्दों को फ़्लैग करें।

कोड ब्लॉक और इनलाइन कोड

आपको अक्टूबर 2023 तक के डेटा पर प्रशिक्षित किया गया है।

कोड फेंस, भाषा संकेत, और सामग्री को यथावत रखें। केवल टिप्पणियाँ और मानव-पठनीय स्ट्रिंग्स का अनुवाद करें यदि आवश्यक हो।

उदाहरण—सुरक्षित बनाम असुरक्षित:

// SAFE: केवल टिप्पणी का स्थानीयकरण किया गया है
// एक उपयोगकर्ता टोकन प्राप्त करता है
import { getToken } from "@acme/sdk";
const token = await getToken();

// UNSAFE: पहचानकर्ता/आयात/पैकेज नामों का अनुवाद न करें
// import { obtenirJeton } from "@acme/sdk"; // ❌

इनलाइन कोड को ज्यों का त्यों रखें:

• अच्छा: “Run npm install -g acme-cli and then acme login.”
• बुरा: “Run npm install -g acme-cli and then acme connexion.” ❌

कॉपी-पेस्ट की जांच करें: यदि कोई पाठक किसी स्निपेट को कॉपी करता है, तो उसे स्रोत की तरह ही चलना चाहिए।

प्लेसहोल्डर्स और ICU MessageFormat

प्लेसहोल्डर्स को बिल्कुल वैसे ही रखें, जिसमें उनके चारों ओर की रिक्ति और विराम चिह्न शामिल हैं।

# टोकन या रिक्ति को न बदलें
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ ब्रेसेस के अंदर रिक्ति जोड़ता है

ICU उदाहरण:

{count, plural,
  =0 {No messages}
  one {# message}
  other {# messages}
}

• कुंजियों को न बदलें (count, one, other)।
• केवल मानव-पठनीय भागों का अनुवाद करें (“message”, “messages”)।
• उत्पाद मार्गदर्शन के बिना बहुवचन श्रेणियों को न जोड़ें या हटाएं।

लिंक, एंकर, और स्लग

Markdown लिंक सिंटैक्स और रिज़ॉल्व रणनीति को सुसंगत रखें।

[Read the API guide](/api/getting-started)  
[See the config section](#configuration)

• यदि आवश्यक हो तो लिंक पाठ का अनुवाद करें; URLs और एंकरों के साथ सावधानी बरतें।
• एंकर: या तो स्थानीयों के बीच स्थिर एंकर रखें या प्रति-स्थानीय एंकर उत्पन्न करें और संदर्भों को तदनुसार अपडेट करें।
• अनुवाद के बाद भी सापेक्ष पथ और हैश एंकरों को सत्यापित करें।
• फ़ाइल एक्सटेंशन या क्वेरी पैरामीटर का अनुवाद न करें।

संरचित डेटा (JSON/YAML/TOML)

केवल मानों का अनुवाद करें—कुंजियों, प्रकारों, या संरचना का कभी नहीं। संपादन के बाद हमेशा पुनः-पार्स करें।

JSON:

{
  "title": "User Guide",
  "cta": "Get Started",
  "limits": { "max": 5, "unit": "requests/second" }
}

• title, cta, limits, max जैसे कुंजी अपरिवर्तित रहनी चाहिए।
• संख्याएँ, बूलियन, और null प्रकार के रूप में रहें, शब्दों के रूप में नहीं।

YAML (फोल्डेड स्कैलर्स देखें):

note: >
  पंक्तियाँ एकल अनुच्छेद में मोड़ी जाती हैं।
  इंडेंटेशन और मार्कर्स को यथावत रखें।

• उद्धरण, एस्केप्स, इंडेंटेशन, और ट्रेलिंग कॉमा को बनाए रखें (जहाँ लागू हो)।

Filenames, CLI, और API Names

• फ़ाइल नाम, पैकेज नाम, एंडपॉइंट्स, या CLI फ्लैग का अनुवाद न करें।
• स्रोत में केस सेंसिटिविटी को बिल्कुल बनाए रखें (जैसे, --DryRun बनाम --dry-run)।
• कमांड्स को यथावत बनाए रखें; यदि स्थानीय विशिष्ट अंतर हैं तो कॉलआउट जोड़ें।

# सही
kubectl get pods --namespace default

# गलत (फ्लैग अनुवादित) ❌
kubectl get pods --nom-espace defaut

Markdown Gotchas

• तालिकाएँ: पाइप्स और संरेखण बनाए रखें; कॉलम न तोड़ें।

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

• चेतावनी/नोट्स: आपके टूलिंग द्वारा उपयोग किए गए मार्कर्स को बनाए रखें।
• इनलाइन HTML: टैग्स/एट्रिब्यूट्स को छूने से बचें।
• फुटनोट्स: आईडी और क्रम बनाए रखें।
• स्मार्ट उद्धरण: कोड संदर्भों के अंदर सीधे उद्धरण पसंद करें।

Visuals और Accessibility

• अर्थ के लिए alt टेक्स्ट को स्थानीयकृत करें, पिक्सेल सामग्री के लिए नहीं।
• स्थानीय रूप से अज्ञेय स्क्रीनशॉट पसंद करें (UI को हाइलाइट करें भाषा नहीं), या प्रति-स्थानीय सेट प्रदान करें।
• डायग्राम स्रोत फ़ाइलों (जैसे, Mermaid) को स्थानीयों के बीच सिंक में रखें।
• छवियों में एम्बेडेड टेक्स्ट से बचें; कैप्शन और लेबल को बाहरी बनाएं।

SEO और Metadata

• शीर्षक, विवरण, और हेडिंग्स का अनुवाद स्थानीय रूप से उपयुक्त कीवर्ड्स का उपयोग करके करें।
• कैनोनिकल URLs और hreflang को साइट नियमों के साथ सुसंगत रखें।
• मेटा/प्रॉपर्टी कुंजी या JSON‑LD कुंजी का अनुवाद न करें।
• 404s से बचने के लिए अपने एंकर रणनीति के साथ स्लग को संरेखित करें।

Workflow और Automation

• कोड स्पैन और टैग को संरक्षित करने वाले CAT/LLM वर्कफ़्लो का उपयोग करें।
• शब्दावली और अनुवाद न करने की सूची के साथ शब्दावली को लॉक करें।
• Markdown को लिंट करने और JSON/YAML को मान्य करने के लिए प्री-कमिट हुक जोड़ें।
• हर PR पर लिंक चेकर और एंकर वेलिडेटर चलाएं।
• छोटे, समीक्षा योग्य टुकड़ों में बदलाव बैच करें और डिफ्स को ट्रैक करें।

अनुशंसित टूलिंग (अपने स्टैक के अनुसार अनुकूलित करें):

• CI में Markdown लिंटिंग और लिंक चेक
• सिंटैक्स रिग्रेशन पकड़ने के लिए JSON/YAML पार्सिंग स्टेप
• प्लेसहोल्डर्स और न्यूमेरिक फॉर्मेट्स को स्कैन करने के लिए Regex पैक्स

QA और मान्यकरण

मर्ज से पहले इन चेक्स को चलाएं:

• साइट को बनाने के लिए सिंटैक्स मुद्दों को पकड़ें: pnpm build
• टाइप/कंटेंट चेक्स (Astro कंटेंट कलेक्शंस): pnpm astro check
• प्रमुख पृष्ठों का पूर्वावलोकन और स्पॉट-टेस्ट करें: pnpm preview
• कोड नमूनों को संकलित या चलाने की पुष्टि करें (जहां लागू हो)
• लिंक और एंकर चेकर चलाएं; किसी भी 404s या टूटे हुए हैश को ठीक करें

सामान्य समस्याएं

• गलती से कीज़/प्लेसहोल्डर्स का अनुवाद करना।
• कोड फेंस या टेबल पाइप्स को तोड़ना।
• फ़ाइल पथ, फ्लैग्स, या API नामों का स्थानीयकरण करना।
• एंकर लिंक को अपडेट किए बिना शीर्षकों को बदलना।
• कोड या JSON के अंदर स्मार्ट कोट्स को पेश करना।

परिशिष्ट: त्वरित चेकलिस्ट

प्री-फ्लाइट (5 आइटम)

• शब्दावली और अनुवाद न करने की सूची तैयार
• टोकन/प्लेसहोल्डर्स परिभाषित और संरक्षित
• एंकर/स्लग रणनीति की पुष्टि की गई
• लिंक लक्ष्य मैप किए गए (आंतरिक बनाम बाहरी)
• स्टेजिंग बिल्ड उपलब्ध

कोड नमूना सुरक्षा (5 आइटम)

• फेंस और भाषा संकेत बरकरार
• पहचानकर्ता/आयात अछूते; केवल टिप्पणियाँ स्थानीयकृत
• प्लेसहोल्डर्स और उद्धरण संरक्षित
• कॉपी-पेस्ट टेस्ट पास
• पुरानी स्निपेट्स को बनाए रखने वालों को फ्लैग किया गया

संरचित डेटा (5 आइटम)

• कीज़ और प्रकार अछूते
• उद्धरण/एस्केप्स/इंडेंटेशन संरक्षित
• संख्याएं और बूलियन प्रकार के रूप में बनी रहती हैं
• पार्सर/लिंटर स्थानीय रूप से पास
• आकस्मिक की परिवर्तन के लिए डिफ्स की समीक्षा की गई

संबंधित पठन

• सबसे आम अनुवाद गलतियाँ और उन्हें कैसे टालें
• पेशेवरों के लिए अनुवाद प्रूफरीडिंग चेकलिस्ट
• PDF फाइलों का अनुवाद कैसे करें और फॉर्मेटिंग बनाए रखें
• क्यों आपका अनुवादित वेबसाइट उपयोगकर्ताओं को भ्रमित करता है और इसे कैसे ठीक करें