Fumadocs

KI-Übersetzung für Fumadocs mit Lingo.dev CLI

Was ist Fumadocs?

Fumadocs ist ein Open-Source-Dokumentations-Framework. Es bietet eine schnelle, typsichere Dokumentationswebsite mit integrierter Suche, Internationalisierungsunterstützung und einer ansprechenden Benutzeroberfläche.

Was ist Lingo.dev CLI?

Lingo.dev ist eine KI-gestützte Übersetzungsplattform. Die Lingo.dev CLI liest Quelldateien, sendet übersetzbare Inhalte an Large Language Models und schreibt die übersetzten Dateien zurück in dein Projekt.

Über diesen Leitfaden

Dieser Leitfaden erklärt, wie man die Lingo.dev CLI in einer Fumadocs-Dokumentationswebsite einrichtet. Du lernst, wie man ein Projekt mit Fumadocs erstellt, eine Übersetzungspipeline einrichtet und die Ergebnisse betrachtet.

Schritt 1. Einrichten eines Fumadocs-Projekts

  1. Erstelle eine neue Fumadocs-Anwendung:

    npm create fumadocs-app

  2. Folge den Anweisungen, um das Projekt mit den bevorzugten Einstellungen zu konfigurieren.

  3. Navigiere in das Projektverzeichnis:

    cd <project-name>

Schritt 2. Konfigurieren der Internationalisierungsunterstützung

Fumadocs muss wissen, welche Sprachen deine Dokumentation unterstützen wird. Du wirst Konfigurationsdateien erstellen, die Fumadocs mitteilen, wie mehrere Sprachen zu handhaben sind.

  1. Erstelle eine lib/i18n.ts Datei, um die unterstützten Sprachen zu definieren:

    import { defineI18n } from 'fumadocs-core/i18n';

export const i18n = defineI18n({
  defaultLanguage: 'en',
  languages: ['en', 'es'],
  parser: "dir",
});

  2. Aktualisiere die lib/source.ts Datei, um die i18n-Einstellungen zu verwenden:

    import { docs } from "@/.source";
import { loader } from "fumadocs-core/source";
import { i18n } from "@/lib/i18n";

// See https://fumadocs.vercel.app/docs/headless/source-api for more info
export const source = loader({
  // it assigns a URL to your pages
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
  i18n,
});

  3. Erstelle einen Middleware, um Benutzer basierend auf ihren Sprachpräferenzen zu erkennen und weiterzuleiten:

    // middleware.ts
import { createI18nMiddleware } from 'fumadocs-core/i18n/middleware';
import { i18n } from '@/lib/i18n';

export default createI18nMiddleware(i18n);

