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 Dokumentationsseite 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 große Sprachmodelle und schreibt übersetzte Dateien zurück in Ihr Projekt.

Über diese Anleitung

Diese Anleitung erklärt, wie Sie Lingo.dev CLI in einer Fumadocs-Dokumentationsseite einrichten. Sie erfahren, wie Sie ein Projekt mit Fumadocs erstellen, eine Übersetzungs-Pipeline einrichten und die Ergebnisse anzeigen.

Schritt 1. Fumadocs-Projekt einrichten

  1. Erstellen Sie eine neue Fumadocs-Anwendung:

    npm create fumadocs-app

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

  3. Navigieren Sie in das Projektverzeichnis:

    cd <project-name>

Schritt 2. Internationalisierungsunterstützung konfigurieren

Fumadocs muss wissen, welche Sprachen Ihre Dokumentation unterstützen wird. Sie erstellen Konfigurationsdateien, die Fumadocs mitteilen, wie mehrere Sprachen verarbeitet werden sollen.

  1. Erstellen Sie eine lib/i18n.tsDatei, 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. Aktualisieren Sie die lib/source.tsDatei, 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. Erstellen Sie eine Middleware, um Benutzer basierend auf ihrer Sprachpräferenz 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 vorhandenen 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. Erstellen Sie gemeinsame Layout-Optionen

  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";

/**
 * Shared layout configurations
 *
 * you can customise layouts individually from:
 * 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
        </>
      ),
    },
    // see 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 Sie die 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. Organisieren Sie Inhalte für die Übersetzung

  1. Erstellen Sie sprachspezifische Verzeichnisse für die Inhalte:

    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 Sie die CLI

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

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

Diese Datei definiert:

  • die Dateien, die 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 Speicherort gelesen (z. B. src/content/docs/en/index.mdx) und an einen anderen Speicherort geschrieben werden (z. B. src/content/docs/es/index.mdx).
  • Die 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 sich in verschachtelten Verzeichnissen befinden.

Weitere Informationen finden Sie unter i18n.json-Konfiguration.

Schritt 8. Inhalte übersetzen

  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 Übersetzungs-Pipeline aus:

    npx lingo.dev@latest run

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

Schritt 9. Übersetzte Dokumentation anzeigen

  1. Starten Sie den Entwicklungsserver:

    npm run dev

  2. Navigieren Sie zu den folgenden URLs: