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, typé de manière sécurisée avec une recherche intégrée, un support d'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 source, envoie le contenu traduisible aux modèles de langage avancés et écrit les fichiers traduits dans votre projet.

À propos de ce guide

Ce guide explique comment configurer le CLI Lingo.dev dans un site de documentation Fumadocs. Vous apprendrez comment structurer un projet avec Fumadocs, mettre en place 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 instructions pour configurer le projet avec les paramètres préférés.

  3. Naviguez dans le répertoire du projet :

    cd <project-name>

Étape 2. Configurer le support d'internationalisation

Fumadocs doit connaître les langues que 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";

// Voir https://fumadocs.vercel.app/docs/headless/source-api pour plus d'informations
export const source = loader({
  // cela attribue une URL à vos 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 ignorant `/_next/` et `/api/`
  // Vous devrez peut-être l'ajuster pour ignorer les ressources statiques dans le dossier `/public`
  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 de paramètre de langue :

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

  3. Créez un fichier app/[lang]/layout.tsx pour encapsuler 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 des 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";

/**
 * Configurations de mise en page partagées
 *
 * vous pouvez personnaliser les mises en page individuellement à partir de :
 * Mise en page d'accueil : app/(home)/layout.tsx
 * Mise en page de la documentation : 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
        </>
      ),
    },
    // voir 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.8,
  "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 placeholder 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 à un emplacement différent (par exemple, src/content/docs/es/index.mdx).
  • Le CLI Lingo.dev ne prend pas en charge les modèles glob récursifs (par exemple, **/*.mdx). Vous devrez créer des modèles 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 l'interface de ligne de commande :

    npx lingo.dev@latest login

  3. Exécutez le pipeline de traduction :

    npx lingo.dev@latest run

    L'interface de ligne de commande 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. Visualiser la documentation traduite

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

    npm run dev

  2. Naviguez vers les URL suivantes :