अंतर्राष्ट्रीयकरण

लोकेल-अवेयर रूटिंग, प्रति-भाषा नेविगेशन, अनूदित UI और SEO के साथ अपने डॉक्स को कई भाषाओं में परोसें — सब कुछ कन्वेंशन-फ़र्स्ट।

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

इसे सक्षम करें

अपने लोकेल और उनमें से कौन-सा डिफ़ॉल्ट है, यह सूचीबद्ध करते हुए एक i18n ब्लॉक जोड़ें:

i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
    { code: "ar", label: "العربية", dir: "rtl" },
  ],
}

प्रत्येक लोकेल में एक code (URL में उपयोग किया जाता है), एक label (भाषा स्विचर में दिखाया जाता है), और दाएँ-से-बाएँ लिपियों के लिए एक वैकल्पिक dir होता है (डिफ़ॉल्ट रूप से "ltr")। एक वैकल्पिक style blume translate को उस लोकेल के लिए स्वतंत्र-रूप मार्गदर्शन देता है — रजिस्टर, बोली, शब्दावली, जैसे "Brazilian Portuguese, informal você" — ताकि यह चुनाव एजेंट पर छोड़ने के बजाय पहले ही अनुवाद से तय हो जाए।

अनूदित सामग्री व्यवस्थित करें

डिफ़ॉल्ट लोकेल आपके कंटेंट रूट में रहता है। हर दूसरा लोकेल अपने code के नाम वाला एक टॉप-लेवल फ़ोल्डर होता है, जो डिफ़ॉल्ट संरचना को प्रतिबिंबित करता है:

docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar

फ़ाइल	रूट
`docs/index.mdx`	`/`
`docs/guides/quickstart.mdx`	`/guides/quickstart`
`docs/fr/guides/quickstart.mdx`	`/fr/guides/quickstart`

डिफ़ॉल्ट लोकेल को उसका अपना कोई फ़ोल्डर न दें: केवल अन्य कोड ही लोकेल फ़ोल्डर होते हैं, इसलिए en डिफ़ॉल्ट होने पर docs/en/ साधारण सामग्री है जो /en/… पर प्रकाशित होती है (और फ़्रेंच फ़ॉलबैक के रूप में /fr/en/… पर भी)। ऐसा फ़ोल्डर मिलने पर Blume चेतावनी देता है।

आप केवल वही फ़ाइलें अनूदित करते हैं जो आप चाहते हैं — बाकी सब अपने आप फ़ॉलबैक हो जाता है (फ़ॉलबैक देखें)।

फ़ाइलनाम प्रत्यय

अनुवादों को मूल के पास ही रखना पसंद करते हैं? parser: "dot" सेट करें और फ़ोल्डर उपयोग करने के बजाय फ़ाइलों को लोकेल प्रत्यय के साथ नाम दें:

docs/
  guides/quickstart.mdx     ->  /guides/quickstart      (default)
  guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (French)

विरल अनुवादों के लिए अच्छा — पूरे ट्री को प्रतिबिंबित किए बिना उन कुछ पृष्ठों को साथ रखें जिनका आपने अनुवाद किया है।

साझा फ़ाइलें

ऐसी सामग्री के लिए जो हर भाषा में एक जैसी है — एक चेंजलॉग, एक स्टेटस पेज — एक $ मार्कर जोड़ें ताकि एक ही फ़ाइल बिना दोहराव के सभी लोकेल को परोसे:

docs/changelog.$.mdx   ->  /changelog and /fr/changelog (same content)
docs/guides/meta.$.ts   (folder meta applied to every locale)

किसी लोकेल-विशिष्ट meta.ts उस भाषा के लिए साझा वाले को अब भी ओवरराइड करती है।

डिफ़ॉल्ट-लोकेल URL

डिफ़ॉल्ट रूप से डिफ़ॉल्ट लोकेल का कोई URL उपसर्ग नहीं होता (/, /guides/quickstart) जबकि अन्य लोकेल उपसर्ग सहित होते हैं (/fr/…)। इससे आपकी प्राथमिक भाषा के URL साफ़ रहते हैं। हर लोकेल को, डिफ़ॉल्ट सहित, उपसर्ग देने के लिए:

