नेक्स्ट्रा इंटीग्रेशन
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 gemini
# 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 सक्षम करें।
पेज लेआउट
Nextra 4 i18n के साथ स्रोत-स्थानीय MDX को एक स्थानीय फ़ोल्डर के अंतर्गत रखता है (आमतौर पर content/en/ जब अंग्रेज़ी स्रोत हो)। sourceLocale कोई भी भाषा हो सकती है। अनुवादित प्रतियाँ सहोदर स्थानीय फ़ोल्डरों में लिखी जाती हैं:
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
}
}contentPaths को sourceLocale में लिखी गई .mdx फ़ाइलों और डायरेक्टरी पर इंगित करें। वह भाषा कोई भी भाषा हो सकती है। docsRoot को content/ के अंदर स्रोत-स्थानीय फ़ोल्डर पर सेट करें (उदाहरण के लिए content/en जब अंग्रेज़ी स्रोत हो)।
नेक्स्ट्रा अंतर्राष्ट्रीयकरण को वायर करें: next.config में i18n.locales और defaultLocale सेट करें, और ai-i18n-tools.config.json में targetLocales को उन लोकेल कोड और content/{locale}/ फ़ोल्डर नामों के साथ संरेखित रखें।
किसी मौजूदा साइट में i18n सक्षम करें
केवल अंग्रेज़ी वाली Nextra 4 साइट को एक लोकले फ़ोल्डर, एक रूट पैरामीटर, और Next.js i18n कॉन्फ़िग की आवश्यकता होती है, इससे पहले कि translate-docs कहीं लिख सके। पहली बार सेटअप किसी वेबसाइट या डॉक्स साइट में i18n जोड़ें पर प्रॉम्प्ट का उपयोग करता है। डिक्शनरी प्रॉम्प्ट उन्हीं रूट्स और डिक्शनरी के लिए विस्तृत अनुवर्ती है। चेकलिस्ट:
- MDX को
content/en/में ले जाएँ (अंग्रेज़ी एक स्थानीय फ़ोल्डर है, सामग्री रूट नहीं)। next.configमेंi18n.localesऔरdefaultLocale।- एक
app/[lang]/रूट,getPageMap('/${lang}'), और<Layout i18n={…}>। app/_dictionaries/en.tsके साथget-dictionary.ts, जिसे<Layout>,<Navbar>, और<Footer>में पास किया गया है।- वैकल्पिक
proxy.tsजोnextra/localesको पुनः निर्यात करता है (वैकल्पिक स्थानीय प्रॉक्सी देखें)। targetLocalesउन स्थानीय कोडों के साथ संरेखित, फिरsync।
थीम स्ट्रिंग्स
Nextra थीम स्ट्रिंग्स (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)
Nextra 3+ साइडबार संरचना और शीर्षकों के लिए TypeScript _meta.ts / _meta.tsx फ़ाइलों का उपयोग करता है। जब docsOutput.style "nextra" होता है, तो translate-docs स्वचालित रूप से _meta.ts, _meta.tsx, और _meta.js को docsRoot के तहत एकत्र करता है, 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। एक सर्वर कंपोनेंट (app/_components/feedback-links.tsx) एक फ़्लैट-बंडल लुकअप के माध्यम से t() का उपयोग करता है ताकि कस्टम शेल स्ट्रिंग्स डिक्शनरी के बगल में रह सकें। पोर्ट 3070 पर pnpm run dev चलाएँ।
एजेंट प्रॉम्प्ट: शब्दकोश और रूट्स
इसका उपयोग तब करें जब साइट में अभी भी हार्डकोडेड लेआउट स्ट्रिंग हों और कोई content/en/ ट्री न हो। यह डिफ़ॉल्ट पाथ (डिक्शनरी + _meta.ts + translate-docs) का अनुसरण करता है। यह t() पेश नहीं करता है।
डिक्शनरी और रूट्स प्रॉम्प्ट
# Add Nextra 4 i18n with a theme dictionary
## Context
ai-i18n-tools translates Nextra page bodies, `_meta.ts` object literals, and the
theme dictionary module (`nextraDictionaryPath`, usually
`app/_dictionaries/en.ts`) with `translate-docs`. The English sentence in that
dictionary is the source text. Do not translate strings yourself. Reference:
https://github.com/wsj-br/ai-i18n-tools/tree/main/examples/nextra-docs
## Scope
Edit `next.config`, `app/[lang]/layout.tsx`, `app/_dictionaries/en.ts`,
`app/_dictionaries/get-dictionary.ts`, and move MDX under `content/en/`. Skip
`docsRepositoryBase` (a URL). Keep native language names in a `LOCALE_LABELS`
map untranslated (`English`, `Português (Brasil)`). Do not move `_meta.ts`
sidebar labels into the dictionary or into `t()`.
## Call shape
- `next.config`: `i18n.locales` and `defaultLocale`.
- English MDX and `_meta.ts` live under `content/en/`. `getPageMap('/${lang}')`
loads the matching tree.
- `app/_dictionaries/en.ts` exports the English shell strings (`siteTitle`, `footer`,
`editLink`, search placeholder, table-of-contents title, last-updated label).
`get-dictionary.ts` dynamically imports `./${locale}`.
- Pass those fields into `<Layout>`, `<Navbar>`, and `<Footer>`. Set
`<Layout i18n>` from `LOCALE_LABELS`.
- Config: `features.translateDocs`, `docsOutput.style: "nextra"`,
`docsRoot: "content/en"`, `nextraDictionaryPath: "app/_dictionaries/en.ts"`.
`targetLocales` matches `i18n.locales` except the default locale.
## Order
1. Route, config, and dictionary wiring.
2. Move existing MDX into `content/en/` and point `contentPaths` at that folder.
3. Ask the user to run `sync`. Do not write `app/_dictionaries/pt-BR.ts` or
`content/pt-BR/` by hand.
## Do not
- Do not translate, rename, or reword the English dictionary strings.
- Do not add `t()`, `getRequestConfig`, or a `dictionary.ts` filename. The
English module is `app/_dictionaries/en.ts`.
- Do not duplicate a string in both the dictionary and a later `t()` call.
- Do not hand-edit generated locale dictionaries or locale `_meta.ts` files.
## Verify
- `pnpm build` passes.
- `/` shows the English dictionary strings. After `sync`, one non-English route
shows translated shell strings and page titles.
- Sidebar labels come from `content/en/**/_meta.ts`, not from the dictionary.
## Report back
List files changed, each layout string you left untranslated and why (URLs,
native language names), and any MDX you were not sure belonged under
`content/en/`.वैकल्पिक: app/ रिएक्ट (हाइब्रिड) के लिए t()
डिफ़ॉल्ट: _meta.ts ऑब्जेक्ट लिटरल और app/_dictionaries/en.ts translate-docs द्वारा अनुवादित किए जाते हैं। उन शेल स्ट्रिंग्स के लिए किसी t() की आवश्यकता नहीं है।
वैकल्पिक हाइब्रिड: कस्टम सर्वर कंपोनेंट t("source sentence") और translate-ui को कॉल कर सकते हैं। वाक्य sourceLocale में लिखा गया है, जो कोई भी भाषा हो सकती है। उन कॉलों में डिक्शनरी स्ट्रिंग या _meta.ts शीर्षक कॉपी न करें। extract केवल t() के अंदर लिटरल देखता है, इसलिए ui.sourceRoots को केवल उन फ़ोल्डरों को सूचीबद्ध करना चाहिए जिनमें वे कॉल शामिल हैं (उदाहरण app/_components का उपयोग करता है), न कि app/_dictionaries।
changeLanguage के साथ एक मॉड्यूल-स्तर i18next सिंगलटन एक सर्वर कंपोनेंट में असुरक्षित है: समवर्ती अनुरोध इसे साझा करते हैं। उदाहरण इसके बजाय एक स्टेटलेस लुकअप का उपयोग करता है। getT(lang) एक लक्ष्य स्थानीय के लिए locales/{lang}.json लोड करता है, स्रोत रूट को एक खाली बंडल के रूप में मानता है (अंग्रेज़ी लिटरल पहले से ही टेक्स्ट है), और ai-i18n-tools/runtime से interpolateTemplate के साथ इंटरपोलेट करता है। प्लेसहोल्डर ASCII शब्द कुंजियों के साथ {{name}} हैं। यह examples/astro-website/src/i18n/t.ts के समान विचार है।
वह लुकअप बहुवचन रूपों का चयन नहीं करता है। एक कंपोनेंट जिसे plurals: true की आवश्यकता है, उसे क्लाइंट कंपोनेंट में Wire i18next से i18next पाथ का उपयोग करना चाहिए, या प्रति-अनुरोध createInstance() का।
हाइब्रिड के लिए कॉन्फ़िग, मौजूदा डॉक्स ब्लॉक के बगल में:
features.translateUIStringsui.sourceRoots— फ़ोल्डर जिनमेंt()कॉल शामिल हैंui.stringsJsonui.flatOutputDir
उदाहरण का sourceLocale en-GB है और साइट रूट en है। स्टेटलेस लुकअप के साथ en रूट को किसी बंडल की आवश्यकता नहीं होती है, इसलिए वह बेमेल मायने नहीं रखता। यह तभी मायने रखता है जब आप इस कंपोनेंट को i18next बूटस्ट्रैप पर स्विच करते हैं, जो बंडलों को sourceLocale द्वारा कुंजीबद्ध करता है।
| सामग्री | डिफ़ॉल्ट पाइपलाइन | वैकल्पिक विकल्प |
|---|---|---|
| MDX पेज बॉडी | translate-docs | — |
_meta.ts / _meta.tsx ऑब्जेक्ट शीर्षक | translate-docs | JSX (हाइब्रिड) में t() में रीफ़ैक्टर करें |
app/ लेआउट, _components/ | nextraDictionaryPath + डिक्शनरी .ts | t() + translate-ui |
examples/nextra-docs में app/_components/feedback-links.tsx और lib/ui-t.ts देखें। उस उदाहरण में pnpm run i18n:sync-ui डॉक्स पाइपलाइन को छुए बिना एक्सट्रैक्ट और translate-ui चलाता है।
उदाहरण AI एजेंट प्रॉम्प्ट (डिक्शनरी के बगल में t() जोड़ते समय कर्सर या किसी अन्य कोडिंग एजेंट में कॉपी करें):
हाइब्रिड t() प्रॉम्प्ट
# Add a stateless t() lookup to a Nextra 4 server component
## Context
MDX pages, `_meta.ts`, and `app/_dictionaries/en.ts` stay on `translate-docs`.
Do not duplicate those strings in `t()`. This task adds `t("source sentence")`
only in custom components that the dictionary does not cover. The literal is the
catalog key and is written in `sourceLocale`, which can be any language. Do not translate any string.
Follow `lib/ui-t.ts` and `app/_components/feedback-links.tsx` in
https://github.com/wsj-br/ai-i18n-tools/tree/main/examples/nextra-docs
## Scope
Edit the named components and `ai-i18n-tools.config.json`. Do not edit
`app/_dictionaries`, `content/**/_meta.ts`, or generated locale trees. Skip
URLs, native language names, and `docsRepositoryBase`.
## Call shape
Create `lib/ui-t.ts`. `getT(lang)` loads `locales/{lang}.json` through a
dynamic-import map for target locales, uses an empty bundle for the source
route, and returns
`(source, vars) => interpolateTemplate(flat[source] ?? source, vars ?? {})` with
`interpolateTemplate` imported from `ai-i18n-tools/runtime`.
Replace hardcoded sentences in the named server components with `t("source sentence")`. The sentence is written in `sourceLocale`, which can be any language.
A placeholder is `t("You are reading {{page}}.", { page })`.
Do not use `getRequestConfig` (that is a next-intl API) and do not call
`changeLanguage` on a shared i18next instance. This lookup does not resolve
plurals. Leave plural copy on the i18next client path.
Set `features.translateUIStrings`, `ui.sourceRoots` to only the folders that
contain `t()` calls, `ui.stringsJson`, and `ui.flatOutputDir`.
## Order
1. Add `lib/ui-t.ts` and the `t()` calls.
2. Set the four `ui` config keys.
3. Run `ai-i18n-tools extract` (or `sync-ui`). Do not hand-write
`locales/*.json`.
## Do not
- Do not translate, rename, or reword the source sentences.
- Do not put `t()` keys in `app/_dictionaries` or move `_meta.ts` titles into
`t()`.
- Do not hand-edit `strings.json` or flat locale files.
- Do not change layout or Nextra theme props that already receive dictionary
strings.
## Verify
- `extract` writes a non-empty catalog containing the new sentences and nothing
from the dictionary.
- The project build passes.
- The source route still shows the English sentences. After `translate-ui`, one
non-English route renders the translated component.
## Report back
List files changed, each string you left in the dictionary on purpose, and any
plural or server-concurrency case you did not convert.लिंक कन्वेंशन
नेक्स्ट्रा नेक्स्ट.जेएस 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: Nextra और Next.js next.config, content/{locale}/, और NEXT_LOCALE कुकी में छोटे रूट कोड (en, pt-BR, zh-Hans) का उपयोग करते हैं। ai-i18n-tools.config.json में sourceLocale अनुवाद गुणवत्ता के लिए en-GB जैसा BCP-47 टैग हो सकता है — वह टैग साइट रूट नहीं है। यदि ब्राउज़र कुकी या Accept-Language, i18n.locales के बाहर किसी टैग पर रिज़ॉल्व होता है (उदाहरण के लिए en-GB जब केवल en कॉन्फ़िगर किया गया हो), तो Nextra का स्टॉक प्रॉक्सी लूप में रीडायरेक्ट कर सकता है। examples/nextra-docs डेमो, सौंपने से पहले अमान्य कुकीज़ और पाथ को डिफ़ॉल्ट साइट लोकले पर रीसेट करने के लिए nextra/locales को रैप करता है।
यह output: 'export' स्थिर निर्यात के साथ काम नहीं करता है। नेक्स्ट्रा i18n डॉक्स देखें।
यह भी देखें कॉन्फ़िगरेशन — docsOutput और आउटपुट लेआउट।