Docusaurus-Integration

Verwenden Sie init -t ui-docusaurus und docsOutput.style: "docusaurus" für Docusaurus-Dokumentationsseiten. Das Preset erstellt einen docs[]-Block mit docusaurusCatalogDir, sodass translate-docs sowohl Seiten-Markdown als auch Docusaurus-Shell-JSON in einem Befehl übersetzen kann.

Siehe auch Dokumente, die ausführbare Demo examples/docusaurus-docs und examples/nextjs-app für eine kombinierte Next.js-App mit verschachtelten Docusaurus-Dokumenten, flacher README und SVG-Assets.

Schnellstart

ai-i18n-tools init -t ui-docusaurus [-P <provider>]
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths, docusaurusCatalogDir)
pnpm run i18n:sync   # or: ai-i18n-tools sync
cd docs-site && pnpm build   # or: cd examples/docusaurus-docs && pnpm build

Aktivieren Sie features.translateDocs und setzen Sie docs[].docusaurusCatalogDir, wenn Sie sowohl Dokumentationsseiten als auch die Site-Oberfläche (Navigationsleiste, Fußzeile, Theme-Strings) übersetzen. Führen Sie docusaurus write-translations in Ihrem Docusaurus-Projekt aus, wenn Sie @docusaurus/* aktualisieren oder Navigationsleisten-/Fußzeilen-/Theme-Beschriftungen ändern – und führen Sie dann translate-docs oder sync erneut aus, damit Shell-JSON in jeden Sprachordner übersetzt wird.

Seitenlayout

Englisches Markdown und MDX befinden sich unter Ihrem Docusaurus-Ordner docs/ (zum Beispiel docs-site/docs/). Übersetzte Kopien werden in den Inhaltsbaum des Plugins jeder Sprache geschrieben:

docs-site/docs/getting-started.md
  →  docs-site/i18n/de/docusaurus-plugin-content-docs/current/getting-started.md
docs-site/docs/guide/quick-start.md
  →  docs-site/i18n/fr/docusaurus-plugin-content-docs/current/guide/quick-start.md

Konfigurieren Sie einen docs[]-Block:

{
  "contentPaths": ["docs-site/docs/"],
  "outputDir": "docs-site/i18n",
  "docusaurusCatalogDir": "docs-site/i18n/en",
  "addFrontmatter": true,
  "docsOutput": {
    "style": "docusaurus",
    "docsRoot": "docs-site/docs"
  }
}

Verweisen Sie contentPaths auf Ihre englischen .md / .mdx-Dateien und -Verzeichnisse. Setzen Sie docsRoot auf denselben Ordner, den Docusaurus als Inhaltsstamm verwendet. Setzen Sie outputDir auf das übergeordnete Verzeichnis jedes Sprachordners unter i18n/.

Verbinden Sie die Internationalisierung von Docusaurus: Halten Sie targetLocales in ai-i18n-tools.config.json mit dem locales-Array in docusaurus.config.js synchron. Jedes localeConfigs[locale].path muss mit dem Ordnernamen unter i18n/ übereinstimmen (zum Beispiel path: "fr" für i18n/fr/).

Shell-Strings (write-translations)

Docusaurus-Navigationsleiste, Fußzeile, Suchplatzhalter und andere Theme-/Plugin-Beschriftungen werden nicht aus Markdown extrahiert. Führen Sie docusaurus write-translations in Ihrem Docusaurus-Projekt aus, um JSON-Kataloge unter dem Standard-Sprachordner (typischerweise i18n/en/) zu generieren. Verweisen Sie dann docs[].docusaurusCatalogDir auf diesen Ordner:

{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "description": "Docusaurus pages + shell JSON",
      "contentPaths": ["docs-site/docs/"],
      "outputDir": "docs-site/i18n",
      "docusaurusCatalogDir": "docs-site/i18n/en",
      "docsOutput": {
        "style": "docusaurus",
        "docsRoot": "docs-site/docs"
      }
    }
  ]
}

Wenn docusaurusCatalogDir gesetzt und features.translateDocs aktiviert ist, übersetzt translate-docs beides:

• Dokumentationsseiten – Markdown/MDX von contentPaths nach i18n/<locale>/docusaurus-plugin-content-docs/current/
• Shell-JSON – Navigationsleiste, Fußzeile und Theme-/Plugin-Kataloge von i18n/en/ in gleichgeordnete Sprachordner

Legen Sie Docusaurus-Shell-JSON nicht in json[] ab; verwenden Sie stattdessen docs[].docusaurusCatalogDir mit Dokumenten.

Beispielprojekt

examples/docusaurus-docs – Englische Quellen unter docs/, festgeschriebene Übersetzungen unter i18n/<locale>/docusaurus-plugin-content-docs/current/, plus übersetztes Shell-JSON. Führen Sie pnpm start auf Port 3100 aus (Build + Serve), damit die Sprachauswahl funktioniert; verwenden Sie pnpm dev für den englischsprachigen Hot Reload.

Für UI-Strings, SVG-Übersetzung und eine flache README im selben Repository-Layout siehe examples/nextjs-app (verschachteltes docs-site/ auf Port 3040).