नेक्स्ट्रा इंटीग्रेशन

Next.js ऐप राउटर पर नेक्स्ट्रा 4 डॉक्यूमेंटेशन साइट्स के लिए init -t ui-nextra और docsOutput.style: "nextra" का उपयोग करें। प्रीसेट doc-system के लिए एक उपनाम है जिसमें एक खाली localeSubpath और BCP-47 लोकेल फ़ोल्डर नाम संरक्षित हैं (localePathLowercase डिफ़ॉल्ट रूप से false होता है, इसलिए फ़ोल्डर pt-BR, zh-Hans, आदि रहते हैं)।

दस्तावेज़ और चलाने योग्य उदाहरण/नेक्स्ट्रा-डॉक्स डेमो भी देखें।

त्वरित शुरुआत

ai-i18n-tools init -t ui-nextra [-P <provider>]
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync   # or: ai-i18n-tools sync
pnpm run build       # Next.js build (project-specific script)

जब आप पेज सामग्री, _meta.ts साइडबार लेबल और थीम डिक्शनरी मॉड्यूल को एक sync रन में अनुवादित करते हैं, तो features.translateDocs सक्षम करें।

पेज लेआउट

i18n के साथ नेक्स्ट्रा 4 लोकेल फ़ोल्डर के तहत अंग्रेजी स्रोत MDX (आमतौर पर content/en/) रखता है। अनुवादित प्रतियां सिबलिंग लोकेल फ़ोल्डरों में लिखी जाती हैं:

content/en/index.mdx              →  content/pt-BR/index.mdx
content/en/guide/getting-started.mdx  →  content/zh-Hans/guide/getting-started.mdx

एक docs[] ब्लॉक कॉन्फ़िगर करें:

{
  "contentPaths": ["content/en"],
  "outputDir": "content",
  "docsOutput": {
    "style": "nextra",
    "docsRoot": "content/en",
    "rewriteNextraLinks": true
  }
}

अपने अंग्रेजी .mdx फ़ाइलों और निर्देशिकाओं पर contentPaths इंगित करें। docsRoot को content/ के अंदर अंग्रेजी लोकेल फ़ोल्डर पर सेट करें।

नेक्स्ट्रा अंतर्राष्ट्रीयकरण को वायर करें: next.config में i18n.locales और defaultLocale सेट करें, और ai-i18n-tools.config.json में targetLocales को उन लोकेल कोड और content/{locale}/ फ़ोल्डर नामों के साथ संरेखित रखें।

थीम स्ट्रिंग्स

नेक्स्ट्रा थीम क्रोम (editLink, खोज प्लेसहोल्डर, फुटर, और इसी तरह) मार्कडाउन से निकाला नहीं जाता है। एक टाइपस्क्रिप्ट डिक्शनरी मॉड्यूल (उदाहरण के लिए app/_dictionaries/en.ts) में अंग्रेजी स्ट्रिंग्स लिखें और इसे translate-docs के अंदर अनुवादित करें:

{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "contentPaths": ["content/en"],
      "outputDir": "content",
      "nextraDictionaryPath": "app/_dictionaries/en.ts",
      "docsOutput": {
        "style": "nextra",
        "docsRoot": "content/en"
      }
    }
  ]
}

टूल app/_dictionaries/{locale}.ts लिखता है (डिफ़ॉल्ट टेम्पलेट: {dir}/{locale}.ts)। app/_dictionaries/get-dictionary.ts में प्रति-लोकेल मॉड्यूल लोड करें और <Layout>, <Search>, <Footer> और संबंधित थीम घटकों को अनुवादित स्ट्रिंग्स पास करें।

नेक्स्ट्रा थीम डिक्शनरी स्ट्रिंग्स के लिए json[] का उपयोग न करें — वह पैटर्न केवल असंबंधित ऐप लोकेल बंडलों के लिए है।

साइडबार लेबल (_meta.ts)

