تخطي إلى المحتوى الرئيسي

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

المشكلات الشائعة والحلول الخاصة بـ i18n-rosetta.

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

"OPENROUTER_API_KEY not found"​

يتطلب Rosetta مفتاح واجهة برمجة تطبيقات (API) للترجمة باستخدام النماذج اللغوية الكبيرة (LLM). قم بتعيينه كمتغير بيئة:

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

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

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

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

"401 Unauthorized" من OpenRouter​

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

"429 Too Many Requests" / تقييد معدل الطلبات (Rate Limiting)​

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

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

لم يتم العثور على النموذج (Model Not Found) / أخطاء 404​

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

"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" — قد يكون النموذج مهملًا (deprecated) أو مكتوبًا بشكل خاطئ. يقوم Rosetta بجلب قائمة النماذج الحية للمزود ويقترح بدائل. راجع وثائق المزود لمعرفة أسماء النماذج الحالية.

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

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

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

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

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

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

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

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

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

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

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

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

"No locale files found" (لم يتم العثور على ملفات اللغة)​

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

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

تعارضات ملف القفل (Lock file)​

إذا أصبح .i18n-rosetta.lock في حالة سيئة:

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

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

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

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

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

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

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

ترجمة المحتوى تفسد كتل التعليمات البرمجية (Code blocks)​

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

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

مشكلات واجهة سطر الأوامر (CLI)​

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

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

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

npx يقوم بتشغيل إصدار قديم​

# Clear the npx cache
npx --yes i18n-rosetta@latest sync

أو قم بتثبيته بشكل عام (globally):

npm install -g i18n-rosetta
i18n-rosetta sync

الأداء​

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

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

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

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

  • التحقق من أحجام الدفعات — دفعات أكبر = مكالمات API أقل = تكلفة أقل
  • استخدام ذاكرة الترجمة (Translation Memory) — يتم تشغيلها افتراضيًا. قم بتشغيل i18n-rosetta tm stats للتحقق من عملها. إذا رأيت 0 إدخالات بعد مزامنات متعددة، فقد يكون هناك خطأ ما في أذونات دليل .rosetta/ الخاص بك
  • استخدام التخزين المؤقت للمطالبات (prompt caching) — يقوم Rosetta بتقسيم رسائل النظام/المستخدم لتحقيق إصابات التخزين المؤقت (cache hits) على نماذج Anthropic وGoogle
  • استخدام Google Translate للغات المستوى الثاني (Tier 2) — راجع دليل ترجمة 30 لغة

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

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

# Force fresh translations for all keys
i18n-rosetta sync --no-tm

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

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

هل ما زلت تواجه مشكلة؟​