Nextra-Integration

Verwenden Sie init -t ui-nextra und docsOutput.style: "nextra" für Nextra 4-Dokumentationsseiten auf dem Next.js App Router. Das Preset ist ein Alias für doc-system mit einem leeren localeSubpath und beibehaltenen BCP-47-Gebietsschema-Ordnernamen (localePathLowercase ist standardmäßig false, sodass Ordner pt-BR, zh-Hans usw. bleiben).

Siehe auch Dokumente und die ausführbare Demo examples/nextra-docs.

Schnellstart

bash

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)

Aktivieren Sie features.translateDocs, wenn Sie Seiteninhalte, _meta.ts-Seitenleistenbeschriftungen und Theme-Wörterbuchmodule in einem sync-Lauf übersetzen.

Seitenlayout

Nextra 4 mit i18n behält englische MDX-Quelldateien in einem Gebietsschema-Ordner (typischerweise content/en/). Übersetzte Kopien werden in gleichrangige Gebietsschema-Ordner geschrieben:

text

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

Konfigurieren Sie einen docs[]-Block:

json

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

Verweisen Sie contentPaths auf Ihre englischen .mdx-Dateien und -Verzeichnisse. Setzen Sie docsRoot auf den englischen Gebietsschema-Ordner innerhalb von content/.

Verbinden Sie die Nextra-Internationalisierung: Setzen Sie i18n.locales und defaultLocale in next.config und halten Sie targetLocales in ai-i18n-tools.config.json mit diesen Gebietsschema-Codes und den content/{locale}/-Ordnernamen übereinstimmend.

Theme-Strings

Nextra Theme Chrome (editLink, Suchplatzhalter, Fußzeile usw.) wird nicht aus Markdown extrahiert. Erstellen Sie englische Zeichenfolgen in einem TypeScript-Wörterbuchmodul (z. B. app/_dictionaries/en.ts) und übersetzen Sie es innerhalb von translate-docs:

json

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

Das Tool schreibt app/_dictionaries/{locale}.ts (Standardvorlage: {dir}/{locale}.ts). Laden Sie das Modul pro Gebietsschema in app/_dictionaries/get-dictionary.ts und übergeben Sie übersetzte Zeichenfolgen an <Layout>, <Search>, <Footer> und verwandte Theme-Komponenten.

Verwenden Sie nicht json[] für Nextra-Theme-Wörterbuchzeichenfolgen – dieses Muster ist nur für nicht verwandte App-Gebietsschema-Bundles vorgesehen.

Seitenleistenbeschriftungen (`_meta.ts`)

Nextra 3+ verwendet TypeScript _meta.ts / _meta.tsx-Dateien für die Seitenleistenstruktur und -titel. Wenn docsOutput.style "nextra" ist, sammelt translate-docs automatisch _meta.ts, _meta.tsx und _meta.js unter docsRoot, übersetzt Zeichenliterale in der export default { … }-Meta-Map und schreibt gespiegelte Dateien unter content/{locale}/**.

Empfohlenes Muster: Englische Literale inline in content/en/**/_meta.ts beibehalten (wie bei swr-site):

text

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

Optional: Überschreiben Sie die Sammlung mit docs[].nextraMetaGlob oder beschränken Sie übersetzbare Eigenschaftsnamen mit docs[].nextraMetaTranslatableKeys (Standard: title, display, breadcrumb).

Erstellen Sie keine JSON-Sidecars (i18n/meta.en.json) oder dünne _meta.ts-Dateien, die übersetztes JSON importieren – generieren Sie Gebietsschema-_meta-Dateien mit sync / translate-docs neu, wenn sich das Englische ändert.

Beispielprojekt

examples/nextra-docs – Englische Quellen unter content/en/, festgeschriebene pt-BR- und zh-Hans-Seitenbäume, Inline-_meta.ts-Dateien und app/_dictionaries/{locale}.ts. Führen Sie pnpm run dev auf Port 3070 aus.

Optional: `t()` für `app/` React (Hybrid)

Standard: _meta.ts / _meta.tsx Objekt-Literal-Strings werden innerhalb von translate-docs übersetzt – kein t() erforderlich.

Optionaler Hybrid: Teams können zusätzlich t() + translate-ui für app/-Layout-Chrome, benutzerdefinierte MDX-Komponenten oder _meta.tsx-Beschriftungen verwenden, die nur innerhalb von JSX-Komponenten (über die Objekt-Literal-Extraktion in v1 hinaus) existieren. Dies ersetzt nicht translate-meta für Meta-Dateien, es sei denn, Sie refaktorieren explizit Sidebar-Beschriftungen in Komponenten.

