الانتقال إلى المحتوى الرئيسي

درس تعليمي: إنشاء إضافة ترجمة

أنشئ طريقة ترجمة مخصصة من الصفر، وقم بقياس أدائها، ثم انشرها كإضافة لـ champollion. هذا هو سير العمل الكامل لإضافة زوج لغوي جديد لا تدعمه أي واجهة برمجة تطبيقات جاهزة.

ما الذي ستنشئه: إضافة ترجمة موجَّهة للفرنسية الرسمية مع فرض المصطلحات، وقواعد نحوية، ودرجات قياس أداء.

الوقت: 30–45 دقيقة

المتطلبات المسبقة:

  • champollion مثبَّت (npm install --save-dev champollion)
  • مفتاح API من OpenRouter (OPENROUTER_API_KEY)
  • Python 3.10+ (لمنصة التقييم)

الخطوة 1: تحديد المشكلة​

أنت تترجم لوحة تحكم SaaS إلى الفرنسية. الطريقة الافتراضية llm تنتج ترجمات صحيحة لكنها غير متسقة:

  • أحياناً تصبح "dashboard" هي "tableau de bord"، وأحياناً أخرى "panneau de contrôle"
  • تتناوب النبرة بين صيغتي tu وvous
  • تُكتب المصطلحات التقنية بصيغة إنجليزية بشكل غير متسق

أنت بحاجة إلى فرض المصطلحات والتحكم في مستوى الخطاب اللذين لا يوفرهما الموجّه العام لنموذج اللغة الكبير.

الخطوة 2: إنشاء بيانات التوجيه​

أنشئ ملف توجيه يُرمِّز متطلباتك اللغوية:

mkdir -p .champollion/coaching
.champollion/coaching/fr.json
{
  "grammar_rules": [
    "Always use the 'vous' form for formal register",
    "French adjectives agree in gender and number with their noun",
    "Use the present tense for UI instructions, not the imperative",
    "Preserve sentence-final punctuation style from the source"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres",
    "environment variable": "variable d'environnement",
    "webhook": "webhook",
    "API key": "clé API",
    "sign in": "se connecter",
    "sign out": "se déconnecter",
    "repository": "dépôt",
    "pull request": "demande de tirage"
  },
  "style_notes": "Formal technical French. Prefer native French terms over anglicisms where established equivalents exist. Keep UI labels concise — 3 words maximum where possible."
}

ما يفعله كل حقل:

  • grammar_rules — يُحقَن في موجّه النظام لنموذج اللغة الكبير كقيود صريحة
  • dictionary — يُطابَق مع مفاتيح المصدر؛ عندما يظهر مصطلح من القاموس، يُحقَن في الموجّه باعتباره "مصطلحات إلزامية"
  • style_notes — يُلحَق بموجّه النظام كإرشادات أسلوبية عامة

الخطوة 3: تهيئة الزوج اللغوي​

أخبر champollion باستخدام llm-coached للفرنسية:

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "pairs": {
    "en:fr": {
      "method": "llm-coached",
      "model": "google/gemini-3.5-flash",
      "temperature": 0.2
    }
  },
  "languages": {
    "fr": {
      "register": "Formal technical French (vous-form)",
      "name": "French"
    }
  }
}

الخطوة 4: الاختبار​

npx champollion sync --dry

راجع مخرجات التشغيل التجريبي (dry-run). تحقق من أن:

  • ✅ مصطلحات القاموس مستخدمة بشكل متسق ("tableau de bord" وليس "panneau de contrôle")
  • ✅ صيغة vous مستخدمة في كل النص
  • ✅ المصطلحات التقنية تطابق قاموسك

ثم نفِّذ المزامنة الفعلية:

npx champollion sync

الخطوة 5: قياس الأداء باستخدام منصة التقييم (اختياري)​

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

تثبيت المنصة​

pip install mt-eval-harness

إنشاء متن مرجعي​

أنشئ ملفاً يحتوي على نصوص المصدر وترجمات معروفة الجودة:

corpus/french-formal.json
[
  {
    "source": "Dashboard",
    "reference": "Tableau de bord"
  },
  {
    "source": "Sign in to your account",
    "reference": "Connectez-vous à votre compte"
  },
  {
    "source": "Your deployment is ready",
    "reference": "Votre déploiement est prêt"
  },
  {
    "source": "Environment variables",
    "reference": "Variables d'environnement"
  }
]

تشغيل قياس الأداء​

mt-eval test \
  --corpus corpus/french-formal.json \
  --source en \
  --target fr \
  --model google/gemini-3.5-flash \
  --temperature 0.2 \
  --champollion-config champollion.config.json

تُخرج المنصة:

  • chrF++ — درجة F على مستوى الأحرف (0–100). أعلى من 70 تُعدّ قوية.
  • BLEU — تداخل N-gram‏ (0–100). أعلى من 40 تُعدّ جيدة للترجمة الموجَّهة.
  • Exact match rate — نسبة الترجمات المطابقة للمرجع تماماً.
  • COMET — مقياس جودة عصبي (إذا كان مثبتاً عبر mt-eval setup --comet).

:::tip اختبر ما تشحنه استخدام --champollion-config يستورد نموذج الإنتاج ومستوى الخطاب ودرجة الحرارة وبيانات التوجيه مباشرة من ملف champollion.config.json الخاص بك. هذا يضمن أنك تقيس أداء الطريقة ذاتها التي ستنشرها. :::

تصدير الإضافة​

عندما تكون راضياً عن الدرجات:

mt-eval export \
  --name french-formal-v1 \
  --report eval/logs/harness/run_report.json \
  --output ./french-formal-v1/

هذا يُنشئ:

french-formal-v1/
├── method.json          # Manifest with config + benchmarks
└── coaching/
    └── fr.json          # Your coaching data

الخطوة 6: تثبيت الإضافة في Champollion​

npx champollion plugin install ./french-formal-v1/

هذا ينسخ الإضافة إلى .champollion/methods/french-formal-v1/.

حدِّث ملف الإعدادات لاستخدامها:

champollion.config.json
{
  "pairs": {
    "en:fr": {
      "methodPlugin": "french-formal-v1"
    }
  }
}

الخطوة 7: التحقق​

# Check plugin is installed and shows benchmark scores
npx champollion status

# Run a sync with the plugin
npx champollion sync

# Audit licensing status
npx champollion provenance

سيُظهر مُخرج status:

en → fr
  Method:    french-formal-v1 (llm-coached)
  Model:     google/gemini-3.5-flash
  Quality:   high
  chrF++:    74.2
  BLEU:      46.8
  Exact:     42%

ما الذي أنشأته​

أصبح لديك الآن:

  1. بيانات توجيه — قواعد نحوية ومصطلحات تفرض الاتساق
  2. درجات قياس أداء — جودة مُقاسة كمياً تُشحَن مع الإضافة
  3. إضافة قابلة للنقل — method.json + بيانات التوجيه، قابلة للتثبيت على أي جهاز
  4. نشر في بيئة الإنتاج — مدمجة في خط أنابيب المزامنة لديك

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