البدء السريع لـ The Epic Stack

مقدمة

مُجمِّع Lingo.dev هو أداة مدعومة بالذكاء الاصطناعي تمكنك من توطين التطبيقات القائمة على React دون إجراء تغييرات على المكونات الحالية. ما عليك سوى تكوين بعض الأشياء، وتغليف تطبيقك في موفر سياق، وهذا كل شيء - تم توطين تطبيقك.

يشرح هذا الدليل كيفية إعداد مُجمِّع Lingo.dev مع The Epic Stack، وهو إطار تطبيق ويب متكامل من Kent C. Dodds مبني على Remix.

ما ستتعلمه

• كيفية تهيئة مُجمِّع Lingo.dev في The Epic Stack
• كيفية تكوين المُجمِّع للتوافق مع The Epic Stack
• كيفية إعداد مبدل اللغات للتبديل بين اللغات المحلية

الخطوة 1. إعداد مفتاح API

يستخدم مُجمِّع Lingo.dev نماذج اللغة الكبيرة (LLMs) لتوطين التطبيقات باستخدام الذكاء الاصطناعي. لاستخدام أحد هذه النماذج، تحتاج إلى مفتاح API من مزود مدعوم.

للبدء بأسرع وقت ممكن، نوصي باستخدام محرك Lingo.dev - منصتنا المستضافة التي توفر 10,000 رمز من الاستخدام المجاني الشهري.

لإعداد مفتاح API:

1. قم بتسجيل الدخول إلى محرك Lingo.dev.

2. انتقل إلى صفحة المشاريع.

3. انقر على مفتاح API > نسخ.

4. قم بتخزين مفتاح API في متغير بيئي:

   export LINGODOTDEV_API_KEY="<your_api_key>"

بديل: مزودو LLM المخصصون

لست مضطرًا لاستخدام محرك Lingo.dev. يمكنك تكوين المُجمِّع للتكامل مع عدد من مزودي LLM المخصصين، بما في ذلك:

• Groq
• Google
• Mistral
• Ollama
• OpenRouter

الخطوة 2. تثبيت الحزمة

يتم توزيع مُجمِّع Lingo.dev كجزء من حزمة npm lingo.dev. لتثبيته، استخدم مدير الحزم المفضل لديك:

npm install lingo.dev

الخطوة 3. تهيئة المُجمِّع

يتكامل مُجمِّع Lingo.dev مع Vite ويعمل أثناء وقت البناء. للارتباط بعملية بناء Vite، قم بإجراء التغييرات التالية على ملف vite.config.ts:

1. استيراد المُجمِّع:

   import lingoCompiler from "lingo.dev/compiler";

2. تهيئة المُجمِّع باستخدام طريقة vite:

   const withLingo = lingoCompiler.vite({
     sourceRoot: "app",
     lingoDir: "lingo",
     sourceLocale: "en",
     targetLocales: ["es"],
     rsc: false,
     useDirective: false,
     debug: false,
     models: "lingo.dev",
   });

   للتوافق مع The Epic Stack، تأكد من أن:

   • sourceRoot مضبوط على "app"
   • rsc مضبوط على false

   لمعرفة المزيد عن الخيارات المتاحة، راجع خيارات المُجمِّع.

3. دمج تكوين المُجمِّع مع التكوين الحالي وتصديره:

   export default defineConfig((config) => {
     const configWithSentry = {
       ...viteConfig,
       plugins: [
         ...viteConfig.plugins!.filter(Boolean),
         MODE === "production" && process.env.SENTRY_AUTH_TOKEN
           ? sentryReactRouter(sentryConfig, config)
           : null,
       ].filter(Boolean),
     };
   
     return withLingo(configWithSentry);
   });

مع هذا التكوين، سيقوم مُجمِّع Lingo.dev بما يلي:

• تصفح شجرة الصياغة المجردة (AST) لقاعدة الشفرة
• العثور على المحتوى القابل للترجمة (أي النص في عناصر JSX وقيم السمات المعينة)
• استخدام نموذج (نماذج) الذكاء الاصطناعي المُكوَّن لإنشاء الترجمات
• تخزين المحتوى الأصلي والمترجم في ملف dictionary.js
• استبدال المحتوى المترجم بعناصر نائبة

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

بعد أن يعالج المُجمِّع تطبيقك وينشئ الترجمات، تحتاج إلى تحميل وتقديم هذا المحتوى المترجم للمستخدمين. يتضمن ذلك:

• تحميل القاموس المناسب بناءً على تفضيل اللغة المحلية للمستخدم
• توفير الترجمات المحمّلة لتطبيقك من خلال مزود السياق