Inhalt	Standard-Pipeline	Optionale Alternative
MDX-Seiteninhalte	`translate-docs`	—
`_meta.ts` / `_meta.tsx` Objekttitel	`translate-docs`	Refaktorierung zu `t()` in JSX (Hybrid)
`app/`-Layout, `_components/`	`nextraDictionaryPath` + Wörterbuch `.ts`	`t()` + `translate-ui`

Beispiel für einen KI-Agenten-Prompt (in Cursor oder einen anderen Codierungsagenten kopieren, wenn Layout-Chrome zu t() migriert wird):

markdown

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.

Link-Konventionen

Nextra bedient lokal-präfixierte Routen über Next.js i18n (/guide/getting-started, /pt-BR/guide/getting-started). Links innerhalb der Seite sollten lokal-neutral bleiben (/guide/getting-started), damit Next.js das aktive Gebietsschema automatisch präfixieren kann.

Aktivieren Sie den integrierten Normalisierer, damit translate-docs Links in jeder übersetzten Datei automatisch korrigiert:

json

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

rewriteNextraLinks ist standardmäßig aktiviert, wenn style "nextra" ist.

Autor in englischer Quelle	Nach Normalisierer
`[Guide](content/en/guide/getting-started.mdx)`	`[Guide](/de/guide/getting-started)`
`[Guide](/de/guide/getting-started.mdx)`	`[Guide](/de/guide/getting-started)`
`[Demo](https://github.com/org/repo)`	unverändert (vollständige URL)

Regeln für die Erstellung

Dokumentenlinks über mehrere Seiten hinweg: Verwenden Sie lokal-neutrale Site-Routen (/guide/…) in englischem MDX oder content/en/… / relative .mdx-Pfade und lassen Sie den Normalisierer diese während sync umschreiben.
Repo-Dateien außerhalb des Inhaltsbaums: Verwenden Sie vollständige URLs.
Bearbeiten Sie Links in content/<locale>/ nicht manuell – generieren Sie sie mit sync / translate-docs neu.

Optionaler Locale-Proxy

Nextra bietet einen Locale-Erkennungs-Proxy für i18n-Sites. Exportieren Sie ihn aus proxy.ts in Ihrem Projekt-Root:

export { proxy } from 'nextra/locales'

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

Site-Locale-Codes vs. sourceLocale: Nextra und Next.js verwenden kurze Routen-Codes (en, pt-BR, zh-Hans) in next.config, content/{locale}/ und dem NEXT_LOCALE-Cookie. sourceLocale in ai-i18n-tools.config.json kann ein BCP-47-Tag wie en-GB für die Übersetzungsqualität sein – dieses Tag ist keine Site-Route. Wenn das Browser-Cookie oder Accept-Language zu einem Tag außerhalb von i18n.locales aufgelöst wird (z. B. en-GB, wenn nur en konfiguriert ist), kann der Standard-Proxy von Nextra in einer Schleife umleiten. Die Demo examples/nextra-docs umschließt nextra/locales, um ungültige Cookies und Pfade auf das Standard-Site-Locale zurückzusetzen, bevor sie delegiert.

Dies funktioniert nicht mit output: 'export' statischen Exporten. Siehe Nextra i18n docs.

Siehe auch Konfiguration – docsOutput und Ausgabe-Layouts.

UI-Strings

Dokumente

Integrationen

Bilder & Screenshots

SVG-Übersetzung

Übersetzungs-Dashboard

Nextra-Integration

Schnellstart

Seitenlayout

Theme-Strings

Seitenleistenbeschriftungen (`_meta.ts`)

Beispielprojekt

Optional: `t()` für `app/` React (Hybrid)

Link-Konventionen

Optionaler Locale-Proxy

UI-Strings

Dokumente

Nextra-Integration ​

Schnellstart ​

Seitenlayout ​

Theme-Strings ​

Seitenleistenbeschriftungen (_meta.ts) ​

Beispielprojekt ​

Optional: t() für app/ React (Hybrid) ​

Link-Konventionen ​

Optionaler Locale-Proxy ​

Nextra-Integration

Schnellstart

Seitenlayout

Theme-Strings

Seitenleistenbeschriftungen (`_meta.ts`)

Beispielprojekt

Optional: `t()` für `app/` React (Hybrid)

Link-Konventionen

Optionaler Locale-Proxy