كيفية تجميع ملفات .po إلى .mo (4 طرق)

لقد قضيت فترة ما بعد الظهر في إتقان ترجمة ألمانية. كل سلسلة نصية في ملف de_DE.po الخاص بك مقروءة بشكل جميل، والعناصر النائبة سليمة، وصيغ الجمع صحيحة. تقوم بتحميله إلى موقعك، وتغيير اللغة إلى الألمانية، و... لا شيء. لا تزال الصفحة باللغة الإنجليزية. تتحقق مرة أخرى من اسم الملف، والمجلد، ونطاق النص (text domain). كل شيء يبدو صحيحًا. فلماذا لا يعرض ووردبريس ترجمتك؟

في تسع مرات من أصل عشرة، الإجابة هي نفسها: لقد قمت بتحرير ملف .po ولكنك لم تقم أبدًا بتجميعه إلى .mo. لا يقرأ ووردبريس ملفات .po أثناء التشغيل — بل يقوم بتحميل الملف الثنائي المجمّع .mo. إذا كنت تريد أن تظهر ترجماتك بالفعل، فأنت بحاجة إلى تجميع ملفات po إلى mo في كل مرة تقوم فيها بتغيير النص. ملف .po هو مصدرك القابل للتحرير؛ وملف .mo هو ما يقدمه الموقع.

يشرح هذا الدليل سبب وجود خطوة التجميع هذه، ثم يستعرض أربع طرق موثوقة للقيام بذلك: WP-CLI، أمر msgfmt الكلاسيكي، Poedit، وأداة سحابية تنتج ملف .mo لك تلقائيًا. سنتناول أيضًا الخطأ الأكثر شيوعًا — نسيان إعادة التجميع — وتنسيق .l10n.php الأحدث الذي يفضله ووردبريس الآن من أجل السرعة.

لماذا يقوم ووردبريس بتحميل ملفات .mo وليس .po؟

يقوم ووردبريس بتحميل ملفات .mo لأنها ثنائيات مجمعة ومحسنة للبحث السريع، بينما ملفات .po هي نصوص عادية مصممة ليقرأها البشر ويعدلوها. سيكون تحليل النص في كل مرة يتم فيها تحميل صفحة بطيئًا؛ أما قراءة جدول تجزئة ثنائي مُعد مسبقًا فهو فوري تقريبًا.

ملف .po يعتمد على الأسطر وصديق للبشر. يربط كل إدخال معرف رسالة المصدر (msgid) بسلسلة مترجمة (msgstr)، بالإضافة إلى تعليقات تشير إلى مصدر السلسلة. هذا رائع للتحرير ولكنه سيء للأداء — سيتعين على الخادم إعادة تحليل ملف النص بالكامل في كل طلب.

#: includes/cart.php:88
msgid "Your cart is empty"
msgstr "Ihr Warenkorb ist leer"

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

أربع طرق لتجميع ملفات po إلى mo

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

الطريقة الأولى: WP-CLI

النهج الحديث والأنظف هو WP-CLI، والذي يمكنه تجميع مجلد كامل من ملفات .po في أمر واحد. إذا كنت تدير ووردبريس بالفعل من سطر الأوامر، فإن هذا يتناسب بشكل طبيعي مع سير عملك.

# Compile every .po file in the languages folder to .mo
wp i18n make-mo languages/

# Compile into a specific destination directory
wp i18n make-mo languages/ build/languages/

يقوم أمر make-mo بمسح الدليل المستهدف، ويجمع كل ملف .po يجده، ويكتب ملف .mo مطابقًا بجانبه (أو في الوجهة التي تحددها). يتعامل مع الدُفعات بسلاسة، مما يجعله مثاليًا عندما تحتفظ بالعديد من اللغات في وقت واحد. إنها الأداة الموصى بها لأي مشروع يستخدم WP-CLI بالفعل.

الطريقة الثانية: msgfmt

الأداة الأصلية من Gettext لهذه المهمة هي msgfmt، وهي جزء من حزمة GNU gettext. تقوم بتجميع ملف .po واحد إلى ملف .mo واحد وهي متوفرة على جميع أنظمة Linux و macOS تقريبًا.

