---
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` चलाने पर हर लोकेल के लिए एक ही पेज का अनुवाद होता है। जब किसी बासी पेज का दोबारा अनुवाद होता है, तो एजेंट को मौजूदा अनुवाद दिखाया जाता है और उसके रजिस्टर, बोली और शब्दावली से मेल खाने को कहा जाता है — स्रोत में एक अनुच्छेद का संपादन अनुवाद में एक अनुच्छेद का ही अंतर पैदा करता है, शुरुआत से पुनर्लेखन नहीं।

पहले अनुवाद के पास मेल खाने के लिए कोई पूर्व उदाहरण नहीं होता, इसलिए यह चुनाव पहले ही [लोकेल पर `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) के ज़रिए उसके स्रोत शीर्षक की एंकर आईडी से बाँध दिया जाता है, बशर्ते अनुवाद पहले से ही कोई मार्कर न लगाता हो, ताकि `#fragment` लिंक हर भाषा में एक जैसे हल हों। शीर्षक स्थिति के अनुसार आपस में जोड़े जाते हैं, इसलिए जिस अनुवाद की शीर्षक संरचना स्रोत से मेल नहीं खाती, उसे कोई मार्कर नहीं मिलता।

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

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

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

```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` में है, जिसमें अंतर प्रति लोकेल समूहीकृत होता है। हाथ से लिखे (अनट्रैक किए गए) अनुवाद गेट को कभी विफल नहीं करते।

## सीमाएँ [#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 के रूप में दें।