Fumadocs

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

ما هو 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.8,
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "mdx": {
      "include": ["content/docs/[locale]/*.mdx"]
    }
  }
}

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

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

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

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

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

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

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

  1. قم بالتسجيل للحصول على حساب Lingo.dev.

  2. قم بتسجيل الدخول إلى Lingo.dev عبر واجهة سطر الأوامر:

    npx lingo.dev@latest login

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

    npx lingo.dev@latest run

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

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

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

    npm run dev

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