export const config = {
  // Matcher ignoring `/_next/` and `/api/`
  // You may need to adjust it to ignore static assets in `/public` folder
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

Schritt 3. App-Struktur für mehrere Sprachen aktualisieren

  1. Erstellen Sie ein Sprachparameter-Verzeichnis im app/-Ordner:

    mkdir app/[lang]

  2. Verschieben Sie Ihre bestehenden Seiten in das Sprachparameter-Verzeichnis:

    • app/docs/ → app/[lang]/docs/
    • app/(home)/ → app/[lang]/(home)/

  3. Erstellen Sie eine app/[lang]/layout.tsx-Datei, um alle Ihre sprachspezifischen Seiten zu umschließen:

    import { RootProvider } from "fumadocs-ui/provider";
import { defineI18nUI } from "fumadocs-ui/i18n";
import { i18n } from "@/lib/i18n";

const { provider } = defineI18nUI(i18n, {
  translations: {
    en: {
      displayName: "English",
    },
    es: {
      displayName: "Español",
    },
  },
});

export default async function RootLayout({
  params,
  children,
}: LayoutProps<"/[lang]">) {
  const lang = (await params).lang;

  return (
    <html lang={lang}>
      <body>
        <RootProvider i18n={provider(lang)}>{children}</RootProvider>
      </body>
    </html>
  );
}

Schritt 4. Gemeinsame Layout-Optionen erstellen

  1. Erstellen Sie eine lib/layout.shared.tsx-Datei für gemeinsame Layout-Konfigurationen:

    // lib/layout.shared.tsx
import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
import { i18n } from "@/lib/i18n";

/**
 * Gemeinsame Layout-Konfigurationen
 *
 * Sie können Layouts individuell anpassen von:
 * Home Layout: app/(home)/layout.tsx
 * Docs Layout: app/docs/layout.tsx
 */
export function baseOptions(locale: string): BaseLayoutProps {
  return {
    i18n,
    nav: {
      title: (
        <>
          <svg
            width="24"
            height="24"
            xmlns="http://www.w3.org/2000/svg"
            aria-label="Logo"
          >
            <circle cx={12} cy={12} r={12} fill="currentColor" />
          </svg>
          My App
        </>
      ),
    },
    // siehe https://fumadocs.dev/docs/ui/navigation/links
    links: [],
  };
}

  2. Aktualisieren Sie die app/[lang]/docs/layout.tsx-Datei, um die gemeinsamen Optionen zu verwenden:

    // app/[lang]/docs/layout.tsx
import type { ReactNode } from "react";
import { source } from "@/lib/source";
import { DocsLayout } from "fumadocs-ui/layouts/docs";
import { baseOptions } from "@/lib/layout.shared";

export default async function Layout({
  params,
  children,
}: LayoutProps<"/[lang]/docs">) {
  const { lang } = await params;

  return (
    <DocsLayout {...baseOptions(lang)} tree={source.pageTree[lang]}>
      {children}
    </DocsLayout>
  );
}

  3. Aktualisieren Sie die app/[lang]/(home)/layout.tsx-Datei, um die gemeinsamen Optionen zu verwenden:

    // app/[lang]/(home)/layout.tsx
import { HomeLayout } from "fumadocs-ui/layouts/home";
import { baseOptions } from "@/lib/layout.shared";

export default async function Layout({
  children,
  params,
}: LayoutProps<"/[lang]">) {
  const { lang } = await params;
  return <HomeLayout {...baseOptions(lang)}>{children}</HomeLayout>;
}

Schritt 5. Aktualisieren der Seitenkomponenten

Aktualisieren Sie die Seitenkomponenten (z.B. app/[lang]/docs/[[...slug]]/page.tsx), um den Sprachparameter zu verarbeiten:

import { source } from "@/lib/source";
import {
  DocsBody,
  DocsDescription,
  DocsPage,
  DocsTitle,
} from "fumadocs-ui/page";
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { createRelativeLink } from "fumadocs-ui/mdx";
import { getMDXComponents } from "@/mdx-components";

export default async function Page(
  props: PageProps<"/[lang]/docs/[[...slug]]">,
) {
  const params = await props.params;
  const page = source.getPage(params.slug, params.lang);
  if (!page) notFound();

  const MDXContent = page.data.body;

  return (
    <DocsPage toc={page.data.toc} full={page.data.full}>
      <DocsTitle>{page.data.title}</DocsTitle>
      <DocsDescription>{page.data.description}</DocsDescription>
      <DocsBody>
        <MDXContent
          components={getMDXComponents({
            // this allows you to link to other pages with relative file paths
            a: createRelativeLink(source, page),
          })}
        />
      </DocsBody>
    </DocsPage>
  );
}

export async function generateStaticParams() {
  return source.generateParams();
}

export async function generateMetadata(
  props: PageProps<"/[lang]/docs/[[...slug]]">,
): Promise<Metadata> {
  const params = await props.params;
  const page = source.getPage(params.slug, params.lang);
  if (!page) notFound();

  return {
    title: page.data.title,
    description: page.data.description,
  };
}

Schritt 6. Inhalte für die Übersetzung organisieren

  1. Erstellen Sie sprachspezifische Verzeichnisse für den Inhalt:

    mkdir -p content/docs/en

  2. Verschieben Sie die vorhandenen MDX-Dateien in das englische Verzeichnis:

    • content/docs/index.mdx → content/docs/en/index.mdx
    • content/docs/test.mdx → content/docs/en/test.mdx

Schritt 7. Konfigurieren der CLI

Erstellen Sie im Stammverzeichnis des Projekts eine i18n.json-Datei:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "mdx": {
      "include": ["content/docs/[locale]/*.mdx"]
    }
  }
}

Diese Datei definiert:

  • die Dateien, die Lingo.dev CLI übersetzen soll
  • die Sprachen, zwischen denen übersetzt werden soll

In diesem Fall übersetzt die Konfiguration MDX-Dateien von Englisch nach Spanisch.

Es ist wichtig zu beachten, dass:

  • [locale] ein Platzhalter ist, der zur Laufzeit ersetzt wird. Er stellt sicher, dass Inhalte von einem Ort (z.B. src/content/docs/en/index.mdx) gelesen und an einen anderen Ort (z.B. src/content/docs/es/index.mdx) geschrieben werden.
  • Lingo.dev CLI unterstützt keine rekursiven Glob-Muster (z.B. **/*.mdx). Sie müssen zusätzliche include-Muster erstellen, um Dateien zu übersetzen, die in verschachtelten Verzeichnissen existieren.

Weitere Informationen finden Sie unter i18n.json-Konfiguration.

Schritt 8. Übersetzen Sie den Inhalt

  1. Registrieren Sie sich für ein Lingo.dev-Konto.

  2. Melden Sie sich über die CLI bei Lingo.dev an:

    npx lingo.dev@latest login

  3. Führen Sie die Übersetzungspipeline aus:

    npx lingo.dev@latest run

    Die CLI erstellt ein Verzeichnis content/docs/es/ zum Speichern der übersetzten Inhalte und eine Datei i18n.lock, um zu verfolgen, was bereits übersetzt wurde (um unnötige Neuübersetzungen zu vermeiden).

Schritt 9. Anzeigen der übersetzten Dokumentation

  1. Starten Sie den Entwicklungsserver:

    npm run dev

  2. Navigieren Sie zu folgenden URLs: