لماذا لا تظهر ترجماتك في WordPress (دليل استكشاف الأخطاء وإصلاحها)

لا يوجد شيء أكثر إحباطًا في تطوير WordPress من "الفشل الصامت".

لقد فعلت كل شيء بشكل صحيح. لقد ترجمت ملف ‎.po. لقد قمت بتجميعه في ملف ‎.mo. لقد قمت بتحميله إلى الخادم الخاص بك عبر FTP. لقد مسحت ذاكرة التخزين المؤقت.

تقوم بتحديث الصفحة، متوقعًا رؤية اللغة الإسبانية أو الفرنسية أو الألمانية. بدلاً من ذلك، ترى... اللغة الإنجليزية.

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

1. أنت تسمي الملف بشكل خاطئ

WordPress صارم بشكل لا يصدق بشأن تسمية الملفات. إذا فاتتك حرف، فلن يتم تحميل الملف.

التنسيق القياسي هو: {text-domain}-{locale}.mo

• نطاق النص: هذا هو المعرف الفريد للسمة أو البرنامج المساعد (على سبيل المثال، woocommerce، twentytwentyfour، my-custom-plugin).
• اللغة: رمز لغة WP (على سبيل المثال، es_ES للإسبانية في إسبانيا، fr_FR للفرنسية).

الأخطاء الشائعة:

• تسمية الملف es_ES.mo فقط (هذا يعمل فقط لملفات WordPress الأساسية العامة، وليس للبرامج المساعدة).
• استخدام الشرطة الخاطئة: my_plugin_es_ES.mo (شرطة سفلية) بدلاً من my-plugin-es_ES.mo (واصلة).
• تخمين نطاق النص. يجب عليك التحقق من كود البرنامج المساعد (رأس style.css أو دالة load_plugin_textdomain) للعثور على المصطلح المحدد.

2. أنت تضع الملف في المجلد الخطأ

مكان تحميل الملف مهم تمامًا مثل اسمه. يبحث WordPress في أدلة معينة بترتيب معين.

• مجلد النظام "الآمن": ‏/wp-content/languages/plugins/ أو /wp-content/languages/themes/.
  • الإيجابيات: هذا آمن من تحديثات البرنامج المساعد.
  • السلبيات: يجب عليك تسمية الملف textdomain-locale.mo.
• مجلد المؤلف: ‏/wp-content/plugins/plugin-name/languages/.
  • الإيجابيات: سهل العثور عليه.
  • السلبيات: خطر. عند تحديث البرنامج المساعد، يتم مسح هذا المجلد بالكامل. ستختفي ترجماتك.

أفضل الممارسات: ضع دائمًا ملفات ‎.mo المخصصة في الدليل العام /wp-content/languages/ لمنع فقدان البيانات أثناء التحديثات.

3. "القاتل الصامت": بناء جملة تالف في ملف ‎.po

هذه هي أصعب مشكلة في التصحيح، وتحدث بشكل متكرر مع أدوات الترجمة بالذكاء الاصطناعي العامة.

يقرأ WordPress ملفات ‎.mo الثنائية، والتي يتم تجميعها من ملفات ‎.po النصية. إذا كان ملف ‎.po الخاص بك يحتوي على أخطاء في بناء الجملة، فقد يتم إنشاء ملف ‎.mo، ولكنه سيكون "معطلاً" داخليًا.

كيف يحدث هذا؟ إذا أفسد المترجم (البشري أو الذكاء الاصطناعي) تنسيق Gettext، فسيصبح السلسلة غير صالحة.

• مثال: فقدان علامة اقتباس الإغلاق ".
• مثال: كسر متغير (تغيير %s إلى % s).
• مثال: إفساد عدد msgid_plural.

عندما يصادف WordPress إدخالاً معطلاً في ملف ‎.mo، فإنه غالبًا ما يتخطاه أو يتوقف عن قراءة الملف تمامًا، ويعود إلى اللغة الإنجليزية الأصلية.

4. لقد نسيت التجميع (‎.po مقابل ‎.mo)

لا يمكن لـ WordPress قراءة ملفات ‎.po مباشرةً. هذا مفهوم خاطئ شائع.

• ‎.po = يمكن للبشر قراءتها (كائن محمول).
• ‎.mo = يمكن للآلات قراءتها (كائن آلي).

إذا قمت بتحميل ملف my-theme-es_ES.po ولكن نسيت إنشاء ملف ‎.mo المطابق، فلن يحدث شيء. يجب عليك تجميعه.

5. التخزين المؤقت (المشتبه به المعتاد)

إذا كنت تستخدم مكونات إضافية للتخزين المؤقت (WP Rocket، LiteSpeed) أو التخزين المؤقت من جانب الخادم (Varnish، Redis)، فقد يعرض موقعك إصدار HTML مخزن مؤقتًا من قبل تحميل الترجمة.

الحل: امسح جميع ذاكرات التخزين المؤقت، بما في ذلك ذاكرة التخزين المؤقت للمتصفح وذاكرة التخزين المؤقت للكائنات.

الحل النهائي: ملفات صالحة من البداية

يعد استكشاف أخطاء مسارات الملفات وأسمائها أمرًا سهلاً. يعد استكشاف أخطاء بناء الجملة التالف (السبب رقم 3) كابوسًا.

إذا كنت تستخدم أداة تكسر متغيرات التعليمات البرمجية الخاصة بك أو تفسد بنية Gettext، فسوف تقضي ساعات في التساؤل عن سبب عدم عمل الملف، دون إدراك أن الملف نفسه "مسموم".

هذا هو السبب في أننا قمنا ببناء SimplePoTranslate.

• تأمين بناء الجملة: نضمن أن كل سلسلة مفردة صالحة نحويًا قبل تنزيلها. نقوم بتأمين متغيرات مثل %s حتى لا يمكن كسرها.
• تنسيق مثالي: نقوم بإنشاء ملفات ‎.po نظيفة وقياسية يتم تجميعها في ملفات ‎.mo عاملة بنسبة 100% من الوقت.
• لا توجد مكونات إضافية مطلوبة: تقوم بتنزيل الملف، وأنت تعلم أنه يعمل. ما عليك سوى تحميله إلى المجلد الصحيح.
• مكون WordPress الإضافي: هل تفضل تخطي التحميل اليدوي تمامًا؟ يكتشف مكون SimplePoTranslate WordPress الإضافي الرسمي ملفات ‎.pot الخاصة بالسمة والبرامج المساعدة تلقائيًا، ويترجمها في السحابة، وينشر النتيجة في الدليل الصحيح بالاسم الصحيح. لا مزيد من الملفات التي تحمل أسماء خاطئة، ولا مزيد من مسارات المجلدات الخاطئة - وهما السببان الأكثر شيوعًا لفشل ظهور الترجمات.

توقف عن تخمين سبب عدم ظهور ترجماتك. ابدأ بملف يمكنك الوثوق به.

هل أنت مستعد للترجمة دون صداع؟ ابدأ مجانًا على SimplePoTranslate.com