Fumadocs

الترجمة بالذكاء الاصطناعي لـ Fumadocs باستخدام Lingo.dev CLI

ما هو Fumadocs؟

Fumadocs هو إطار عمل مفتوح المصدر للتوثيق. يوفر موقع توثيق سريع وآمن من حيث الأنواع مع بحث مدمج ودعم للترجمة وواجهة مستخدم جميلة.

ما هو Lingo.dev CLI؟

Lingo.dev هي منصة ترجمة مدعومة بالذكاء الاصطناعي. يقرأ Lingo.dev CLI الملفات المصدرية، ويرسل المحتوى القابل للترجمة إلى نماذج اللغة الكبيرة، ويكتب الملفات المترجمة مرة أخرى إلى مشروعك.

حول هذا الدليل

يشرح هذا الدليل كيفية إعداد Lingo.dev CLI في موقع توثيق Fumadocs. ستتعلم كيفية إنشاء مشروع باستخدام Fumadocs، وإعداد خط أنابيب الترجمة، وعرض النتائج.

الخطوة 1. إعداد مشروع Fumadocs

  1. إنشاء تطبيق Fumadocs جديد:

    npm create fumadocs-app

  2. اتبع المطالبات لتكوين المشروع بالإعدادات المفضلة.

  3. الانتقال إلى دليل المشروع:

    cd <project-name>

الخطوة 2. تكوين دعم الترجمة

يحتاج Fumadocs إلى معرفة اللغات التي سيدعمها التوثيق الخاص بك. ستقوم بإنشاء ملفات تكوين تخبر Fumadocs بكيفية التعامل مع لغات متعددة.

  1. إنشاء ملف lib/i18n.ts لتحديد اللغات المدعومة:

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

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

  2. تحديث ملف lib/source.ts لاستخدام إعدادات 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. إنشاء middleware للكشف عن تفضيل اللغة للمستخدمين وإعادة توجيههم بناءً عليه:

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

الخطوة 3. تحديث بنية التطبيق للغات متعددة

  1. إنشاء دليل معامل اللغة في مجلد app/:

    mkdir app/[lang]

  2. انقل صفحاتك الحالية إلى دليل معامل اللغة:

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

  3. أنشئ ملف app/[lang]/layout.tsx لتغليف جميع صفحاتك الخاصة باللغة:

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

الخطوة 4. إنشاء خيارات التخطيط المشتركة

  1. أنشئ ملف lib/layout.shared.tsx لإعدادات التخطيط المشتركة:

    // 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. حدّث ملف app/[lang]/docs/layout.tsx لاستخدام الخيارات المشتركة:

    // 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. حدّث ملف app/[lang]/(home)/layout.tsx لاستخدام الخيارات المشتركة:

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

الخطوة 5. تحديث مكونات الصفحة

حدّث مكونات الصفحة (مثل app/[lang]/docs/[[...slug]]/page.tsx) للتعامل مع معامل اللغة:

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

الخطوة 6. تنظيم المحتوى للترجمة

  1. أنشئ أدلة خاصة باللغة للمحتوى:

    mkdir -p content/docs/en

  2. انقل ملفات MDX الحالية إلى دليل اللغة الإنجليزية:

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

الخطوة 7. تكوين واجهة سطر الأوامر

في جذر المشروع، أنشئ ملف i18n.json:

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

يحدد هذا الملف:

  • الملفات التي يجب على Lingo.dev CLI ترجمتها
  • اللغات المراد الترجمة بينها

في هذه الحالة، يترجم التكوين ملفات MDX من الإنجليزية إلى الإسبانية.

من المهم ملاحظة أن:

  • [locale] هو عنصر نائب يتم استبداله في وقت التشغيل. يضمن قراءة المحتوى من موقع واحد (مثل src/content/docs/en/index.mdx) وكتابته إلى موقع مختلف (مثل src/content/docs/es/index.mdx).
  • لا يدعم Lingo.dev CLI أنماط glob العودية (مثل **/*.mdx). ستحتاج إلى إنشاء أنماط include إضافية لترجمة الملفات الموجودة داخل الدلائل المتداخلة.

لمعرفة المزيد، راجع تكوين i18n.json.

الخطوة 8. ترجمة المحتوى

  1. سجل للحصول على حساب Lingo.dev.

  2. سجل الدخول إلى Lingo.dev عبر CLI:

    npx lingo.dev@latest login

  3. قم بتشغيل خط أنابيب الترجمة:

    npx lingo.dev@latest run

    سينشئ CLI دليل content/docs/es/ لتخزين المحتوى المترجم وملف i18n.lock لتتبع ما تمت ترجمته (لمنع إعادة الترجمة غير الضرورية).

الخطوة 9. عرض الوثائق المترجمة

  1. ابدأ خادم التطوير:

    npm run dev

  2. انتقل إلى عناوين URL التالية: