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

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

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

استخدم المحاكي الافتراضي دائمًا

يُفضل:

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

لماذا:

• تغذية راجعة فورية بدون تأخير في واجهة البرمجة
• مجاني تمامًا ولا يحتاج إلى أرصدة واجهة البرمجة
• علامات مرئية توضح ما تم ترجمته
• يختبر واجهة المستخدم مع أطوال نص متنوعة

عطّل هذه الميزة فقط عند مراجعة جودة الترجمة الحقيقية.

فصل بيئة التطوير، CI، والإنتاج

بيئة التطوير:

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

CI:

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

الإنتاج:

{
  buildMode: "cache-only",
}

هذا الأسلوب:

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

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

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

يُفضل:

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

ابدأ بلغتين أو ثلاث فقط. أضف المزيد عند الحاجة. تجنب التحسين المبكر.

استخدم محرك 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)
• التوجيه عبر الرابط (/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. أما نسخة الإنتاج فتستخدم الترجمات المخزنة مؤقتًا.

استخدم الكاش فقط في الإنتاج

افعل:

# 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
  }
}

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

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

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // Fast & cheap
    "en:ja": "openai:gpt-4o", // High quality for complex language
    "*:*": "lingo.dev", // Fallback
  }
}

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

الاختبار

اختبر أولاً باستخدام المحاكي الزائف

افعل:

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"

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

في بيئة التكامل المستمر (CI)، تحقق من وجود أخطاء في الترجمات:

- 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

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

الإطلاق التدريجي