i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}

हर भाषा को उस लोकेल की फ़ाइलों से बना अपना खुद का साइडबार मिलता है — इसलिए अनुवाद संरचना, क्रम या लेबल में भिन्न हो सकते हैं। फ़ोल्डर meta.ts फ़ाइलें भी प्रति लोकेल हल होती हैं: डिफ़ॉल्ट dir पार्सर के तहत, फ़्रेंच समूह को स्वतंत्र रूप से क्रमबद्ध करने के लिए fr/guides/ के अंदर एक meta.ts रखें। जब तक किसी लोकेल की अपनी meta.ts (या एक साझा meta.$.ts) नहीं होती, तब तक उसका समूह फ़ॉलबैक लोकेल के समूह को प्रतिबिंबित करता है — उस फ़ोल्डर की meta.ts और उसके इंडेक्स पृष्ठ द्वारा सेट किया गया sidebar.display — ताकि फ़ॉलबैक होने वाले पृष्ठ वही शीर्षक, क्रम और संकुचित होने योग्य समूह बनाए रखें। dot पार्सर के तहत अनुवाद मूल के पास ही रहते हैं, इसलिए किसी फ़ोल्डर की meta.ts हर लोकेल पर लागू होती है। नेविगेशन के बारे में बाकी सब कुछ हर भाषा के लिए एक जैसा ही काम करता है।

हेडर टैब, हेडर लिंक और फ़ुटर कॉन्फ़िगर किए जाते हैं, सामग्री से व्युत्पन्न नहीं, इसलिए उनके लेबल blume.config.ts में स्थानीयकृत होते हैं। हर कॉन्फ़िगर किया गया लेबल सादे-स्ट्रिंग रूप के साथ-साथ एक प्रति-लोकेल मैप ({ en: "Docs", fr: "Documentation" }) भी स्वीकार करता है, और जिन लोकेल को आपने नहीं भरा है उनके लिए डिफ़ॉल्ट लोकेल की प्रविष्टि पर फ़ॉलबैक करता है: टैब और ड्रॉपडाउन लेबल (टैब), फ़ीचर्ड लिंक, हेडर एक्शन और कॉल टू एक्शन, फ़ुटर लिंक, बैनर का टेक्स्ट और लिंक टेक्स्ट, और MCP से कनेक्ट करें मेन्यू में कस्टम क्लाइंट।

navigation: {
  cta: {
    href: "https://acme.dev/signup",
    label: { en: "Start free", fr: "Essai gratuit" },
  },
},
footer: {
  links: [
    { label: { en: "Pricing", fr: "Tarifs" }, href: "https://acme.dev/pricing" },
  ],
},

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

फ़ॉलबैक

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

i18n: {
  // …
  fallbackLocale: "en", // default; set to null to 404 instead
}

फ़ॉलबैक पृष्ठ अपना कैनोनिकल लिंक उस पृष्ठ की ओर इंगित करते हैं जिसकी वे प्रतिलिपि हैं, खोज इंडेक्स, llms.txt, और MCP तथा JSON API पृष्ठ सूचियों से बाहर रखे जाते हैं, और hreflang में असली अनुवाद के रूप में प्रचारित नहीं किए जाते, इसलिए अअनूदित सामग्री रैंकिंग के लिए प्रतिस्पर्धा नहीं करती। वे उस लोकेल के साइडबार में फिर भी दिखते हैं, ताकि नेविगेशन पूरा बना रहे — एक पाठक किसी भी भाषा में हर पृष्ठ तक पहुँच सकता है।

githubReleases() स्रोत से आने वाले रिलीज़ नोट्स इसका अपवाद हैं: वे एक ही भाषा में प्रकाशित होते हैं, इसलिए उन्हें कभी भी अन्य लोकेल के URL पर कॉपी नहीं किया जाता और उनमें कोई भाषा स्विचर नहीं दिखता।

