دليل الوكيل: استخدام champollion

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

:::tip هل أنت على دراية مسبقة؟ إذا كنت تحتاج فقط إلى الأوامر، انتقل إلى مرجع CLI. وإذا كنت تريد بناء طريقة ترجمة وقياس أدائها، راجع دليل وكيل Arena. :::

---

إعداد البيئة

# No global install needed — npx runs it directly
npx champollion sync

المتطلبات:

• Node.js 18 أو أحدث
• مفتاح API لمزوّد الترجمة الخاص بك

إعداد مفتاح API — يحتاج champollion إلى مفتاح واحد على الأقل حسب الطرق التي تستخدمها:

# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."        # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..."    # for google-translate method

# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env

يقرأ Champollion .env تلقائيًا. احصل على مفتاح OpenRouter من openrouter.ai/keys.

---

أول مزامنة

يكتشف Champollion تلقائيًا ملفات اللغات لديك، وصيغتها (JSON أو TOML أو YAML أو PO)، واللغات المستهدفة:

npx champollion sync

ما الذي يحدث:

1. يحمّل champollion.config.json (أو يكتشف الإعدادات تلقائيًا)
2. يفحص ملف اللغة المصدر لديك ويسطّح المفاتيح المتداخلة
3. يقارن مع .champollion.lock (تجزئات SHA-256 للقيم المترجمة سابقًا)
4. يفحص .champollion/tm.json بحثًا عن ترجمات مخزّنة مؤقتًا (ذاكرة الترجمة)
5. يترجم فقط المفاتيح المتغيّرة أو المفقودة أو القديمة عبر الطريقة المُهيَّأة
6. يشغّل بوابة الجودة (5 فحوصات) على كل ترجمة
7. يكتب الترجمات الناجحة في ملف اللغة المستهدف
8. يحدّث ملف القفل وذاكرة الترجمة المؤقتة

في إعادة تشغيل نموذجية بعد تغيير مفتاح واحد، تخدم الخطوة 4 ما عدده 142 مفتاحًا من الذاكرة المؤقتة وتترجم الخطوة 5 مفتاحًا واحدًا. لهذا السبب تكون المزامنات اللاحقة سريعة ومنخفضة التكلفة.

---

الإعدادات

أنشئ champollion.config.json في جذر مشروعك:

{
  "inputLocale": "en",
  "pairs": {
    "en-fr": { "method": "llm-coached" },
    "en-ja": { "method": "google-translate" },
    "en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
  }
}

الحقول الرئيسية:

الحقل	الغرض	القيمة الافتراضية
inputLocale	اللغة المصدر	en
pairs	خريطة المصدر→الهدف مع إعدادات الطريقة	(مطلوب)
localesDir	موقع ملفات اللغات	(يُكتشَف تلقائيًا)
model	نموذج LLM لطريقتي llm/llm-coached	google/gemini-2.5-flash
batchSize	عدد المفاتيح لكل استدعاء API	80 (LLM)، 128 (Google)
jsonConcurrency	ترجمات اللغات المتوازية لمفاتيح JSON	200
contentConcurrency	استدعاءات API المتوازية لترجمة المحتوى	48

المرجع الكامل: الإعدادات

---

طرق الترجمة

الطريقة	متى تُستخدم	التكلفة	مفتاح API المطلوب
llm	للأغراض العامة، مناسبة للغات ذات الموارد الوفيرة	لكل رمز (حسب النموذج)	OPENROUTER_API_KEY
llm-coached	عندما تتوفر لديك قواعد نحوية/قاموس للغة المستهدفة	لكل رمز + سياق التوجيه	OPENROUTER_API_KEY
google-translate	اللغات ذات الموارد العالية التي تعمل GT معها جيدًا	20 دولارًا لكل مليون حرف	GOOGLE_TRANSLATE_API_KEY
api	خط معالجة مخصص مستضاف خلف نقطة نهاية HTTP	يحدّدها الخادم	لا شيء (نقطة النهاية تتولى المصادقة)
plugin	طريقة مُعدّة مسبقًا ومثبّتة محليًا	متفاوتة	متفاوت

التفاصيل: طرق الترجمة

---

بيانات التوجيه

لأزواج llm-coached، توجّه بيانات التوجيه نموذج LLM بمعرفة لغوية صريحة. أنشئ ملف توجيه:

coaching/fr.json

{
  "grammar_rules": [
    "Use formal register (vous) for all UI text",
    "Adjectives agree in gender and number with the noun"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms."
}

أشِر إليه في إعدادات الزوج الخاص بك:

"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }

تتحقق بوابة الجودة من أن مصطلحات القاموس تظهر فعلًا في المخرجات — وتُسجَّل الانتهاكات كتحذيرات [TERM].

التفاصيل: بيانات التوجيه

---

بوابة الجودة

تمر كل ترجمة عبر خمسة فحوصات آلية قبل كتابتها على القرص:

الفحص	ما الذي يلتقطه	مثال
فارغ/خالٍ	لم يُرجِع النموذج شيئًا	""
صدى المصدر	أرجع النموذج المُدخَل الإنجليزي دون تغيير	"Welcome" لليابانية
حلقة هلوسة	ثلاثيات متكررة	"Qo' Qo' Qo' Qo'"
تضخم الطول	المخرجات أطول من المصدر بأربعة أضعاف أو أكثر	مصدر من 10 أحرف → مخرجات من 50 حرفًا
مطابقة نظام الكتابة	نظام كتابة خاطئ للّغة	نص لاتيني للغة العربية

تُسجَّل حالات الفشل ببادئة [GATE]. لا توجد بدائل صامتة — إذا فشلت ترجمة، يتم الإبلاغ عنها، ولا تُقبَل بصمت.

التفاصيل: بوابة الجودة

---

ذاكرة الترجمة

يخزّن Champollion الترجمات مؤقتًا في .champollion/tm.json، مفهرسة حسب النص المصدر + اللغة + الطريقة. في المزامنات اللاحقة، تُخدَم المفاتيح غير المتغيّرة من الذاكرة المؤقتة — بلا استدعاء API ولا تكلفة.

[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]

لتجاوز الذاكرة المؤقتة لتشغيلة واحدة: npx champollion sync --no-tm

التفاصيل: ذاكرة الترجمة

---

الملفات المُنشأة

ينشئ Champollion عدة ملفات في مشروعك. تعرّف عليها كي لا تحذف أو تُدرِج في Git الملفات الخاطئة عن طريق الخطأ:

الملف	الغرض	Git؟
.champollion.lock	تجزئات SHA-256 لقيم المصدر المترجمة (اكتشاف التغييرات)	نعم — أدرِجه في Git
.champollion-content.lock	نفس الشيء، لكن لملفات محتوى Markdown/MDX	نعم — أدرِجه في Git
.champollion/tm.json	ذاكرة الترجمة المؤقتة	نعم — أدرِجه في Git (يوفّر تكاليف API للفريق)
.champollion/coaching/	مجلد بيانات التوجيه	نعم — هذه معرفتك اللغوية
champollion.config.json	إعدادات المشروع	نعم — أدرِجه في Git

---

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

ترجمة زوج لغوي واحد:

npx champollion sync --pair en-fr

ترجمة جميع الأزواج المُهيَّأة:

npx champollion sync

يترجم Champollion جميع اللغات بشكل متوازٍ. مع التخزين المؤقت في ذاكرة الترجمة، تصل المفاتيح المتغيّرة فقط إلى واجهة API.

وضع المحتوى (Markdown/MDX لـ Docusaurus وHugo وغيرهما):

npx champollion sync --content

يترجم الوثائق والمقالات وملفات المحتوى إلى جانب ملفات JSON للّغات. يستخدم التزامن المتوازي (افتراضيًا: 48 استدعاء API متزامنًا). اضبطه باستخدام --content-concurrency.

تشغيل تجريبي (معاينة دون كتابة):

npx champollion sync --dry-run

إجبار إعادة ترجمة مفاتيح محددة:

npx champollion sync --force-keys "hero.title,nav.about"

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

npx champollion sync --force-content

التحقق من حالة الترجمة:

npx champollion status

يعرض التغطية ومستويات الجودة ومعلومات الإضافات لكل زوج.

تدقيق القيم الاحتياطية غير المترجمة:

npx champollion audit

يسرد جميع القيم الاحتياطية [EN] التي تحتاج إلى ترجمة.

---

استكشاف الأخطاء وإصلاحها

المشكلة	الحل
OPENROUTER_API_KEY not set	صدّر المفتاح أو أضفه إلى .env في جذر مشروعك
No locale files found	عيّن localesDir في الإعدادات، أو تأكد من أن ملفات اللغات لديك تطابق التسمية القياسية (en.json، fr.json)
[GATE] Script compliance failed	حصلت لغتك المستهدفة على نص لاتيني بدلًا من نظام الكتابة المتوقع — جرّب نموذجًا مختلفًا أو أضِف بيانات توجيه
[GATE] Source echo	أرجع النموذج النص الإنجليزي دون تغيير — عادةً ما تحل بيانات التوجيه أو نموذج مختلف هذه المشكلة
جميع الترجمات مخزّنة مؤقتًا	شغّل مع --no-tm لتجاوز الذاكرة المؤقتة، أو --force-keys لمفاتيح محددة
تعارضات ملف القفل	يستخدم .champollion.lock تجزئات SHA-256 — يمكن حل تعارضات الدمج بأمان بالاحتفاظ بأي من النسختين، ثم إعادة تشغيل المزامنة

---

ما التالي

• البدء السريع — جولة كاملة للبدء
• مرجع CLI — كل أمر وكل خيار
• كيف يعمل — شرح خط معالجة المزامنة
• جسر منصة التقييم — كيف يتصل champollion بـ Arena
• هل تريد بناء طريقة ترجمة خاصة بك؟ راجع دليل وكيل Arena — ابنِ طريقة، وأثبت فعاليتها، واربح الجوائز.