---
title: अनुवाद
description: >-
  blume translate एक AI एजेंट की मदद से आपके लोकेल भरता है — यह हर भाषा में गायब या पुराने पेज ढूँढता है, उन्हें आपके पास पहले से मौजूद एजेंट CLI से अनुवादित करता है, और CI को एक ऐसा गेट देता है जो अनुवादों के पिछड़ने पर विफल हो जाता है।
---

[i18n](/docs/content/i18n) चालू होने के बाद, स्रोत पेज में किया गया हर संपादन चुपचाप उसके अनुवादों को पुराना कर देता है। `blume translate` इस कमी को पूरा करता है: यह ठीक-ठीक गणना करता है कि हर लोकेल में कौन-से पेज गायब या पुराने हैं, उन्हें एक स्थानीय एजेंट CLI से हेडलेस तरीके से अनुवादित करता है, और जो कुछ किया गया उसे एक कमिट किए गए लेजर में दर्ज करता है, ताकि अगला रन — और CI — जान सके कि क्या अद्यतन है।

```bash
blume translate --claude
```

```
blume translate  3 item(s) · 2 locale(s) · Claude Code

  ✔ docs/guides/install.mdx → fr 24.2s $0.11
  ✔ docs/guides/install.mdx → de 22.8s $0.10
  ✔ meta titles (2) → de 4.1s $0.01

  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
```

## यह कैसे काम करता है [#how-it-works]

