Fumadocs

Traduction IA pour Fumadocs avec Lingo.dev CLI

Qu'est-ce que Fumadocs ?

Fumadocs est un framework de documentation open source. Il fournit un site de documentation rapide et type-safe avec recherche intégrée, support de l'internationalisation et une interface utilisateur élégante.

Qu'est-ce que Lingo.dev CLI ?

Lingo.dev est une plateforme de traduction alimentée par l'IA. Le CLI Lingo.dev lit les fichiers sources, envoie le contenu traduisible aux grands modèles de langage et réécrit les fichiers traduits dans votre projet.

À propos de ce guide

Ce guide explique comment configurer Lingo.dev CLI dans un site de documentation Fumadocs. Vous apprendrez comment créer un projet avec Fumadocs, configurer un pipeline de traduction et visualiser les résultats.

Étape 1. Configurer un projet Fumadocs

  1. Créez une nouvelle application Fumadocs :

    npm create fumadocs-app

  2. Suivez les invites pour configurer le projet avec les paramètres préférés.

  3. Accédez au répertoire du projet :

    cd <project-name>

Étape 2. Configurer le support de l'internationalisation

Fumadocs doit savoir quelles langues votre documentation prendra en charge. Vous allez créer des fichiers de configuration qui indiquent à Fumadocs comment gérer plusieurs langues.

  1. Créez un fichier lib/i18n.ts pour définir les langues prises en charge :

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

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

  2. Mettez à jour le fichier lib/source.ts pour utiliser les paramètres i18n :

    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. Créez un middleware pour détecter et rediriger les utilisateurs en fonction de leur préférence linguistique :

    // 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).*)"],
};

Étape 3. Mettre à jour la structure de l'application pour plusieurs langues

  1. Créez un répertoire de paramètre de langue dans le dossier app/ :

    mkdir app/[lang]

  2. Déplacez vos pages existantes dans le répertoire du paramètre de langue :

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

  3. Créez un fichier app/[lang]/layout.tsx pour englober toutes vos pages spécifiques à la langue :

    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>
  );
}

Étape 4. Créer les options de mise en page partagées

  1. Créez un fichier lib/layout.shared.tsx pour les configurations de mise en page partagées :

    // 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. Mettez à jour le fichier app/[lang]/docs/layout.tsx pour utiliser les options partagées :

    // 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. Mettez à jour le fichier app/[lang]/(home)/layout.tsx pour utiliser les options partagées :

    // 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>;
}

Étape 5. Mettre à jour les composants de page

Mettez à jour les composants de page (par exemple, app/[lang]/docs/[[...slug]]/page.tsx) pour gérer le paramètre de langue :

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,
  };
}

Étape 6. Organiser le contenu pour la traduction

  1. Créez des répertoires spécifiques à chaque langue pour le contenu :

    mkdir -p content/docs/en

  2. Déplacez les fichiers MDX existants dans le répertoire anglais :

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

Étape 7. Configurer le CLI

À la racine du projet, créez un fichier i18n.json :

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

Ce fichier définit :

  • les fichiers que le CLI Lingo.dev doit traduire
  • les langues entre lesquelles traduire

Dans ce cas, la configuration traduit les fichiers MDX de l'anglais vers l'espagnol.

Il est important de noter que :

  • [locale] est un espace réservé qui est remplacé à l'exécution. Il garantit que le contenu est lu depuis un emplacement (par exemple, src/content/docs/en/index.mdx) et écrit vers un emplacement différent (par exemple, src/content/docs/es/index.mdx).
  • La CLI Lingo.dev ne prend pas en charge les motifs glob récursifs (par exemple, **/*.mdx). Vous devrez créer des motifs include supplémentaires pour traduire les fichiers qui existent dans des répertoires imbriqués.

Pour en savoir plus, consultez Configuration i18n.json.

Étape 8. Traduire le contenu

  1. Créez un compte Lingo.dev.

  2. Connectez-vous à Lingo.dev via la CLI :

    npx lingo.dev@latest login

  3. Exécutez le pipeline de traduction :

    npx lingo.dev@latest run

    La CLI créera un répertoire content/docs/es/ pour stocker le contenu traduit et un fichier i18n.lock pour suivre ce qui a été traduit (afin d'éviter les retraductions inutiles).

Étape 9. Afficher la documentation traduite

  1. Démarrez le serveur de développement :

    npm run dev

  2. Accédez aux URL suivantes :