लोकेल के आर-पार लिंक

आंतरिक लिंक हर भाषा में, अनूदित पृष्ठों सहित, वैसे ही लिखें जैसे आप डिफ़ॉल्ट लोकेल में लिखते — [Setup](/guides/setup), <Card href="/guides/setup">। जब कोई पृष्ठ किसी लोकेल उपसर्ग के तहत रेंडर होता है, तो Blume हर रूट-सापेक्ष पृष्ठ लिंक को उस लोकेल में ले जाता है (/fr/guides/setup), बशर्ते वह रूट वहाँ परोसा जाता हो — असली अनुवाद के रूप में या फ़ॉलबैक पृष्ठ के रूप में। जिस लिंक का कोई प्रति-लोकेल संस्करण नहीं है — एक कस्टम पृष्ठ, एक जनरेट किया गया रूट, या फ़ॉलबैक अक्षम की गई साइट पर कोई गायब अनुवाद — वह 404 की ओर इशारा करने के बजाय अपना लिखा हुआ लक्ष्य बनाए रखता है, और जो लिंक पहले से ही कोई लोकेल उपसर्ग रखता है (/de/guides/setup) उसे छेड़ा नहीं जाता, ताकि आर-पार-लोकेल लिंक स्पष्ट बने रहें।

एंकर लिंक के साथ चलते हैं, इसलिए हेडिंग id का भाषाओं के आर-पार मेल खाना ज़रूरी है। blume translate इसका ध्यान रखता है: हर अनूदित हेडिंग को अंत में लगे [#id] मार्कर के ज़रिए उसकी स्रोत हेडिंग की id से बाँध दिया जाता है। जो अनुवाद आप हाथ से लिखते हैं, उसमें हेडिंग्स को उसी [#custom-id] मार्कर से खुद बाँधें — वरना #ordering फ़्रेंच पृष्ठ की स्वतः-जनरेट हुई #ordre से मेल नहीं खाएगा, और blume validate उस अनूदित पृष्ठ के सापेक्ष बेमेल की रिपोर्ट करता है जिस पर पाठक वास्तव में पहुँचता है।

एजेंट से अनुवाद करना

आपको लोकेल हाथ से भरने की ज़रूरत नहीं है। blume translate हर उस पृष्ठ को ढूँढता है जो प्रत्येक लोकेल में गायब या पुराना है और उसे एक लोकल एजेंट CLI (Codex या Claude Code) से अनूदित करता है:

blume translate --codex

Blume हर परिणाम की संरचना — फ़्रंटमैटर, कोड फ़ेंस, लिंक — को मान्य करता है और फ़ाइलें खुद लिखता है; एजेंट केवल टेक्स्ट का अनुवाद करता है। एक कमिट किया गया लेजर (blume.translations.json) ट्रैक करता है कि हर अनुवाद किस स्रोत रिवीज़न से आया था, इसलिए दोबारा चलाने पर केवल वही छुआ जाता है जो बदला है, और जो अनुवाद आपने हाथ से लिखे हैं उन्हें ज्यों-का-त्यों अपनाया जाता है, कभी ओवरराइट नहीं किया जाता। CI में, blume translate --check तब विफल होता है जब कोई स्रोत पृष्ठ अपने अनुवादों से आगे खिसक गया हो।

भाषा स्विचर

जब i18n चालू होता है, तो हेडर में अपने आप एक भाषा स्विचर दिखाई देता है, जो आपके locales से बनाया जाता है। हर पृष्ठ के लिए यह हर भाषा में मेल खाते अनुवाद को लिंक करता है; जहाँ कोई अनुवाद गायब है वहाँ यह फ़ॉलबैक पृष्ठ को लिंक करता है और उसे अअनूदित के रूप में चिह्नित करता है। फ़ॉलबैक बंद होने पर (fallbackLocale: null) लिंक करने के लिए कोई पृष्ठ नहीं होता, इसलिए स्विचर उस भाषा को छोड़ देता है। कॉन्फ़िगर करने के लिए कुछ नहीं है। GitHub Releases स्रोत से आने वाले पृष्ठ इसका अपवाद हैं: रिलीज़ नोट्स केवल एक भाषा में मौजूद होते हैं, इसलिए वे पृष्ठ बिना स्विचर के रेंडर होते हैं।

ब्राउज़र भाषा के अनुसार रूटिंग

आगंतुकों को उनकी अपनी भाषा में भेजने के लिए, routeByBrowserLanguage चालू करें:

i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
  ],
  routeByBrowserLanguage: true,
}

जो आगंतुक साइट के बाहर से डिफ़ॉल्ट भाषा के होमपेज पर पहुँचता है, उसे फिर उनके ब्राउज़र की पसंदीदा भाषा वाले होमपेज पर भेजा जाता है, बशर्ते साइट में वह भाषा उपलब्ध हो। Blume ब्राउज़र द्वारा पसंद की गई हर भाषा को क्रम से आज़माता है, पहले सटीक कोड का मिलान करता है और फिर मूल भाषा का (fr-CA से fr मिल जाता है)। यदि डिफ़ॉल्ट भाषा पहले आती है, तो आगंतुक वहीं रहता है। एक बार जब कोई पाठक स्विचर से कोई भाषा चुन लेता है, तो Blume उस चुनाव को याद रखता है और उन्हें रूट करना बंद कर देता है। केवल होमपेज रूट होता है; किसी भी अन्य पृष्ठ का लिंक वैसे ही खुलता है जैसा वह लिखा गया है।

रीडायरेक्ट पृष्ठ के पेंट होने से पहले ब्राउज़र में चलता है, इसलिए यह स्टैटिक बिल्ड सहित किसी भी होस्ट पर काम करता है। यह डिफ़ॉल्ट रूप से बंद रहता है क्योंकि सर्च इंजन एक ही भाषा में क्रॉल करते हैं: इसे चालू रखने पर, Blume द्वारा उत्सर्जित hreflang वैकल्पिक लिंक बनाए रखें ताकि हर भाषा के पृष्ठ फिर भी इंडेक्स हों।

अनूदित UI

Blume अपने खुद के इंटरफ़ेस क्रोम — “इस पृष्ठ पर”, “खोजें”, “GitHub पर संपादित करें”, और बाकी — के लिए अंतर्निहित अनुवाद के साथ आता है, इसलिए जिस लोकेल के लिए अंतर्निहित पैक है उसे बिना किसी अतिरिक्त काम के अनूदित UI मिलता है। आप केवल अपनी सामग्री का अनुवाद करते हैं।

पैक 30 से अधिक भाषाओं के लिए उपलब्ध हैं — अरबी, बंगाली, बल्गेरियाई, कैटलन, चीनी (सरलीकृत और पारंपरिक), क्रोएशियाई, चेक, डेनिश, डच, फ़िनिश, फ़्रेंच, जर्मन, ग्रीक, हिब्रू, हिन्दी, हंगेरियन, इंडोनेशियाई, इतालवी, जापानी, कोरियाई, नॉर्वेजियन, फ़ारसी, पोलिश, पुर्तगाली (और ब्राज़ीली पुर्तगाली), रोमानियाई, रूसी, सर्बियाई, स्लोवाक, स्पेनिश, स्वीडिश, थाई, तुर्की, यूक्रेनी, और वियतनामी। ये समुदाय द्वारा अनुरक्षित हैं — कोई लोकेल जोड़ने या किसी अनुवाद को बेहतर करने के लिए एक PR खोलें।

ये पैक API संदर्भ को भी कवर करते हैं: किसी ऑपरेशन पृष्ठ की हेडिंग्स, स्कीमा तालिकाएँ और Try it पैनल पृष्ठ की भाषा का अनुसरण करते हैं। संदर्भ द्वारा साइडबार में जोड़े गए लेबल — उसका अवलोकन पृष्ठ और वे समूह जिनके नाम वह खुद रखता है (Operations, Webhooks, और GraphQL के प्रकार) — डिफ़ॉल्ट लोकेल के शब्दों का उपयोग करते हैं, क्योंकि संदर्भ उसी लोकेल में प्रकाशित होता है। केवल लेबल बदलते हैं, इसलिए संदर्भ के URL हर भाषा में एक जैसे रहते हैं।

गायब या न भेजी गई स्ट्रिंग्स डिफ़ॉल्ट लोकेल पर, फिर अंग्रेज़ी पर फ़ॉलबैक करती हैं। किसी स्ट्रिंग को ओवरराइड करने या अपनी खुद की भाषा देने के लिए, लोकेल द्वारा कीयुक्त i18n.ui सेट करें:

i18n: {
  // …
  ui: {
    fr: {
      search: { button: "Rechercher", placeholder: "Rechercher…" },
      page: { previous: "Précédent", next: "Suivant" },
      reference: { tryIt: "Essayer" },
    },
  },
}

SEO

स्थानीयकृत SEO आपके लिए संभाला जाता है — प्रति पृष्ठ कोई मेटाडेटा लिखने की ज़रूरत नहीं:

<html lang> और dir सक्रिय लोकेल से सेट किए जाते हैं।
hreflang वैकल्पिक लिंक किसी पृष्ठ के हर उस असली अनुवाद को जोड़ते हैं जिसे सर्च इंजन इंडेक्स कर सकते हैं (noindex, छिपे हुए, या किसी अन्य पृष्ठ को कैनोनिकल बताने वाले अनुवाद को छोड़ दिया जाता है), साथ ही डिफ़ॉल्ट लोकेल की ओर इशारा करने वाला एक x-default भी।
कैनोनिकल URL लोकेल-सही होते हैं, और JSON-LD inLanguage ले जाता है।

deployment.site सेट करें ताकि इन्हें निरपेक्ष URL के रूप में उत्सर्जित किया जा सके।

खोज

खोज सक्रिय भाषा तक सीमित होती है: किसी /fr/… पृष्ठ पर डायलॉग फ़्रेंच परिणाम लौटाता है, साथ में एक सभी भाषाएँ टॉगल होता है जिससे एक साथ हर लोकेल में खोजा जा सके। डिफ़ॉल्ट (Orama) और FlexSearch इंडेक्स ब्राउज़र में फ़िल्टर करते हैं, Pagefind हर भाषा के लिए एक अलग इंडेक्स रखता है, और Algolia, Orama Cloud और Typesense हर रिकॉर्ड पर एक locale फ़ील्ड रखते हैं। Mixedbread खोज को भाषा के अनुसार सीमित नहीं कर सकता, इसलिए इसके साथ हर खोज सभी लोकेल में होती है और डायलॉग में कोई टॉगल नहीं होता। हर एडेप्टर इसे कैसे संभालता है, यह जानने के लिए खोज देखें।

दाएँ-से-बाएँ

किसी लोकेल पर dir: "rtl" सेट करें और Blume पूरे इंटरफ़ेस को प्रतिबिंबित कर देता है — साइडबार, हेडर, विषय-सूची, पेजिनेशन, खोज और मेन्यू — और <html dir> को उससे मेल खाने के लिए सेट करता है। दो चीज़ें जानबूझकर बाएँ-से-दाएँ ही रहती हैं: कोड ब्लॉक (कोड किसी भी भाषा में LTR पढ़ा जाता है) और फ़ॉलबैक सामग्री — एक अअनूदित पृष्ठ उसी भाषा की दिशा बनाए रखता है जिसमें वह वास्तव में लिखा गया है, ताकि RTL लोकेल के तहत दिखाई गई अंग्रेज़ी भी सही पढ़ी जाए जबकि आसपास का क्रोम प्रतिबिंबित हो।

आगे कहाँ

नेविगेशन

हर लोकेल के साइडबार, क्रम और टैब को आकार दें।

खोज-योग्यता

साइटमैप, Open Graph और संरचित डेटा।