पाइपलाइन Blume के नियंत्रण में रहती है; एजेंट केवल टेक्स्ट का अनुवाद करता है। जिस भी फ़ाइल पर काम करना हो, उसके लिए Blume एक अनुवाद प्रॉम्प्ट तैयार करता है, एजेंट CLI को उसके फ़ाइल, शेल और वेब टूल अक्षम करके हेडलेस रूप से चलाता है, उत्तर की संरचना को सत्यापित करता है, और लक्ष्य फ़ाइल स्वयं लिखता है — `--claude` के साथ [Claude Code](https://claude.com/claude-code), या `--codex` के साथ [Codex](https://developers.openai.com/codex/cli)। Blume न तो कोई API कुंजी रखता है और न ही स्वयं किसी मॉडल को कॉल करता है।

हर सत्यापित लेखन प्रोजेक्ट रूट पर स्थित `blume.translations.json` में दर्ज होता है: हर स्रोत फ़ाइल और लोकेल के लिए, अनुवाद के समय स्रोत का एक हैश। **इस फ़ाइल को कमिट करें।** इसी के ज़रिए दोबारा चलाए गए रन को "पहले से अनुवादित" और "अनुवादित, लेकिन तब से स्रोत बदल गया है" के बीच का अंतर पता चलता है — और यही CI गेट को संभव बनाता है।

हर फ़ाइल पूरी होने के बाद लेजर सहेज दिया जाता है, इसलिए किसी लंबे रन को रोकने (Ctrl+C) पर अधिक से अधिक वही अनुवाद खोते हैं जो उस समय चल रहे थे — अगला रन वहीं से शुरू होता है जहाँ आपने छोड़ा था। डिफ़ॉल्ट रूप से एक साथ 4 फ़ाइलें चलती हैं; यदि आपकी मशीन और एजेंट की रेट लिमिट अनुमति दें, तो `--concurrency` से इसे बढ़ाएँ।

दोबारा चलाए गए रन इंक्रीमेंटल होते हैं: जो स्रोत अपने पिछले अनुवाद के बाद से नहीं बदला, उसे छोड़ दिया जाता है, इसलिए एक पेज संपादित करने के बाद `blume translate` चलाने पर हर लोकेल में केवल एक पेज अनुवादित होता है। जब किसी पुराने पेज का दोबारा अनुवाद किया जाता है, तो एजेंट को मौजूदा अनुवाद दिखाया जाता है और उसकी भाषा-शैली, बोली और शब्दावली से मेल खाने को कहा जाता है — स्रोत में एक अनुच्छेद का संपादन अनुवाद में भी केवल एक अनुच्छेद का अंतर (diff) पैदा करता है, शुरुआत से पूरा पुनर्लेखन नहीं।

पहले अनुवाद के पास मेल खाने के लिए कोई पूर्व उदाहरण नहीं होता, इसलिए [लोकेल पर `style`](/docs/content/i18n) के ज़रिए यह चुनाव पहले से तय कर दें (`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`)। यह निर्देश हर अनुवाद प्रॉम्प्ट के साथ भेजा जाता है, और जहाँ कोई मौजूदा अनुवाद इससे असहमत हो, वहाँ `style` को प्राथमिकता मिलती है — इसलिए दोबारा अनुवाद पुराने पेजों को भी धीरे-धीरे कॉन्फ़िगर की गई शैली की ओर ले जाता है।

## किन चीज़ों का अनुवाद होता है [#what-gets-translated]

- **पेज** — डिफ़ॉल्ट लोकेल की `.md`/`.mdx` फ़ाइलें। एजेंट गद्य का और केवल मनुष्यों को दिखने वाले फ्रंटमैटर मानों (`title`, `description`, `sidebar.label`, `sidebar.badge`, `seo.title`, `seo.description`) का अनुवाद करता है। लक्ष्य फ़ाइलें आपके पार्सर का अनुसरण करती हैं: `dir` के अंतर्गत `fr/guides/install.mdx`, और `dot` के अंतर्गत `guides/install.fr.mdx`।
- **फ़ोल्डर नेविगेशन शीर्षक** — `dir` पार्सर के अंतर्गत, हर लोकेल के लिए आवश्यक [`meta.ts`](/docs/content/meta) शीर्षकों का अनुवाद एक ही बैच कॉल में किया जाता है, और हर लोकेल के लिए जनरेट की गई `meta.ts` बाकी सभी कुंजियों (`order`, `pages`, `icon`, `collapsed`) को ज्यों का त्यों कॉपी करती है, ताकि उस लोकेल का साइडबार अपना क्रम बनाए रखे।

आपके द्वारा हाथ से लिखे गए अनुवाद **अपना लिए जाते हैं, कभी ओवरराइट नहीं किए जाते**: जो अनुवाद मौजूद है लेकिन जिसकी लेजर में कोई प्रविष्टि नहीं है, उसे अद्यतन के रूप में चिह्नित करके वैसे ही छोड़ दिया जाता है। केवल `--force` ही उसका दोबारा अनुवाद करता है।

## सत्यापन [#validation]

संरचना के मामले में एजेंट पर कभी भरोसा नहीं किया जाता। लिखने से पहले, Blume हर उत्तर की जाँच करता है और फ़ाइल को स्रोत से दोबारा बनाता है:

- फ्रंटमैटर को स्रोत फ़ाइल के डेटा से दोबारा बनाया जाता है, और उस पर केवल छह अनुवाद-योग्य मान रखे जाते हैं — एजेंट द्वारा गढ़ी गई कुंजियाँ हटा दी जाती हैं, उसके द्वारा हटाई गई कुंजियाँ बहाल कर दी जाती हैं, और `slug`, `icon`, `order` तथा तिथियाँ इस बनावट के कारण हमेशा हूबहू स्रोत जैसी रहती हैं।
- कोड फ़ेंस की संख्या स्रोत से मेल खानी चाहिए, बॉडी खाली नहीं होनी चाहिए, और फ्रंटमैटर पार्स होना चाहिए।
- हर हेडिंग को अंत में लगे [`[#id]` मार्कर](/docs/content/syntax#custom-anchors) के ज़रिए उसकी स्रोत हेडिंग की एंकर id से पिन कर दिया जाता है, जब तक कि अनुवाद में पहले से कोई पिन न हो, ताकि `#fragment` लिंक हर भाषा में एक जैसे रिज़ॉल्व हों। हेडिंग्स का मिलान उनकी स्थिति के आधार पर होता है, इसलिए जिस अनुवाद की हेडिंग संरचना स्रोत से मेल नहीं खाती, उसे कोई पिन नहीं मिलता।

सत्यापन में विफल होने वाला उत्तर कुछ भी नहीं लिखता — उस आइटम को विफल के रूप में रिपोर्ट किया जाता है और रन आगे बढ़ जाता है। जो कुछ सफल हुआ, वह लेजर में दर्ज रहता है, इसलिए दोबारा चलाने पर केवल विफल आइटम ही फिर से आज़माए जाते हैं।

## CI को विफल करना [#failing-ci]

`blume translate --check` केवल-पढ़ने वाला (read-only) गेट है: यह हर गायब और पुराने जोड़े की रिपोर्ट करता है और विचलन (drift) होने पर नॉन-ज़ीरो कोड के साथ बाहर निकलता है, बिना कोई एजेंट चलाए या कुछ भी लिखे।

```bash
blume translate --check           # exit 1 when translations are missing or stale
blume translate --check --json    # machine-readable drift report on stdout
```

```yaml .github/workflows/translations.yml
- run: npx blume translate --check
```

JSON रिपोर्ट का `diagnostics` + `summary` स्वरूप वही है जो `blume validate --json`, `blume audit --json` और `blume eval --json` का है, और इसमें विचलन को लोकेल के अनुसार समूहित किया जाता है। हर गायब या पुराना अनुवाद एक त्रुटि डायग्नोस्टिक (`BLUME_TRANSLATE_MISSING`, `BLUME_TRANSLATE_STALE`) होता है, इसलिए `summary.error` एग्ज़िट कोड से मेल खाता है। हाथ से लिखे गए (अनट्रैक्ड) अनुवाद कभी भी गेट को विफल नहीं करते।

## सीमाएँ [#limitations]

- मेटा शीर्षकों का अनुवाद केवल `dir` पार्सर के साथ होता है — `dot` पार्सर में प्रति-लोकेल `meta.ts` की कोई व्यवस्था नहीं है। जो `meta.ts` डिफ़ॉल्ट रूप से कोई फ़ंक्शन एक्सपोर्ट करती है, उसे एक चेतावनी के साथ छोड़ दिया जाता है; उस लोकेल की प्रति आप स्वयं हाथ से लिखें।
- रिमोट और CMS-आधारित स्रोत छोड़ दिए जाते हैं: उनके लिए अनुवाद लिखने हेतु कोई स्थानीय फ़ाइल नहीं होती।
- हेडर टैब लेबल सामग्री में नहीं, बल्कि `blume.config.ts` में रहते हैं — उन्हें वहीं [प्रति-लोकेल लेबल मैप](/docs/content/navigation#tabs) के ज़रिए स्थानीयकृत करें।
- अनुवाद की गुणवत्ता एजेंट पर निर्भर करती है। आउटपुट की समीक्षा किसी भी अन्य योगदान की तरह करें — लेजर केवल ताज़गी की गारंटी देता है, भाषा की सहजता की नहीं।

## फ़्लैग [#flags]

- `--claude` / `--codex` — अनुवाद करने वाला एजेंट CLI। इनमें से ठीक एक आवश्यक है (`--check` के साथ छोड़कर)।
- `--check` — कुछ भी लिखे बिना विचलन की रिपोर्ट करता है और नॉन-ज़ीरो कोड के साथ बाहर निकलता है।
- `--concurrency <n>` — समानांतर एजेंट सत्र। डिफ़ॉल्ट `4`, अधिकतम `16`।
- `--locale <codes>` — अल्पविराम से अलग किए गए लक्ष्य लोकेल (डिफ़ॉल्ट रूप से हर गैर-डिफ़ॉल्ट लोकेल)।
- `--force` — अद्यतन और हाथ से लिखी गई फ़ाइलों सहित, सब कुछ दोबारा अनुवादित करता है।
- `--timeout <seconds>` — प्रति फ़ाइल एजेंट की समय-सीमा। डिफ़ॉल्ट `600`; यह ऊपरी सीमा अटके हुए एजेंटों को पकड़ने के लिए है, इसलिए बड़े पेजों को पूरा होने के लिए पर्याप्त समय मिलता है।
- `--json` — दोनों मोड में, रिपोर्ट को stdout पर JSON के रूप में आउटपुट करता है।