# Compile one file
msgfmt my-plugin-de_DE.po -o my-plugin-de_DE.mo

# Add statistics about translated, fuzzy, and untranslated strings
msgfmt --statistics my-plugin-de_DE.po -o my-plugin-de_DE.mo

# Install it first if missing
#   macOS:  brew install gettext
#   Debian: sudo apt-get install gettext

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

نظرًا لأن msgfmt هي أداة سطر أوامر بسيطة، فإنها تتناسب بشكل أنيق مع الأتمتة. يمكنك تضمينها في حلقة shell لتجميع مجلد كامل، أو توصيلها بخط أنابيب CI بحيث ينتج كل التزام يمس ملف .po ملف .mo جديدًا تلقائيًا. نمط شائع هو for f in languages/*.po; do msgfmt "$f" -o "${f%.po}.mo"; done، والذي يجمع كل لغة في تمريرة واحدة. تضيف الراية --check التحقق من الصحة، وتحدد عدم تطابق سلاسل التنسيق بين msgid و msgstr قبل وصولها إلى الإنتاج — وهو ضمان رخيص ضد أخطاء العناصر النائبة المعطلة التي تفسد التخطيطات المترجمة بصمت.

الطريقة الثالثة: Poedit (يجمع تلقائيًا عند الحفظ)

إذا قمت بتحرير الترجمات في محرر رسومي، فإن Poedit يقوم بالتجميع لك تلقائيًا. في كل مرة تحفظ فيها ملف .po، يكتب Poedit ملف .mo المطابق بجانبه مباشرةً — لا يوجد أمر منفصل، ولا خطوة إضافية.

هذا أحد الأسباب التي تجعل Poedit يظل شائعًا بين المترجمين الذين لا يشعرون بالراحة عند استخدام سطر الأوامر. تفتح ملف .po، تكتب ترجماتك، تضغط على حفظ، ويتم تحديث كلا الملفين معًا. يمكنك تأكيد السلوك ضمن تفضيلات Poedit، حيث يتم تمكين تجميع ملف .mo التلقائي عند الحفظ بشكل افتراضي. تتم مراجعة Poedit وأدوات سطح المكتب المماثلة في أفضل 5 أدوات مجانية لتحرير وترجمة ملفات PO على Mac و Windows.

المشكلة في المحرر المكتبي هي أن التجميع يحدث فقط عندما يفتح الإنسان الملف ويحفظه. هذا جيد لمشروع فردي، ولكنه لا يتوسع ليشمل اثنتي عشرة لغة أو فريقًا يتبادل الملفات. إذا قام شخص ما بتحرير ملف .po في أداة مختلفة ونسخه إلى المستودع دون فتح Poedit، فلن يتم تحديث ملف .mo أبدًا. بالنسبة للمشاريع الأكبر أو التعاونية، تزيل طريقة مؤتمتة — سطر الأوامر أو السحابة — هذا الاعتماد على تذكر الضغط على حفظ.

الطريقة الرابعة: أداة سحابية تنشئ ملف .mo لك

يزيل الخيار الرابع خطوة التجميع بالكامل: استخدم خدمة سحابية تعيد ملف .mo المجمع مع ملف .po المترجم. لا تقوم أبدًا بتشغيل أمر أو حفظ ملف مرتين — أنت تقوم بالتحميل، وتعود الملفات المكتملة والمُسماة بشكل صحيح.

يعمل SimplePoTranslate بهذه الطريقة تمامًا. تقوم بتحميل ملف .po أو .pot، وتقوم بترجمة السلاسل النصية باستخدام الذكاء الاصطناعي الواعي بالسياق (Context-Aware AI)، ويعيد ملف ZIP واحدًا يحتوي على ملفي .po و .mo المُنشأة جنبًا إلى جنب — مجمعة بالفعل، ومسماة بالفعل لتتوافق مع نطاق النص واللغة المحلية الخاصة بك. لا توجد تمريرة تجميع منفصلة ولا توجد فرصة لنسيان واحدة.

كما يتعامل مع التفاصيل التي تعطل سير العمل اليدوي. قفل بناء الجملة (Syntax Locking) يجمد العناصر النائبة مثل %s و %1$s و {name} بالإضافة إلى علامات HTML قبل الترجمة، بحيث تبقى متغيراتك سليمة في ملف .mo. الدعم الكامل لـ صيغ الجمع في Gettext (Gettext plural) يعني أن صيغ الجمع المعقدة يتم تجميعها بشكل صحيح أيضًا — وهو موضوع يستحق الفهم العميق، والذي نغطيه في فهم صيغ الجمع في Gettext. ولأنه يعمل في السحابة، لا توجد إضافة لتثبيتها ولا توجد أدوات بناء (build tooling) للحفاظ عليها.

الخطأ الأكثر شيوعًا: نسيت إعادة التجميع

السبب الأكبر والأوحد لعدم ظهور الترجمات هو تحرير ملف .po ولكن نسيان إعادة تجميع ملف .mo. يستمر ووردبريس في تحميل الملف الثنائي القديم، لذلك لا تظهر صياغتك الجديدة أبدًا — ولا توجد رسالة خطأ تخبرك بالسبب.

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

هذا الخطأ خفي بشكل خاص عند تسليم المشاريع من بيئة التطوير (staging) إلى بيئة الإنتاج (production). يقوم المطور بالتحرير وإعادة التجميع محليًا، ويرى الترجمة تعمل، ثم ينشر ملف .po فقط وينسى ملف .mo — لذلك تحتفظ بيئة الإنتاج بالنص القديم بصمت. كلما نقلت ملفات الترجمة بين البيئات، انقل ملفي .po و .mo المجمع حديثًا معًا، أو قم بالتجميع كجزء من خطوة النشر الخاصة بك بحيث يتم دائمًا إعادة بناء الملف الثنائي من المصدر الحالي.

إذا كانت ترجماتك لا تزال ترفض الظهور بعد إعادة التجميع، فالمشكلة عادة ما تكون عدم تطابق في التسمية، أو مجلد خاطئ، أو طبقة تخزين مؤقت (caching layer) تحتفظ بالملف القديم. القائمة المرجعية الكاملة موجودة في لماذا لا تظهر ترجماتك في ووردبريس.

ملاحظة حول تنسيق .l10n.php الأحدث

قدمت إصدارات ووردبريس الأخيرة تنسيق تشغيل ثالث: .l10n.php. بدلاً من ملف .mo الثنائي، يتم تخزين الترجمات كمصفوفة PHP عادية يمكن لذاكرة التخزين المؤقت لرمز التشغيل (opcode cache) في PHP الاحتفاظ بها في الذاكرة، مما يجعل عمليات البحث أسرع حتى من .mo في المواقع المزدحمة.

<?php
return [
	'domain'  => 'my-plugin',
	'messages' => [ 'Your cart is empty' => 'Ihr Warenkorb ist leer' ],
];

يقوم ووردبريس بإنشاء ملفات .l10n.php تلقائيًا عندما يكون لديه ملف .mo المطابق متاحًا، لذلك لا تحتاج إلى إنشائها يدويًا. في الوقت الحالي، يظل تجميع ملف .mo صحيحًا هو الأساس — يتم اشتقاق تنسيق الأداء منه.

الخلاصة

لـ تجميع ملفات po إلى mo بشكل موثوق، اختر الطريقة التي تتناسب مع طريقة عملك: WP-CLI لدُفعات سطر الأوامر، msgfmt للملفات الفردية مع الإحصائيات، Poedit للتجميع التلقائي عند الحفظ، أو أداة سحابية تبني ملف .mo لك بحيث لا يتم تخطي هذه الخطوة أبدًا. تنتج جميع الطرق الأربع نفس الملف الثنائي الذي يحتاجه ووردبريس أثناء التشغيل.

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

هل أنت مستعد لتخطي خطوة التجميع اليدوي للأبد؟ جرب SimplePoTranslate مجانًا — لا يلزم وجود بطاقة ائتمان. قم بتحميل ملف .po الخاص بك وقم بتنزيل حزمة .po + .mo جاهزة للنشر على الطبقة المجانية في دقائق.