أفضل الممارسات

الأنماط وسير العمل الموصى بها لـ @lingo.dev/compiler.

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

استخدم المترجم الزائف بشكل افتراضي

افعل:

{
  dev: {
    usePseudotranslator: true, // Fast, free, instant feedback
  }
}

لماذا:

• ملاحظات فورية—بدون زمن انتقال API
• تكلفة صفرية—لا يتم استهلاك أرصدة API
• علامات مرئية توضح ما يتم ترجمته
• اختبار واجهة المستخدم بأطوال نصية متفاوتة

قم بالتعطيل فقط عند مراجعة جودة الترجمة الفعلية.

فصل بيئات التطوير والتكامل المستمر والإنتاج

التطوير:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

التكامل المستمر:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

الإنتاج:

{
  buildMode: "cache-only",
}

يوفر سير العمل هذا:

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

استراتيجية الترجمة

دع الذكاء الاصطناعي يتولى معظم الترجمات

افعل:

<p>Welcome to our application</p>

لا تفعل:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our application
</p>

استخدم التجاوزات بشكل محدود—فقط لـ:

• أسماء العلامات التجارية
• المصطلحات التقنية التي تتطلب ترجمات محددة
• النصوص القانونية التي تتطلب اعتماداً
• المحتوى التسويقي الذي يحتاج إلى مراجعة بشرية

استخدم التجاوزات بشكل متسق

افعل:

// Consistent brand name across app
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

<p>
  Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
    Lingo.dev
  </span>
</p>

لا تفعل:

<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override—inconsistent

الإعدادات

ابدأ ببساطة

افعل:

{
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
}

لا تفعل:

{
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "pt", "it", "ja", "zh", "ar", "ru", "ko"],
  models: {
    "en:es": "groq:...",
    "en:de": "google:...",
    // Complex mappings for 10 locales
  },
  prompt: "Long custom prompt...",
  pluralization: { enabled: false },
}

ابدأ بـ 2-3 لغات مستهدفة. أضف المزيد حسب الحاجة. تجنب التحسين المبكر.

استخدم محرك Lingo.dev

افعل:

{
  models: "lingo.dev" // Simple, optimized, supports all features
}

لا تفعل:

{
  models: {
    "*:*": "groq:...", // Requires manual model selection
  }
}

يوفر محرك Lingo.dev:

• اختيار النموذج تلقائيًا
• معالجة الاحتياطية
• ذاكرة الترجمة
• دعم المسرد

استخدم موفري LLM المباشرين فقط إذا كنت بحاجة إلى تحكم كامل أو تحسين التكلفة.

اكتشاف اللغة

استخدم الاستمرارية الافتراضية المستندة إلى ملفات تعريف الارتباط

افعل:

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",
      maxAge: 31536000,
    },
  },
}

متى يجب التخصيص:

• الحاجة إلى localStorage (تفضيل SPA)
• التوجيه المستند إلى URL (/en/about)
• التوجيه بالنطاق الفرعي (es.example.com)
• تفضيلات المستخدم المدعومة بقاعدة البيانات

قم بتنفيذ محللات اللغة المخصصة فقط عندما لا يناسب الإعداد الافتراضي.

التحكم في الإصدار

قم بإيداع دليل .lingo/

افعل:

git add .lingo/
git commit -m "chore: update translations"
git push

لماذا:

• يتتبع نظام التحكم في الإصدارات تغييرات الترجمة
• يشارك الفريق الترجمات
• يستخدم CI/CD الترجمات المُلتزم بها
• لا تحتاج إصدارات الإنتاج إلى مفاتيح API

الالتزام بعد تشغيل CI

افعل (في CI):

- name: Generate translations
  run: npm run build

- name: Commit translations
  run: |
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

يضمن هذا أن إصدارات الإنتاج تحتوي دائمًا على ترجمات محدثة.

CI/CD

إنشاء الترجمات في CI

افعل:

# GitHub Actions
- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: npm run build

لا تفعل:

# Production build without API key
- name: Build
  run: npm run build # Fails if translations missing

أنشئ الترجمات في CI حيث تمتلك مفاتيح API. تستخدم إصدارات الإنتاج الترجمات المخزنة مؤقتًا.

استخدم cache-only في الإنتاج

افعل:

# Production build
LINGO_BUILD_MODE=cache-only npm run build

لا تفعل:

# Production build with translate mode
LINGO_BUILD_MODE=translate npm run build # Non-deterministic, requires API keys

الأداء

تفعيل صيغ الجمع بشكل انتقائي

افعل (إذا كنت تستخدم صيغ الجمع):

{
  pluralization: {
    enabled: true,
  }
}

افعل (إذا كنت لا تستخدم صيغ الجمع):

{
  pluralization: {
    enabled: false, // Skip plural detection—faster builds
  }
}

يضيف التعدد الصرفي عبئًا بسيطًا (استدعاء واحد لنموذج اللغة الكبير لكل نص يحتوي على أرقام). قم بتعطيله إذا لم يكن مطلوبًا.

استخدم نماذج سريعة للتعدد الصرفي

افعل:

{
  pluralization: {
    enabled: true,
    model: "groq:llama-3.1-8b-instant", // Fast, cheap
  }
}

