طرق الترجمة

يدعم Champollion عشر طرق للترجمة. يمكن لكل زوج لغوي استخدام طريقة مختلفة — فأنت لست مقيدًا بنهج واحد لمشروعك بأكمله.

مقارنة الطرق

مزودو نماذج اللغة الكبيرة (LLM)

تركّز على الجودة، وتدرك تنسيق Markdown، ومتوافقة مع بيانات التوجيه. الأفضل للمشاريع الغنية بالمحتوى.

الطريقة	المفتاح	ما تفعله
llm (الافتراضية)	OPENROUTER_API_KEY	نموذج لغة كبير عبر OpenRouter — أكثر من 200 نموذج مع توجيه تلقائي
llm-coached	OPENROUTER_API_KEY	نموذج لغة كبير + قواعد نحوية وقواميس وملاحظات أسلوبية
openai	OPENAI_API_KEY	واجهة OpenAI API المباشرة (gpt-4o، gpt-4o-mini)
anthropic	ANTHROPIC_API_KEY	واجهة Anthropic API المباشرة (Claude Sonnet، Haiku، Opus)
gemini	GEMINI_API_KEY	واجهة Google Gemini API المباشرة (Flash، Pro) — مستوى مجاني

الترجمة الآلية التقليدية

تركّز على السرعة والتكلفة. الأفضل لأزواج المفتاح-القيمة عالية الحجم.

الطريقة	المفتاح	ما تفعله
google-translate	GOOGLE_TRANSLATE_API_KEY	واجهة Google Cloud Translation API v2 (أكثر من 130 لغة)
deepl	DEEPL_API_KEY	واجهة DeepL API مع دعم المسارد (أكثر من 30 لغة)
microsoft-translator	MICROSOFT_TRANSLATOR_API_KEY	مترجم Azure Cognitive Services (أكثر من 100 لغة)
libretranslate	(استضافة ذاتية)	LibreTranslate باستضافة ذاتية (AGPL، مجاني)

البنية التحتية

الطريقة	المفتاح	ما تفعله
api	(حسب المزود)	عميل HTTP خفيف لأي نقطة نهاية ترجمة REST

شجرة القرار

---

llm — الترجمة بنماذج اللغة الكبيرة (الافتراضية)

تترجم عبر أي نموذج لغة كبير على OpenRouter. هذه هي الطريقة الافتراضية والأكثر تنوعًا.

كيف تعمل:

1. تجمّع المفاتيح في دفعات (افتراضيًا 80 مفتاحًا لكل دفعة) مع تعليمات السجل اللغوي والسياق
2. ترسلها إلى OpenRouter كموجّه منظَّم
3. تحلّل استجابة JSON
4. تتحقق من كل ترجمة عبر بوابة الجودة
5. تكتب الترجمات الناجحة، وتعيد المحاولة أو ترفض الترجمات الفاشلة

متى تُستخدم: في معظم المشاريع. خاصةً المواقع الغنية بالمحتوى التي تستخدم Markdown، حيث تحتاج كتل الشيفرة والرموز المختصرة (shortcodes) إلى الحماية.

الإعدادات:

{
  "defaultMethod": "llm",
  "model": "google/gemini-3.5-flash"
}

llm-coached — الترجمة الموجَّهة بنماذج اللغة الكبيرة

مثل llm، لكن مع حقن قواعد نحوية وقواميس مصطلحات وملاحظات أسلوبية في كل موجّه.

كيف تعمل:

1. تحمّل بيانات التوجيه من .champollion/coaching/<locale>.json أو من دليل coaching/ الخاص بإضافة
2. تحقن القواعد النحوية ومصطلحات القاموس والملاحظات الأسلوبية في موجّه النظام
3. تُدرَج مصطلحات القاموس المطابقة لمفاتيح المصدر كمصطلحات إلزامية
4. تتم الترجمة كما في llm، مع إضافة بيانات التوجيه مزيدًا من الدقة

متى تُستخدم: للغات محدودة الموارد، أو المصطلحات المتخصصة (القانونية والطبية)، أو السجلات الرسمية، أو أي حالة لا يكون فيها ناتج نموذج اللغة العام دقيقًا بما يكفي.

تنسيق بيانات التوجيه:

.champollion/coaching/fr.json

{
  "grammar_rules": [
    "French adjectives agree in gender and number with the noun they modify",
    "Use 'vous' for formal contexts, 'tu' for informal"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms where a native French term exists."
}

انظر أيضًا: دليل اللغات محدودة الموارد

---

openai — واجهة OpenAI API المباشرة

تترجم مباشرة عبر واجهة OpenAI Chat Completions API. بدون وسيط OpenRouter — مفتاحك، وحسابك، ولوحة استخدامك.

النماذج: gpt-4o (الافتراضي)، gpt-4o-mini

الميزات:

• ✅ إدراك تنسيق Markdown (ترجمة المحتوى)
• ✅ دعم التوجيه (قواعد نحوية، استبدالات قاموسية، ملاحظات أسلوبية)
• ✅ وضع JSON لإخراج منظّم بنمط المفتاح-القيمة
• ✅ تراجع أسي مع إعادة المحاولة

الإعدادات:

{
  "pairs": {
    "en:fr": { "method": "openai", "model": "gpt-4o-mini" }
  }
}

export OPENAI_API_KEY=sk-proj-...

احصل على مفتاحك من platform.openai.com/api-keys.

anthropic — واجهة Anthropic API المباشرة

تترجم مباشرة عبر واجهة Anthropic Messages API. تستخدم معامل system لبيانات التوجيه، مما يتيح التخزين المؤقت للموجّهات من Anthropic.

النماذج: claude-sonnet-4-6 (الافتراضي)، claude-haiku-4-5، claude-opus-4-7

الميزات:

• ✅ إدراك تنسيق Markdown (ترجمة المحتوى)
• ✅ دعم التوجيه (قواعد نحوية، استبدالات قاموسية، ملاحظات أسلوبية)
• ✅ تخزين مؤقت لموجّه النظام (يوزّع تكلفة بيانات التوجيه عبر الدفعات)
• ✅ تراجع أسي مع إعادة المحاولة

الإعدادات:

{
  "pairs": {
    "en:ja": { "method": "anthropic", "model": "claude-haiku-4-5" }
  }
}

export ANTHROPIC_API_KEY=sk-ant-...

احصل على مفتاحك من console.anthropic.com.

gemini — واجهة Google Gemini API المباشرة

تترجم مباشرة عبر واجهة Google Gemini generateContent API. يتوفر مستوى مجاني — أفضل نقطة بداية بتكلفة صفرية.

النماذج: gemini-2.5-flash (الافتراضي)، gemini-2.5-pro

الميزات:

• ✅ إدراك تنسيق Markdown (ترجمة المحتوى)
• ✅ دعم التوجيه (قواعد نحوية، استبدالات قاموسية، ملاحظات أسلوبية)
• ✅ وضع استجابة JSON عبر responseMimeType
• ✅ مستوى مجاني (حصة يومية سخية)
• ✅ تراجع أسي مع إعادة المحاولة

الإعدادات:

{
  "pairs": {
    "en:ko": { "method": "gemini", "model": "gemini-2.5-pro" }
  }
}

export GEMINI_API_KEY=AI...

احصل على مفتاحك من aistudio.google.com/apikey.

التحقق من صحة النموذج

يتحقق مزودو نماذج اللغة المباشرون (openai، anthropic، gemini) من صحة سلسلة النموذج لديك عند أول استخدام. وهذا يكشف ثلاث فئات من الأخطاء:

تنسيق طريقة خاطئ — استخدام مسار نموذج بأسلوب OpenRouter مع مزود مباشر:

[WARN] OpenAI: model "google/gemini-3.5-flash" looks like an OpenRouter path.
       Direct providers use bare model names (e.g., "gpt-4o").
       To use OpenRouter models, set method to 'llm' instead.

مزود خاطئ — استخدام نموذج من مزود مختلف تمامًا:

[WARN] Gemini: model "claude-sonnet-4-6" is an Anthropic model.
       This provider (gemini) cannot serve Anthropic models.
       Use --method anthropic or set "method": "anthropic" in config.

نموذج متوقف أو مكتوب بشكل خاطئ — عند أول استدعاء للواجهة البرمجية، يجلب champollion قائمة النماذج الحية للمزود ويفحص نموذجك مقارنةً بها:

[WARN] Gemini: model "gemini-1.5-flash" not found in available models.
       Similar models: gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-pro
       The API call will proceed — the provider will give the final verdict.

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

---

google-translate — واجهة Google Cloud Translation API

تكامل مباشر مع Google Cloud Translation API v2. تستخدم واجهة REST — بدون SDK، وبدون حساب خدمة. مفتاح الواجهة البرمجية فقط.

متى تُستخدم: أزواج سلاسل المفتاح-القيمة عالية الحجم حيث تكون السرعة والتكلفة أهم من الدقة في التعبير. تدعم أكثر من 130 لغة بشكل افتراضي.

القيود:

• ⚠️ لا إدراك لتنسيق Markdown. ستفسد كتل الشيفرة والرموز المختصرة ومتغيرات الإدراج.
• لا تحكم في السجل اللغوي أو النبرة
• لا دعم للتوجيه أو فرض المصطلحات

npx champollion sync --method google-translate

:::tip الاكتشاف التلقائي إذا تم تعيين GOOGLE_TRANSLATE_API_KEY فقط (بدون مفتاح OpenRouter)، يتحول champollion تلقائيًا إلى Google Translate. لا حاجة لتغيير الإعدادات. :::

deepl — واجهة DeepL API

تكامل مباشر مع واجهة ترجمة DeepL. تدعم المسارد لضمان اتساق المصطلحات.

متى تُستخدم: اللغات الأوروبية التي يتفوق فيها DeepL (الألمانية والفرنسية والإسبانية والهولندية والبولندية، إلخ). يضمن دعم المسارد اتساق المصطلحات دون الحاجة لبيانات التوجيه.

الميزات:

• ✅ اكتشاف تلقائي لنقطة النهاية المجانية/الاحترافية (لاحقة :fx في المفاتيح المجانية)
• ✅ إنشاء المسارد وإدارتها
• ✅ التحكم في مستوى الرسمية
• ⚠️ لا إدراك لتنسيق Markdown — أزواج المفتاح-القيمة فقط

الإعدادات:

{
  "pairs": {
    "en:de": { "method": "deepl" }
  }
}

export DEEPL_API_KEY=your-key-here

احصل على مفتاحك من deepl.com/pro-api.

microsoft-translator — خدمات Azure Cognitive Services

تكامل مباشر مع Microsoft Translator Text API v3.

متى تُستخدم: بيئات المؤسسات ذات البنية التحتية القائمة على Azure. تدعم أكثر من 100 لغة بما في ذلك العديد من اللغات التي لا يغطيها Google Translate.

الميزات:

• ✅ حتى 100 جزء لكل طلب (إنتاجية عالية)
• ✅ معامل اختياري للمنطقة لتحسين زمن الاستجابة
• ⚠️ لا إدراك لتنسيق Markdown — أزواج المفتاح-القيمة فقط
• ⚠️ لا ترجمة للمحتوى — أزواج المفتاح-القيمة فقط

الإعدادات:

{
  "pairs": {
    "en:ar": { "method": "microsoft-translator" }
  }
}

export MICROSOFT_TRANSLATOR_API_KEY=your-key
export MICROSOFT_TRANSLATOR_REGION=global  # optional

احصل على مفتاحك من Azure Portal ← Cognitive Services ← Translator.

libretranslate — الترجمة باستضافة ذاتية

ترجمة مفتوحة المصدر باستضافة ذاتية باستخدام LibreTranslate. تعمل محليًا أو على بنيتك التحتية الخاصة — بدون تكاليف واجهات برمجية، مع سيادة كاملة على البيانات.

متى تُستخدم: المشاريع التي تتطلب ترجمة دون اتصال بالإنترنت، أو الامتثال لخصوصية البيانات (GDPR)، أو التشغيل بتكلفة صفرية. مفيدة بشكل خاص لخطوط CI التي لا ينبغي أن تعتمد على واجهات برمجية خارجية.

الميزات:

• ✅ استضافة ذاتية — بدون استدعاءات لواجهات برمجية خارجية
• ✅ مجانية ومفتوحة المصدر (AGPL-3.0)
• ✅ يتوفر النشر عبر Docker
• ⚠️ لا إدراك لتنسيق Markdown — أزواج المفتاح-القيمة فقط
• ⚠️ لا ترجمة للمحتوى — أزواج المفتاح-القيمة فقط
• ⚠️ تتفاوت الجودة حسب الزوج اللغوي

الإعداد:

# Run LibreTranslate locally with Docker
docker run -d -p 5000:5000 libretranslate/libretranslate

# Configure (optional — defaults to localhost:5000)
export LIBRETRANSLATE_API_URL=http://localhost:5000/translate

{
  "pairs": {
    "en:es": { "method": "libretranslate" }
  }
}

---

api — واجهة الترجمة عن بُعد

عميل HTTP خفيف لنقاط نهاية الترجمة المستضافة مجتمعيًا أو المحمية بحقوق الملكية الفكرية. يرسل Champollion المفاتيح ويستقبل الترجمات — وهو لا يحتوي على أي منطق ترجمة.

متى تُستخدم: عندما تكون طرق الترجمة مستضافة على الخادم (مثل بيانات التوجيه الملكية، أو النماذج المضبوطة بدقة، أو خطوط FST التي لا يمكن توزيعها).

{
  "pairs": {
    "en:crk": {
      "method": "api",
      "endpoint": "https://api.example.com/v1/translate",
      "apiKey": "your-key"
    }
  }
}

:::note الترجمة المجتمعية المتوافقة مع مبادئ OCAP طريقة api هي الجسر إلى الترجمة المستضافة مجتمعيًا المتوافقة مع مبادئ OCAP. يمكن لمجتمعات الشعوب الأصلية ومجتمعات لغات الأقليات استضافة نقاط نهاية الترجمة الخاصة بها — مع إبقاء بيانات التوجيه والنماذج المضبوطة بدقة والملكية الفكرية اللغوية تحت سيطرة المجتمع — بينما يتصل بها Champollion كعميل خفيف.

انظر دعم لغة محدودة الموارد للاطلاع على الشرح الكامل للاستضافة المجتمعية، وتقديم طريقة عبر واجهة برمجية لمتطلبات نقاط النهاية. :::

---

إعدادات لكل زوج لغوي

تكمن القوة الحقيقية في المزج بين الطرق لكل زوج لغوي:

champollion.config.json

{
  "version": 3,
  "pairs": {
    "en:fr": { "method": "deepl" },
    "en:ja": { "method": "openai", "model": "gpt-4o" },
    "en:ko": { "method": "gemini" },
    "en:ar": { "method": "microsoft-translator" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

يترجم هذا الفرنسية عبر DeepL (دعم المسارد)، واليابانية عبر OpenAI (الجودة)، والكورية عبر Gemini (المستوى المجاني)، والعربية عبر Microsoft Translator (التغطية)، ولغة كري السهول (Plains Cree) عبر إضافة موجَّهة (متخصصة).

الإضافات

الإضافات هي وصفات ترجمة معدّة مسبقًا لأزواج لغوية محددة. وهي ملفات JSON تعريفية — وليست شيفرة — تخبر champollion بالطريقة التي يجب استخدامها، وبأي إعدادات، وما الجودة التي تم قياسها معياريًا.

:::tip من منصة التقييم إلى الإنتاج بأمر واحد يمكن تثبيت الإضافات المطوَّرة والمثبَتة في منصة التقييم مباشرة — فالطريقة التي تتحقق منها هناك تُنشر هنا بأمر plugin install واحد. انظر تقييم الترجمة الآلية لسير عمل التقييم الكامل. :::

champollion plugin install ./french-formal-v1/
champollion plugin list
champollion plugin remove french-formal-v1

انظر مواصفات الإضافات للاطلاع على التنسيق الكامل لملف التعريف.

---

التبديل بين المزودين

تنتقل بين الطرق؟ يتغير تنسيق النموذج ومتغير البيئة — إليك الخريطة:

OpenRouter ← مزود مباشر

champollion.config.json

 {
   "pairs": {
     "en:fr": {
-      "method": "llm",
-      "model": "openai/gpt-4o"
+      "method": "openai",
+      "model": "gpt-4o"
     }
   }
 }

Environment variables

- export OPENROUTER_API_KEY=sk-or-v1-...
+ export OPENAI_API_KEY=sk-proj-...

الاختلافات الرئيسية:

• يستخدم OpenRouter تنسيق provider/model (مثل openai/gpt-4o). يستخدم المزودون المباشرون أسماء النماذج المجردة (مثل gpt-4o).
• لكل مزود مباشر متغير البيئة الخاص به (OPENAI_API_KEY، ANTHROPIC_API_KEY، GEMINI_API_KEY).
• إذا استخدمت تنسيق نموذج خاطئًا، فسيحذرك champollion — انظر التحقق من صحة النموذج.

مزود مباشر ← OpenRouter

champollion.config.json

 {
   "pairs": {
     "en:ja": {
-      "method": "anthropic",
-      "model": "claude-sonnet-4-6"
+      "method": "llm",
+      "model": "anthropic/claude-sonnet-4-6"
     }
   }
 }

:::tip متى تستخدم OpenRouter مقابل المزود المباشر استخدم OpenRouter عندما تريد التبديل بين النماذج دون تغيير متغيرات البيئة، أو عندما تريد الوصول إلى أكثر من 200 نموذج بمفتاح واحد. استخدم المزودين المباشرين عندما تريد فوترة أبسط، أو زمن استجابة أقل (بدون وسيط)، أو الوصول إلى ميزات خاصة بالمزود مثل التخزين المؤقت للموجّهات من Anthropic. :::

---

مقارنة التكاليف

التكلفة التقريبية لكل 1,000 مفتاح مترجم (بافتراض نحو 10 رموز لكل مفتاح، و80 مفتاحًا لكل دفعة):

الطريقة	التكلفة / 1000 مفتاح	السرعة	الجودة	الأفضل لـ
gemini (Flash)	مجانية (ضمن المستوى المجاني)	سريعة	جيدة	البدء، المشاريع الشخصية
google-translate	~$0.02	الأسرع	مقبولة	الحجم العالي، اللغات الأوروبية
deepl	~$0.02	سريعة	جيدة	اللغات الأوروبية، المصطلحات
microsoft-translator	~$0.01	سريعة	مقبولة	بيئات Azure، تغطية لغوية واسعة
libretranslate	مجانية (استضافة ذاتية)	متفاوتة	متوسطة	البيئات المعزولة، GDPR، خطوط CI
gemini (Pro)	~$0.07	متوسطة	جيدة جدًا	الحالات الحساسة للجودة، حصة مجانية
openai (GPT-4o-mini)	~$0.01	سريعة	جيدة	نماذج لغة بميزانية محدودة
openai (GPT-4o)	~$0.10	متوسطة	جيدة جدًا	الحالات الحساسة للجودة
anthropic (Haiku)	~$0.01	سريعة	جيدة	نماذج لغة بميزانية محدودة
anthropic (Sonnet)	~$0.10	متوسطة	جيدة جدًا	الحالات الحساسة للجودة
anthropic (Opus)	~$0.50	بطيئة	ممتازة	أقصى جودة
llm (OpenRouter)	تتفاوت حسب النموذج	متفاوتة	متفاوتة	مقارنة النماذج، التجريب

:::note هذه تقديرات تعتمد التكاليف الفعلية على طول النص المصدر وحجم الدفعة وتغيرات أسعار المزود. راجع صفحة الأسعار الحالية لكل مزود للحصول على الأسعار الدقيقة. :::

---

انظر أيضًا

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