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

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

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

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

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

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

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

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

• نطاق النص (Text Domain): هذا هو المعرف الفريد للسمة أو المكون الإضافي (على سبيل المثال، woocommerce، twentytwentyfour، my-custom-plugin).
• الإعدادات المحلية (Locale): رمز الإعدادات المحلية لـ 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 vs .mo)

لا يستطيع WordPress قراءة ملفات .po مباشرة. هذا مفهوم خاطئ شائع.

• .po = قابل للقراءة من قبل البشر (Portable Object).
• .mo = قابل للقراءة من قبل الآلات (Machine Object).

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

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

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

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

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

استكشاف أخطاء مسارات الملفات وأسمائها وإصلاحها أمر سهل. استكشاف أخطاء بناء الجملة التالف وإصلاحها (السبب #3) كابوس.

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

لهذا السبب قمنا ببناء SimplePoTranslate.

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

توقف عن التخمين لماذا ترجماتك غير مرئية. ابدأ بملف يمكنك الوثوق به.

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