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

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

المشكلات الشائعة وحلولها في champollion.

واجهة برمجة التطبيقات والمصادقة​

"OPENROUTER_API_KEY not found"​

يتطلب Champollion مفتاح API للترجمة عبر نماذج LLM. قم بتعيينه كمتغير بيئة:

export OPENROUTER_API_KEY="sk-or-v1-..."

أو في ملف .env (إذا كان مشروعك يحمّل ملفات .env):

OPENROUTER_API_KEY=sk-or-v1-...
نصيحة

إذا كان لديك مفتاح API لـ Google Translate فقط، فإن champollion يكتشف ذلك تلقائيًا ويستخدم Google Translate كطريقة افتراضية. لا حاجة لأي تغيير في الإعدادات.

"401 Unauthorized" من OpenRouter​

مفتاح API الخاص بك غير صالح أو منتهي الصلاحية. تحقق منه على openrouter.ai/keys.

"429 Too Many Requests" / تحديد معدل الطلبات​

يتعامل Champollion مع حدود معدل الطلبات داخليًا باستخدام التراجع الأسي (exponential backoff). إذا كنت تصل باستمرار إلى حدود معدل الطلبات:

  1. قلّل حجم الدفعة في ملف الإعدادات الخاص بك: 
    { "batchSize": 15 }
  2. استخدم نموذجًا بحدود معدل أعلى (مثلًا، google/gemini-3.5-flash لديه حدود سخية)
  3. استخدم طريقة أرخص/أسرع لأزواج اللغات ذات الحجم الكبير — لا توجد حدود معدل لدى Google Translate: 
    { "pairs": { "en:it": { "method": "google-translate" } } }

النموذج غير موجود / أخطاء 404​

يتحقق مزوّدو LLM المباشرون (openai، anthropic، gemini) من صحة سلسلة النموذج الخاصة بك عند أول استخدام. إذا رأيت تحذيرًا:

"looks like an OpenRouter path" — أنت تستخدم نموذجًا بصيغة OpenRouter (google/gemini-3.5-flash) مع مزوّد مباشر. يستخدم المزوّدون المباشرون أسماء نماذج مجردة:

- { "method": "gemini", "model": "google/gemini-3.5-flash" }
+ { "method": "gemini", "model": "gemini-2.5-flash" }

أو بدّل إلى طريقة llm لاستخدام OpenRouter:

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

"is an Anthropic/OpenAI/Gemini model" — أنت ترسل نموذجًا إلى المزوّد الخطأ:

- { "method": "gemini", "model": "claude-sonnet-4-6" }
+ { "method": "anthropic", "model": "claude-sonnet-4-6" }

"not found in available models" — قد يكون النموذج متوقفًا عن الدعم أو مكتوبًا بشكل خاطئ. يجلب Champollion قائمة النماذج الحالية من المزوّد ويقترح بدائل. راجع وثائق المزوّد للاطلاع على أسماء النماذج الحالية.

:::tip إيقاف النماذج أمر وارد يقوم المزوّدون بإيقاف أسماء النماذج بانتظام. إذا فشلت الترجمات فجأة بعد تحديث من المزوّد، تحقق من مخرجات [WARN] — فستعرض لك البدائل الحالية. :::

جودة الترجمة​

الترجمات تكرر نص اللغة المصدر​

تكتشف بوابة الجودة هذه الحالة. إذا كانت الترجمة مطابقة للنص الإنجليزي المصدر، فسيتم رفضها وإعادة المحاولة. إذا استمرت المشكلة:

  1. تحقق من النموذج — بعض النماذج تؤدي بشكل ضعيف مع أزواج لغات معينة
  2. أضف تعليمات السجل اللغوي — أخبر النموذج بنوع اللغة المطلوب إنتاجها: 
    {
      "languages": {
        "ja": { "name": "Japanese", "register": "Polite/formal Japanese" }
      }
    }
  3. جرّب نموذجًا مختلفًا — بدّل من gpt-4o-mini إلى gpt-4o أو google/gemini-2.5-pro

مخرجات بنظام كتابة خاطئ (مثلًا، نص لاتيني لليابانية)​

يكتشف فحص توافق نظام الكتابة في بوابة الجودة معظم الحالات. إذا استمرت المشكلة:

  • تحقق من صحة رمز اللغة (ja وليس jp)
  • أضف تعليمات صريحة لنظام الكتابة في حقل register: 
    { "register": "Japanese using hiragana, katakana, and kanji" }

أنماط الهلوسة في المخرجات​

أنماط الثلاثيات المتكررة (مثلًا، "hello hello hello") يتم اكتشافها بواسطة كاشف حلقات الهلوسة. إذا كانت المخرجات مشوهة لكنها تجتاز الكاشف:

  1. قلّل حجم الدفعة — الدفعات الأصغر تنتج مخرجات أكثر تركيزًا
  2. استخدم نموذجًا أقوى — النماذج الأكبر تهلوس بشكل أقل مع أنظمة الكتابة غير اللاتينية
  3. أضف بيانات تدريبية — مصطلحات القاموس ترسّخ الترجمة

مشكلات الملفات والتنسيقات​

"No locale files found"​

يكتشف Champollion ملفات اللغات تلقائيًا. إذا لم يتمكن من العثور عليها:

  1. تحقق من localesDir — يجب أن يشير إلى المجلد الذي يحتوي على ملفات اللغات: 
    { "localesDir": "./locales" }
  2. تحقق من تسمية الملفات — يجب أن تُسمّى الملفات برمز اللغة: en.json، fr.json، وغيرها.
  3. تحقق من التنسيق — التنسيقات المدعومة: JSON و JSON المتداخل و YAML و TOML

تعارضات ملف القفل​

إذا دخل .champollion.lock في حالة سيئة:

# Reset the lock file (next sync will retranslate everything)
rm .champollion.lock
npx champollion sync
تحذير

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

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

إذا كانت ترجمات فردية خاطئة وأردت فرض إعادة ترجمتها دون حذف ملف القفل:

# Re-translate a single key
npx champollion sync --force-keys "hero.title"

# Re-translate multiple keys
npx champollion sync --force-keys "nav.home,nav.about,footer.copyright"

علامة --force-keys تتجاوز فحص تجزئة ملف القفل لتلك المفاتيح المحددة، مما يفرض إعادة الترجمة دون التأثير على أي مفاتيح أخرى.

ترجمة المحتوى تُفسد كتل التعليمات البرمجية​

لا ينبغي أن يحدث هذا — تُحمى كتل التعليمات البرمجية قبل الترجمة. إذا حدث ذلك:

  1. تحقق من أن كتلة التعليمات البرمجية تستخدم السياج القياسي (ثلاث علامات اقتباس مائلة)
  2. تحقق من وجود كتل تعليمات برمجية غير مغلقة في ملف Markdown المصدر
  3. أبلغ عن المشكلة — هذا خلل في نظام الحماية بالحارس (sentinel shielding)

مشكلات سطر الأوامر​

--watch لا يكتشف التغييرات​

تستخدم مراقبة الملفات fs.watch الأصلية في Node.js. المشكلات المعروفة:

  • محركات الأقراص الشبكية — لا يعمل fs.watch بشكل موثوق على نقاط تركيب NFS/SMB
  • أحجام Docker — استخدم وضع الاستطلاع (polling) أو شغّل champollion داخل الحاوية
  • المجلدات الكبيرة — يراقب الراصد localesDir بشكل تكراري؛ قد تتجاوز الأشجار العميقة جدًا حدود نظام التشغيل

npx يشغّل إصدارًا قديمًا​

# Clear the npx cache
npx --yes champollion@latest sync

أو ثبّته عالميًا:

npm install -g champollion
champollion sync

الأداء​

المزامنة بطيئة مع عدد كبير من اللغات​

يترجم Champollion جميع اللغات بالتوازي افتراضيًا. إذا كانت المزامنة لا تزال بطيئة:

  1. استخدم Google Translate لأزواج اللغات ذات الحجم الكبير — فهو أسرع من ترجمة LLM بمقدار 10–50 ضعفًا
  2. زِد حجم الدفعة (القيمة الافتراضية 80): 
    { "batchSize": 120 }
  3. اضبط التزامن — القيمة الافتراضية لتوازي ملفات JSON هي 200 وللمحتوى 48. إذا كان مزوّد API الخاص بك يدعم حدود معدل أعلى: 
    npx champollion sync --json-concurrency 80 --content-concurrency 20
  4. استخدم نموذجًا سريعًا — gpt-4o-mini أسرع بشكل ملحوظ من gpt-4o

تكاليف API مرتفعة​

  • تحقق من أحجام الدفعات — دفعات أكبر = استدعاءات API أقل = تكلفة أقل
  • استخدم ذاكرة الترجمة — ذاكرة الترجمة (TM) مفعّلة افتراضيًا. شغّل champollion tm stats للتحقق من عملها. إذا رأيت 0 إدخالات بعد عدة مزامنات، فقد تكون هناك مشكلة في أذونات مجلد .champollion/
  • استخدم التخزين المؤقت للموجّهات (prompt caching) — يقسم Champollion رسائل النظام والمستخدم لتحقيق إصابات في ذاكرة التخزين المؤقت مع نماذج Anthropic و Google
  • استخدم Google Translate للغات الفئة الثانية — راجع دليل ترجمة 30 لغة

ترجمات قديمة بعد تبديل المزوّدين​

إذا بدّلت من طريقة ترجمة إلى أخرى (مثلًا، من llm إلى deepl)، فقد تستمر ذاكرة التخزين المؤقت لذاكرة الترجمة في تقديم ترجمات قديمة من الطريقة السابقة للمفاتيح التي لم يتغير نصها المصدر. يتضمن مفتاح التخزين المؤقت اسم الطريقة، لذا تُعالج معظم الحالات تلقائيًا. لكن إذا غيّرت model ضمن الطريقة نفسها:

# Force fresh translations for all keys
champollion sync --no-tm

# Or clear the cache entirely and re-sync
champollion tm clear --yes
champollion sync

راجع ذاكرة الترجمة للاطلاع على تفاصيل تصميم مفتاح التخزين المؤقت.

ما زلت عالقًا؟​