كيف يعمل

يحوّل @lingo.dev/compiler تطبيق React الخاص بك إلى تطبيق متعدد اللغات في وقت البناء من خلال تحليل الكود الذكي والترجمة المدعومة بالذكاء الاصطناعي.

التحويل في وقت البناء

تعمل مكتبات i18n التقليدية في وقت التشغيل (i18next، react-intl) أثناء التشغيل—حيث تقوم بتحميل الترجمات، وإدراج القيم، وتنسيق الرسائل أثناء تشغيل تطبيقك. وهذا يضيف حجمًا إلى الحزمة، وعبئًا على وقت التشغيل، وتعقيدًا.

يعمل @lingo.dev/compiler بشكل مختلف: فهو يحوّل الكود الخاص بك أثناء عملية البناء. تظل مكونات React الخاصة بك نظيفة، ويتم تجميع الترجمات مسبقًا في حزم محسّنة.

النتيجة: عدم وجود عبء على وقت التشغيل، وحزم أصغر، وعدم الحاجة لإدارة مفاتيح الترجمة يدويًا.

العملية

1. تحليل AST

يستخدم المترجم Babel لتحليل كود React الخاص بك إلى شجرة بناء جملة مجردة (AST). يتنقل عبر JSX الخاص بك، محددًا المحتوى القابل للترجمة:

  • عقد النص (<p>Hello</p>)
  • سمات النص (<img alt="Logo" />)
  • النص في تعبيرات القوالب (<p>Hello {name}</p>)

يفهم المترجم حدود مكونات React ويحافظ على المعلومات السياقية للحصول على ترجمات دقيقة. يتم تصفية المعرّفات التقنية ومقتطفات الكود والعناصر غير القابلة للترجمة تلقائيًا.

2. استخراج المحتوى

لكل نص قابل للترجمة، يقوم المترجم بـ:

  • إنشاء معرّف مستقر يعتمد على التجزئة
  • الحفاظ على سياق المكون (الملف، الموقع، العناصر المحيطة)
  • استخراج بنية النص الغني (يتعامل مع العناصر المتداخلة مثل <strong> و <em>)
  • الحفاظ على عناصر الإدراج النائبة

يتم تخزين هذه البيانات الوصفية في .lingo/metadata.json—ملف مُصدّر يتتبع جميع المحتويات القابلة للترجمة في تطبيقك.

3. إنشاء الترجمة

أثناء التطوير، يتعامل خادم الترجمة مع الترجمة عند الطلب:

  • وضع المترجم الزائف (افتراضي): ينشئ ترجمات وهمية فورية—مفيد لرؤية ما يتم ترجمته دون تكاليف API
  • وضع الترجمة الحقيقية: يستدعي موفر LLM المُكوّن لديك (محرك Lingo.dev أو LLM مباشر)

خدمة الترجمة عديمة الحالة وتتعامل مع الأعطال الجزئية بسلاسة—إذا فشلت بعض الترجمات، يتم استخدام الترجمات المخزنة مؤقتًا.

4. حقن الكود

يقوم المترجم بحقن عمليات البحث عن الترجمة في JSX الخاص بك:

// Your source code
<p>Hello {name}</p>

// Transformed code (simplified)
<p>{t('abc123', { name })}</p>

الدالة t() محسّنة ويتم حقنها تلقائيًا. تقوم بعمليات بحث قائمة على التجزئة في قواميس الترجمة المحملة مسبقًا.

5. تحسين الحزمة

في وقت البناء:

  • يتم إنشاء حزم لكل لغة
  • يتم تضمين الترجمات المستخدمة فقط
  • تزيل عملية إزالة الكود الميت الترجمات غير المستخدمة
  • يتم تقليص القواميس لكل مكون

سير عمل التطوير

وضع التطوير

{
  dev: {
    usePseudotranslator: true,
  }
}

عند تشغيل npm run dev:

  1. يبدأ المترجم خادم ترجمة (يجد المنافذ تلقائيًا من 60000 إلى 60099)
  2. يقوم تطبيقك بإرسال طلبات إلى الخادم للحصول على الترجمات
  3. ينشئ المترجم الزائف ترجمات وهمية فورية
  4. يتم تخزين الترجمات مؤقتًا في .lingo/metadata.json
  5. يعمل HMR بشكل طبيعي—يتم الحفاظ على الحالة

تتيح لك أداة التطوير (إذا تم تمكينها) تحرير الترجمات في المتصفح ورؤية التغييرات في الوقت الفعلي.