تحميل القاموس

في ملف app/root.tsx:

1. استيراد دالة loadDictionary من lingo.dev/react/react-router:

   import { loadDictionary } from "lingo.dev/react/react-router";

   هذه الدالة:

   • تسترجع اللغة الحالية من ملف تعريف الارتباط lingo-locale
   • ترجع إلى "en" عندما لا تكون اللغة محددة
   • تقوم بتحميل المحتوى المترجم من ملف dictionary.js

2. استدعاء دالة loadDictionary من دالة loader:

   const lingoDictionary = await loadDictionary(request);

3. إرجاع القاموس كجزء من بيانات التحميل:

   return data(
     {
       user,
       requestInfo: {
         hints: getHints(request),
         origin: getDomainUrl(request),
         path: new URL(request.url).pathname,
         userPrefs: {
           theme: getTheme(request),
         },
       },
       ENV: getEnv(),
       toast,
       honeyProps,
       lingoDictionary,
     },
     {
       headers: combineHeaders(
         { "Server-Timing": timings.toString() },
         toastHeaders,
       ),
     },
   );

توفير الترجمات

في ملف app/root.tsx:

1. استيراد مكون LingoProvider من lingo.dev/react/client:

   import { LingoProvider } from "lingo.dev/react/client";

   هذا المكون هو موفر سياق React يقوم باستبدال العناصر النائبة التي تم إنشاؤها بواسطة المترجم بالمحتوى المترجم.

2. في مكون Layout، احصل على البيانات من محمل البيانات:

   const data = useLoaderData<typeof loader | null>();

3. قم بتغليف التطبيق في مكون LingoProvider:

   <LingoProvider>{/* كود التطبيق الحالي */}</LingoProvider>

4. قم بتمرير القاموس المحمل إلى المكون:

   <LingoProvider dictionary={data?.lingoDictionary}>
     {/* كود التطبيق الحالي */}
   </LingoProvider>

الخطوة 5. إعداد مبدل اللغات

لتمكين المستخدمين من التبديل بين اللغات، قم باستيراد LocaleSwitcher من حزمة lingo.dev. هذا مكون غير منسق يقوم بما يلي:

• عرض قائمة منسدلة باللغات المتاحة
• يتيح للمستخدمين اختيار لغة
• يتذكر اللغة المحددة للزيارات القادمة

لاستخدام المكون، قم بتضمينه في أي مكان في تطبيقك وقم بتعيين خاصية locales إلى مصفوفة تحتوي على لغات المصدر والهدف المكونة:

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

البديل: مبدل اللغات المخصص

لست مضطرًا لاستخدام مكون LocaleSwitcher. يمكنك تنفيذ منطق وواجهة مستخدم مخصصة لتبديل اللغات. المتطلب الوحيد هو قراءة وكتابة اللغة النشطة في ملف تعريف الارتباط lingo-locale.

الخطوة 6. تشغيل التطبيق

للتحقق من أن مترجم Lingo.dev قد تم إعداده بشكل صحيح:

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

   npm run dev

2. انتقل إلى localhost:3000.

3. استخدم مكون LocaleSwitcher للتبديل بين اللغات.

يجب أن تتم إعادة تحميل الصفحة وعرض المحتوى المترجم.

البديل: تعيين ملفات تعريف الارتباط يدويًا

إذا كنت لا تستخدم مكون LocaleSwitcher، فهناك طريقة بديلة للتحقق من أن الترجمة تعمل وهي عن طريق تعيين ملف تعريف الارتباط lingo-locale يدويًا.

إذا كنت تستخدم متصفح Google Chrome، اتبع هذه التعليمات:

1. انتقل إلى عرض > المطور > أدوات المطور.
2. اذهب إلى علامة التبويب التطبيق.
3. في الشريط الجانبي الأيسر، ضمن التخزين، قم بتوسيع ملفات تعريف الارتباط وحدد عنوان URL للموقع.
4. في جدول ملفات تعريف الارتباط، انقر بزر الماوس الأيمن في أي مكان وحدد إضافة.
5. في عمود الاسم، أدخل lingo-locale.
6. في عمود القيمة، أدخل اللغة المطلوبة (مثل es).
7. اضغط على Enter لحفظ ملف تعريف الارتباط.
8. قم بتحديث الصفحة لتطبيق ملف تعريف الارتباط.

قراءة إضافية

• لفهم كيفية عمل المترجم، راجع كيف يعمل.
• لمعرفة كيفية تكوين المترجم، راجع خيارات المترجم.