नेक्स्ट्रा 3+ साइडबार संरचना और शीर्षकों के लिए टाइपस्क्रिप्ट _meta.ts / _meta.tsx फ़ाइलों का उपयोग करता है। जब docsOutput.style "nextra" होता है, तो translate-docs स्वचालित रूप से docsRoot के तहत _meta.ts, _meta.tsx, और _meta.js एकत्र करता है, export default { … } मेटा मैप में स्ट्रिंग लिटरल का अनुवाद करता है, और content/{locale}/** के तहत मिरर की गई फ़ाइलें लिखता है।

अनुशंसित पैटर्न: content/en/**/_meta.ts में अंग्रेजी लिटरल को इनलाइन रखें (swr-site के समान):

content/en/_meta.ts           English sidebar labels (source)
content/pt-BR/_meta.ts        Translated copy (generated by translate-docs)

वैकल्पिक: docs[].nextraMetaGlob के साथ संग्रह को ओवरराइड करें या docs[].nextraMetaTranslatableKeys के साथ अनुवाद योग्य प्रॉपर्टी नामों को प्रतिबंधित करें (डिफ़ॉल्ट: title, display, breadcrumb)।

JSON साइडकार (i18n/meta.en.json) या पतली _meta.ts फ़ाइलें जो अनुवादित JSON आयात करती हैं, को हाथ से न लिखें — जब अंग्रेजी बदलती है तो sync / translate-docs के साथ लोकेल _meta फ़ाइलों को फिर से जनरेट करें।

उदाहरण प्रोजेक्ट

उदाहरण/नेक्स्ट्रा-डॉक्स — content/en/ पर अंग्रेजी स्रोत, प्रतिबद्ध pt-BR और zh-Hans पेज ट्री, इनलाइन _meta.ts फ़ाइलें, और app/_dictionaries/{locale}.ts। पोर्ट 3070 पर pnpm run dev चलाएँ।

वैकल्पिक: app/ रिएक्ट (हाइब्रिड) के लिए t()

डिफ़ॉल्ट: _meta.ts / _meta.tsx ऑब्जेक्ट-लिटरल स्ट्रिंग्स translate-docs के अंदर अनुवादित होते हैं — किसी t() की आवश्यकता नहीं है।

वैकल्पिक हाइब्रिड: टीमें app/ लेआउट क्रोम, कस्टम MDX घटकों, या _meta.tsx लेबल के लिए t() + translate-ui का अतिरिक्त रूप से उपयोग कर सकती हैं जो केवल JSX घटक निकायों के अंदर रहते हैं (v1 में ऑब्जेक्ट-लिटरल निष्कर्षण से परे)। यह मेटा फ़ाइलों के लिए अनुवाद-मेटा को प्रतिस्थापित नहीं करता है जब तक कि आप साइडबार लेबल को घटकों में स्पष्ट रूप से रीफैक्टर न करें।

सामग्री	डिफ़ॉल्ट पाइपलाइन	वैकल्पिक विकल्प
MDX पेज बॉडी	translate-docs	—
_meta.ts / _meta.tsx ऑब्जेक्ट शीर्षक	translate-docs	JSX (हाइब्रिड) में t() में रीफ़ैक्टर करें
app/ लेआउट, _components/	nextraDictionaryPath + डिक्शनरी .ts	t() + translate-ui

उदाहरण AI एजेंट प्रॉम्प्ट (लेआउट क्रोम को t() में माइग्रेट करते समय कर्सर या किसी अन्य कोडिंग एजेंट में कॉपी करें):

Add i18n to our Nextra 4 app/ layout using ai-i18n-tools translate-ui (optional hybrid).

Context:
- We already translate MDX pages and _meta.ts via translate-docs (default).
- We want t() in app/[lang]/layout.tsx and app/_components/ for labels not covered by nextraDictionaryPath.
- English-as-key: t("Edit this page on GitHub") in source; strings.json + locales/{locale}.json from extract + translate-ui.
- Do not move _meta.ts sidebar labels into t() unless we explicitly ask — translate-docs handles _meta object literals.

Requirements:
1. Wire getRequestConfig / i18n provider for the app router locale param.
2. Replace hard-coded layout strings with t() calls; keep structure and Nextra theme APIs unchanged.
3. Enable features.translateUIStrings, set ui.sourceRoots to app/ (and mdx-components if needed).
4. Do not duplicate dictionary.ts strings that nextraDictionaryPath already translates — pick one approach per string.

After editing: run extract, translate-ui (or sync), verify en + one target locale in dev.

लिंक कन्वेंशन

नेक्स्ट्रा नेक्स्ट.जेएस i18n (/guide/getting-started, /pt-BR/guide/getting-started) के माध्यम से लोकेल-प्रीफ़िक्स्ड रूट प्रदान करता है। इन-पेज लिंक लोकेल-न्यूट्रल रहने चाहिए (/guide/getting-started) ताकि नेक्स्ट.जेएस सक्रिय लोकेल को स्वचालित रूप से प्रीफ़िक्स कर सके।

बिल्ट-इन नॉर्मलाइज़र को सक्षम करें ताकि translate-docs हर अनुवादित फ़ाइल में लिंक को स्वचालित रूप से ठीक कर दे:

"docsOutput": {
  "style": "nextra",
  "docsRoot": "content/en",
  "rewriteNextraLinks": true
}

जब style "nextra" हो तो rewriteNextraLinks डिफ़ॉल्ट रूप से सक्षम होता है।

अंग्रेजी स्रोत में लेखक	सामान्यीकरण के बाद
[Guide](content/en/guide/getting-started.mdx)	[Guide](/hi/guide/getting-started)
[Guide](/hi/guide/getting-started.mdx)	[Guide](/hi/guide/getting-started)
[Demo](https://github.com/org/repo)	अपरिवर्तित (पूरा URL)

लेखन नियम

• क्रॉस-पेज डॉक लिंक: अंग्रेजी MDX में लोकेल-न्यूट्रल साइट रूट (/guide/…) का उपयोग करें, या content/en/… / सापेक्ष .mdx पाथ का उपयोग करें और सामान्यीकरणकर्ता को sync के दौरान उन्हें फिर से लिखने दें।
• सामग्री ट्री के बाहर रेपो फ़ाइलें: पूर्ण URL का उपयोग करें।
• content/<locale>/ में लिंक को मैन्युअल रूप से संपादित न करें — sync / translate-docs के साथ फिर से जनरेट करें।

वैकल्पिक लोकेल प्रॉक्सी

नेक्स्ट्रा i18n साइटों के लिए एक लोकेल-डिटेक्शन प्रॉक्सी प्रदान करता है। इसे अपने प्रोजेक्ट रूट में proxy.ts से निर्यात करें:

export { proxy } from 'nextra/locales'

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|icon.svg|apple-icon.png|manifest|_pagefind).*)',
  ],
}

साइट लोकेल कोड बनाम sourceLocale: नेक्स्ट्रा और नेक्स्ट.जेएस next.config, content/{locale}/, और NEXT_LOCALE कुकी में छोटे रूट कोड (en, pt-BR, zh-Hans) का उपयोग करते हैं। ai-i18n-tools.config.json में sourceLocale अनुवाद गुणवत्ता के लिए BCP-47 टैग हो सकता है जैसे en-GB — वह टैग साइट रूट नहीं है। यदि ब्राउज़र कुकी या Accept-Language i18n.locales के बाहर एक टैग पर हल होता है (उदाहरण के लिए en-GB जब केवल en कॉन्फ़िगर किया गया हो), तो नेक्स्ट्रा का स्टॉक प्रॉक्सी लूप में रीडायरेक्ट कर सकता है। examples/nextra-docs डेमो अमान्य कुकीज़ और पाथ को डिफ़ॉल्ट साइट लोकेल पर रीसेट करने के लिए nextra/locales को लपेटता है, इससे पहले कि वह डेलिगेट करे।

यह output: 'export' स्थिर निर्यात के साथ काम नहीं करता है। नेक्स्ट्रा i18n डॉक्स देखें।

यह भी देखें कॉन्फ़िगरेशन — docsOutput और आउटपुट लेआउट।