انتقل إلى المحتوى

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

أخطاء شائعة، ما تعنيه، وكيفية إصلاحها.

أخطاء الإعداد

"LLM is not configured"

لم تضف مفتاح API بعد. افتح تطبيق سطح المكتب → Settings → LLM → الصق مفتاحًا. راجع مزودو LLM للدليل الكامل.

AUTH_ERROR

مفتاح LLM API خاطئ أو منتهي الصلاحية.

  • Gemini — أنشئ مفتاحًا جديدًا في https://aistudio.google.com/apikey، الصقه مرة أخرى في Settings → LLM.
  • مزود مخصص — تحقق من صحة المفتاح (curl نقطة النهاية يدويًا بنفس رأس Authorization: Bearer …). إذا انتقلت نقطة النهاية، حدّث حقل API endpoint أيضًا.

QUOTA_ERROR

لقد وصلت إلى حد المستوى المجاني أو الخطة المدفوعة.

  • مستوى Gemini المجاني — تختلف حصة الطلبات اليومية لكل نموذج (راجع https://ai.google.dev/gemini-api/docs/rate-limits). انتظر يومًا، أو ارقَ إلى مدفوع.
  • OpenAI / آخرون — تحقق من لوحة معلومات الفوترة الخاصة بك. تحتوي العديد من الأدوات على "حدود إنفاق" تُوقف الطلبات عند الوصول إليها.

MODEL_NOT_FOUND

اسم النموذج الذي اخترته غير متاح.

  • المزودون المخصصون — تأكد من أن النموذج في قائمة Models المفصولة بفواصل في Settings → LLM.
  • قائمة Gemini المضمنة — انتقل إلى نموذج موثق في Settings → LLM → Default Gemini model.

VISION_NOT_SUPPORTED

اخترت نموذجًا غير مرئي وحاولت ترجمة صورة / PDF ممسوح. انتقل إلى نموذج يحتوي اسمه على flash أو pro أو vision (مثل gpt-4o لـ OpenAI، أي متغير حالي من Gemini Flash أو Pro لـ Gemini).

أخطاء الصوت / الفيديو

FFMPEG_NOT_FOUND

FFmpeg ليس على PATH. راجع إعداد FFmpeg لأمر التثبيت لنظام التشغيل الخاص بك.

يعيد خادم MCP لف هذا كـ: "FFmpeg is required to decode this audio/video file but is not installed or not on PATH."

صفحة Live لا تعرض ترجمات

  • مصدر صوت خاطئ — افتح Settings → Live → Audio source وتأكد من أنه يطابق ما تريده فعلاً (Microphone / System / Both).
  • الميكروفون مكتوم — تحقق من إعدادات صوت OS؛ يستخدم التطبيق جهاز الإدخال الافتراضي.
  • صوت النظام غير معد — راجع التقاط صوت النظام لخطوات loopback في macOS / Windows.

مخرجات الصوت صامتة / فارغة

  • ElevenLabs بدون مفتاح — تظهر صفحة الصوت حوار pre-flight ودود؛ إذا تسلل، فقد يكون الملف بايتات فارغة. تحقق من Settings → Service → ElevenLabs API key.
  • خطأ شبكة Edge TTS — يحتاج Edge TTS إلى الإنترنت؛ إذا كان جدار الحماية يحظر speech.platform.bing.com، انتقل إلى ElevenLabs أو Google Cloud TTS أو Piper TTS (دون اتصال بالكامل).

حوار "Piper voice not installed"

تتحقق صفحات الصوت / الدبلجة / ترجمة النص قبل التشغيل من أن صوت Piper للغة الهدف موجود على القرص قبل بدء أي عامل. إذا لم يكن كذلك، فسترى نافذة modal مع زر Open Settings.

لتنزيل الصوت:

  1. انقر Open Settings في الحوار (أو افتح Settings → Voice يدويًا).
  2. تأكد من أن TTS method مضبوط على Piper TTS.
  3. انقر Download voices now لفتح حوار مكتبة الأصوات.
  4. ابحث عن صف لغة الهدف، ثم انقر Female voice أو Male voice بجانبه. الأصوات هي ملفات ONNX بحجم ~25–60 MB يتم تنزيلها من HuggingFace؛ مرة واحدة لكل لغة.
  5. أغلق الحوار وأعد تشغيل مهمة الترجمة / الصوت / الدبلجة.

إذا لم تكن لغتك المستهدفة في القائمة، فلا توجد تغطية Piper — يعود المحرك بصمت إلى Edge TTS وقت التركيب، لذا لا تحتاج فعلاً إلى تنزيل أي شيء. اللغات الـ 13 بدون أصوات Piper اليوم: البيلاروسية، البنغالية، الصينية (التقليدية)، الكرواتية، الإستونية، العبرية، اليابانية، الخمير، الكورية، الليتوانية، الماليزية، المنغولية، التايلاندية.

صفحة الترجمة الفورية هي المكان الوحيد الذي لن يعرض هذا الحوار — مقاطعة دفق مباشر بنافذة modal سيكون أسوأ من الرجوع، لذا حالات الصوت المفقود هناك تُوجَّه بصمت إلى Edge TTS.

أخطاء ترجمة المستندات

تفشل ترجمة PDF في صفحة معينة

تستخدم ملفات PDF نقاط فحص لكل صفحة — الصفحات الناجحة لا تتم إعادتها. تسجل الصفحة الفاشلة stack في app.log؛ المسببات الشائعة:

  • الصفحة عبارة عن ممسح بدون طبقة نص وOCR غير مكون. إعداد Settings → OCR (راجع محركات OCR).
  • تحتوي الصفحة على تخطيط رياضي معقد أتلفه LLM. جرّب نموذجًا أقوى (متغير Pro بدلاً من Flash).

تكسر ترجمة Office التنسيق

  • التنسيقات الحديثة (.docx, .xlsx, .pptx) — يتم الحفاظ على التنسيق لكل تشغيل عبر HTML round-trip. إذا رأيت علامات <b> ضائعة في المخرجات، فإن LLM لم يغلقها — أعد التشغيل بنموذج أقوى.
  • التنسيقات القديمة (.doc, .xls, .ppt) — قم بتشغيل Settings → Translation → Auto-convert legacy للحصول على دقة أفضل بكثير. يحول خط الأنابيب أولاً إلى .docx، يترجم، يحول مرة أخرى.

تتوقف قائمة انتظار الترجمة في منتصف الدُفعة

اخرج من التطبيق وتحقق من قاعدة البيانات:

sqlite3 ~/.local/share/ai-translate/translator.db \
  "SELECT id, status, error_code, file_name FROM history WHERE status NOT IN ('Done', 'Failed') ORDER BY created_at DESC LIMIT 10;"

تعني صفوف Translating التي لم يتم لمسها لدقائق أن العامل تعطل بصمت. أعد تشغيل تطبيق سطح المكتب — يستأنف تلقائيًا مهام Pending / Translating عند بدء التشغيل.

مشكلات شاملة

تتُرجم ملفات متعددة في وقت واحد بصمت كملف واحد

أفلِت ملفًا واحدًا في كل مرة، أو تحقق من عمود Files في رأس قائمة الانتظار — يجب أن يعرض العدد الذي أفلَتَّه. يعرض حد 100 ملف إشعارًا عند تجاوزه.

يعرض الشريط الجانبي دوّامة إلى الأبد

يشير إلى أن العامل لا يزال محددًا على أنه قيد التشغيل. اخرج من التطبيق بشكل نظيف (لا SIGKILL) — تعيد خطافات التنظيف autouse ضبط الأعلام. إذا ترك SIGKILL الحالة عالقة، فقم بمسح عمال DB يدويًا:

sqlite3 ~/.local/share/ai-translate/translator.db \
  "UPDATE history SET status='Failed', error_code=99 WHERE status IN ('Pending', 'Translating');"

أين السجلات؟

OS Path
Linux ~/.local/state/log/ai-translate/app.log
macOS ~/Library/Logs/ai-translate/app.log
Windows %LOCALAPPDATA%\ai-translate\logs\app.log

تلتقط السجلات دائمًا DEBUG+ بغض النظر عن إسهاب وحدة التحكم. مخرجات وحدة التحكم هي INFO+ افتراضيًا؛ مرر --verbose إلى CLI لعكس سجل الملف الكامل على stdout.

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