وضع الإنتاج

{
  buildMode: "cache-only",
}

عند تشغيل npm run build:

  1. لا يبدأ خادم الترجمة
  2. يتم استخدام الترجمات المخزنة مؤقتًا من .lingo/metadata.json فقط
  3. إذا كانت أي ترجمات مفقودة، يفشل البناء مع رسالة خطأ واضحة
  4. لا يتم إجراء استدعاءات API—لا حاجة لمفاتيح API

لماذا التخزين المؤقت فقط؟ في الإنتاج، تريد عمليات بناء حتمية. يجب إنشاء الترجمات في CI (حيث لديك مفاتيح API)، وليس أثناء عمليات البناء الإنتاجية.

سير العمل الموصى به

التطوير المحلي:

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

CI/CD:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}
  • إنشاء ترجمات حقيقية
  • التشغيل مرة واحدة لكل نشر
  • تثبيت تغييرات .lingo/

بناء الإنتاج:

{
  buildMode: "cache-only",
}
  • استخدام الترجمات المُنشأة مسبقًا
  • لا حاجة لمفاتيح API
  • عمليات بناء سريعة وحتمية

البنية المعمارية

المُترجم منظم حول فصل واضح للمسؤوليات:

مدير البيانات الوصفية

  • عمليات CRUD لـ .lingo/metadata.json
  • آمن للخيوط المتعددة مع قفل الملفات
  • معرّفات قائمة على التجزئة للترجمات

خدمة الترجمة

  • تنسيق سير عمل الترجمة
  • إدارة استراتيجية التخزين المؤقت
  • إدارة الإخفاقات الجزئية
  • إرجاع الترجمات الناجحة والأخطاء

المترجمون (بدون حالة)

  • المترجم الزائف: ترجمات وهمية فورية
  • مترجم LCP: تكامل محرك Lingo.dev
  • مترجمو LLM: تكامل مباشر مع المزود
  • لا يوجد تخزين مؤقت مدمج—طبقة الخدمة تتولى ذلك

خادم الترجمة

  • خادم HTTP للتطوير
  • دعم WebSocket للتحديثات الفورية للواجهة
  • إدارة تلقائية للمنافذ
  • معالجة الطلبات الدفعية

راجع مستند بنية الكود المصدري لتفاصيل التنفيذ.

تكامل إطار العمل

Next.js

يتكامل المُترجم عبر غلاف withLingo():

  • يدعم كلاً من Webpack وTurbopack
  • يعمل مع مكونات خادم React
  • إعداد غير متزامن لتحميل الإضافة الكسول
  • توجيه تلقائي قائم على اللغة (إذا تم تكوينه)

Vite

يتكامل المُترجم عبر lingoCompilerPlugin:

  • قائم على Unplugin (يعمل مع Vite وWebpack وRollup)
  • دعم كامل لـ HMR
  • تكامل فعال مع خادم التطوير
  • إنشاء تلقائي للوحدات الافتراضية

الأسئلة الشائعة

هل يعمل هذا مع مكونات الخادم؟ نعم. في Next.js، يحوّل المُترجم كلاً من مكونات الخادم والعميل. عمليات البحث عن الترجمة تعمل بشكل متماثل.

ماذا عن تقسيم الكود؟ يتم تقسيم الترجمات تلقائيًا جنبًا إلى جنب مع مكوناتك. كل جزء يتضمن فقط الترجمات التي يحتاجها.

كيف يتم تخزين الترجمات مؤقتًا؟ يتم تخزين جميع الترجمات في .lingo/metadata.json. هذا الملف خاضع لإدارة الإصدارات ويعمل كذاكرة تخزين مؤقت للترجمة. يستخدم المُترجم تجزئة المحتوى—فقط النص الجديد أو المُعدّل يؤدي إلى إعادة الترجمة.

ماذا لو فشلت الترجمة؟ تُرجع الخدمة نتائج جزئية. يتم تخزين الترجمات الناجحة مؤقتًا واستخدامها، بينما يتم تسجيل الأخطاء مع السياق لتسهيل تصحيح الأخطاء. لن يتعطل تطبيقك—بل سيعود إلى الترجمات المخزنة مؤقتًا أو النص المصدر.

هل يمكنني رؤية الكود المُحوَّل؟ نعم. في مخرجات البناء الخاصة بك، ابحث عن الملفات المُحوَّلة. التحويلات بسيطة—مجرد استدعاءات دالة t() مع عمليات بحث قائمة على التجزئة.

الخطوات التالية