لا تفعل:

{
  pluralization: {
    model: "openai:gpt-4o", // Expensive overkill for plural detection
  }
}

تحسين تعيين أزواج اللغات

افعل (تحسين التكلفة):

{/* CODE_PLACEHOLDER_28261613385b9e96f05e39a05137d80 */}

استخدم نماذج سريعة/رخيصة للغات المتشابهة (اللغات الرومانسية، الجرمانية). استخدم نماذج عالية الجودة للغات المعقدة (اللغات الصينية واليابانية والكورية، العربية).

الاختبار

اختبر باستخدام المترجم الزائف أولاً

افعل:

1. قم بتفعيل المترجم الزائف
2. اختبر جميع مكونات واجهة المستخدم
3. أصلح مشاكل التخطيط (الفيضان، الاقتطاع)
4. ثم قم بإنشاء الترجمات الحقيقية

السبب:

• الترجمات الزائفة فورية
• تكشف مشاكل التخطيط مبكرًا
• توفر تكاليف واجهة برمجة التطبيقات

اختبر جميع اللغات المستهدفة

افعل:

// Test with locale switcher
<LanguageSwitcher /> // Switch between all locales

// Or manually test
setLocale("es"); // Spanish
setLocale("de"); // German
setLocale("fr"); // French

تحقق من كل لغة:

• تظهر الترجمات بشكل صحيح
• يستوعب التخطيط طول النص
• لا يوجد نص غير مترجم
• تُعرض اللغات من اليمين إلى اليسار بشكل صحيح (إن أمكن)

معالجة الأخطاء

تعامل مع الترجمات المفقودة بشكل سلس

يفشل المترجم في البناء إذا كانت الترجمات مفقودة. هذا مقصود—من الأفضل اكتشاف الترجمات المفقودة مبكرًا بدلاً من شحن واجهة مستخدم معطلة.

إذا فشل البناء:

1. قم بالتشغيل باستخدام buildMode: "translate" لإنشاء الترجمات المفقودة
2. قم بتثبيت .lingo/metadata.json
3. أعد محاولة بناء الإنتاج باستخدام buildMode: "cache-only"

راقب فشل الترجمة

في التكامل المستمر، تحقق من أخطاء الترجمة:

- name: Generate translations
  run: npm run build 2>&1 | tee build.log

- name: Check for translation errors
  run: |
    if grep -q "Failed to generate translation" build.log; then
      echo "Translation generation failed"
      exit 1
    fi

الصيانة

التنظيف الدوري

قم بإزالة الترجمات غير المستخدمة بشكل دوري:

# Backup first
cp .lingo/metadata.json .lingo/metadata.backup.json

# Manual: Search for each hash in codebase, remove if not found

# Automated (coming soon):
npx @lingo.dev/compiler clean

مراقبة حجم الملف

ينمو .lingo/metadata.json مع تطبيقك. إذا أصبح كبيراً (>5 ميجابايت):

• فكر في التقسيم إلى تطبيقات متعددة
• أرشف الترجمات القديمة
• استخدم التنظيف الآلي

الأنماط المضادة الشائعة

لا تفرط في استخدام التجاوزات

سيئ:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our app
</p>

دع الذكاء الاصطناعي يتعامل مع النص العادي. التجاوزات مخصصة للاستثناءات.

لا تقم بإيداع مفاتيح API

سيئ:

// next.config.ts
{
  models: "lingo.dev",
  apiKey: "your-api-key-here", // NEVER commit API keys
}

جيد:

# .env (not committed)
LINGODOTDEV_API_KEY=your_key_here

لا تستخدم وضع الترجمة في الإنتاج

سيئ:

// production config
{
  buildMode: "translate", // Non-deterministic, requires API keys
}

جيد:

{
  buildMode: "cache-only", // Deterministic, no API keys
}

لا تتخطى التحكم في الإصدار

سيئ:

# .gitignore
.lingo/ # DON'T ignore translations

جيد:

# .gitignore
.env # Ignore API keys only

استراتيجية الترحيل

الطرح التدريجي

عند إضافة المترجم إلى تطبيق موجود:

1. ابدأ بلغة أو لغتين
2. فعّل المترجم الزائف
3. اختبر جميع الصفحات
4. أصلح مشاكل التخطيط
5. أضف المزيد من اللغات
6. أنشئ الترجمات الفعلية
7. انشر التطبيق

لا تحاول ترجمة 20 لغة في اليوم الأول.

التبني التدريجي

لا تحتاج إلى ترجمة التطبيق بالكامل دفعة واحدة:

{
  useDirective: true, // Opt-in per file
}

أضف التوجيه 'use i18n' إلى الملفات التي تريد ترجمتها:

'use i18n'; // This file gets translated

export function HomePage() {
  return <h1>Welcome</h1>;
}

تظل الملفات الأخرى غير مترجمة حتى تقوم بتفعيلها.

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

• دليل الترحيل — الترحيل من المترجم القديم
• استكشاف الأخطاء وإصلاحها — المشاكل الشائعة والحلول
• مرجع الإعدادات — شرح جميع الخيارات