كيفية إنشاء ملف .pot لقالَب أو إضافة

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

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

يستعرض هذا الدليل شقي المهمة: إعداد الكود المصدري الخاص بك بحيث يمكن اكتشاف السلاسل النصية، ثم إنشاء ملف .pot نفسه بثلاث أدوات مختلفة. سنستخدم WP-CLI و Poedit والنهج القديم makepot/grunt، مع أوامر حقيقية يمكنك نسخها. بنهاية المطاف، سيكون لديك قالب نظيف جاهز لتسليمه لأي مترجم.

الخطوة الأولى: وضع علامة على سلاسلك النصية كقابلة للترجمة

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

يوفر WordPress مجموعة من دوال التوطين، كل منها لسياق مختلف قليلاً:

// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );

// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );

// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );

// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );

الوسيط الثاني في كل استدعاء — 'my-plugin' — هو نطاق النص (text domain). يقوم بتجميع جميع السلاسل النصية لإضافة أو قالب تحت مساحة اسم واحدة حتى يعرف WordPress أي ملف .mo يجب تحميله لها. يجب أن تشارك كل سلسلة نصية قابلة للترجمة في مشروعك نفس نطاق النص بالضبط، وإلا فلن يتم ترجمة بعض السلاسل أبدًا.

استخدم _x() كلما كانت الكلمة غامضة. يمكن أن تكون كلمة "Post" الإنجليزية اسمًا أو فعلًا، وتترجمها العديد من اللغات بشكل مختلف. تسمح سلاسل السياق للمترجمين بتمييزها. واستخدم صيغ esc_html__() و esc_attr__() كلما تم طباعة السلسلة المترجمة في HTML، لتبقى آمنًا وموطنًا في نفس الوقت.

هناك بعض العادات التي تحافظ على إمكانية استخراج سلاسلك النصية. قم دائمًا بتمرير سلسلة نصية حرفية عادية كوسيط أول — لا تمرر أبدًا متغيرًا أو عملية دمج مثل __( 'Hello ' . $name, 'my-plugin' )، لأن الماسح الضوئي يقرأ النص المصدري بشكل ثابت ولا يمكنه حل قيم وقت التشغيل. للجمل التي تحتوي على رقم، استخدم _n() بحيث يتم التقاط صيغ الجمع بشكل صحيح، وللجمل التي تحتوي على قيمة ديناميكية، استخدم sprintf() حول عنصر نائب مثل %s بدلًا من لصق السلاسل ببعضها البعض. الاتساق هنا هو ما يجعل الخطوة التالية — إنشاء القالب — تنتج نتيجة كاملة وقابلة للاستخدام.

الخطوة الثانية: الإعلان عن نطاق النص في ترويستك

يحتاج WordPress إلى حقلي ترويسة لمعرفة مكان ترجماتك: نطاق النص (Text Domain) و مسار النطاق (Domain Path). قم بتعيينهما في الملف الرئيسي لإضافتك أو في ملف style.css لقالَبك، وسيقوم WordPress تلقائيًا بتحميل ملف .mo الصحيح أثناء وقت التشغيل.

<?php
/**
 * Plugin Name:       My Plugin
 * Description:        A perfectly localized WordPress plugin.
 * Version:            1.0.0
 * Requires at least: 6.4
 * Text Domain:       my-plugin
 * Domain Path:       /languages
 */

يجب أن يتطابق نطاق النص (Text Domain) مع السلسلة التي مررتها إلى كل استدعاء __() و _e() — my-plugin هنا. يخبر مسار النطاق (Domain Path) ووردبريس بأي مجلد فرعي يحتوي على ملفات الترجمة، بالنسبة إلى جذر الإضافة أو القالب. التقاليد هي /languages، وهذا هو بالضبط المكان الذي يجب أن يتواجد فيه ملف .pot الذي تم إنشاؤه.

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

كيف تنشئ ملف .pot؟ ثلاث طرق

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

الطريقة 1: WP-CLI (موصى بها)

الطريقة الرسمية والحديثة لإنشاء ملف POT هي WP-CLI باستخدام أمر i18n. يأتي كجزء من أدوات WordPress الأساسية، ويفهم سلاسل PHP و JavaScript، وينتج قالبًا متوافقًا مع المعايير في سطر واحد.

# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot

# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin

# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules

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

يتضمن القالب الذي تم إنشاؤه بيانات وصفية مفيدة يمكنك تعديلها باستخدام علامات إضافية. مرر --headers لتعيين اسم المشروع والإصدار وعنوان الاتصال بالمترجمين، بحيث يتم ملء كتلة ترويسة .pot بشكل صحيح بدلًا من تركها كعناصر نائبة. يستخرج WP-CLI أيضًا سلاسل JavaScript من استدعاءات wp_set_script_translations() تلقائيًا، وهو أمر مهم لقوالب الكتل الحديثة وإضافات Gutenberg حيث يعيش نصف النص الموجه للمستخدم في JavaScript بدلًا من PHP. أمر واحد يغطي كلا العالمين.

الطريقة 2: Poedit (رسومية)

إذا كنت تفضل تطبيق سطح مكتب، يمكن لـ Poedit مسح الكود المصدري الخاص بك وإنشاء القالب من خلال واجهته. افتح Poedit، اختر إنشاء ترجمة جديدة من POT أو مسح المصادر مباشرةً، وجهه إلى مجلد مشروعك، وقم بتكوين الكلمات المفتاحية المصدر (__, _e, _x, esc_html__) ضمن خصائص الكتالوج.

توجد ميزات مسح المصادر وإنشاء ملفات .pot في إصدار Pro من Poedit، ولكن سير العمل ودود للمطورين الذين يفضلون النقر بدلًا من كتابة الأوامر. إنه أيضًا محرر قوي لمرحلة الترجمة التي تلي ذلك. تتم مقارنة Poedit والعديد من خيارات سطح المكتب الأخرى في أفضل 5 أدوات مجانية لتحرير وترجمة ملفات PO على Mac و Windows.

الطريقة 3: makepot / grunt (قديمة)

قبل WP-CLI، كانت الأداة القياسية هي السكربت makepot.php من مستودع WordPress i18n-tools، والذي غالبًا ما كان يدمج في مهمة بناء Grunt باستخدام grunt-wp-i18n. ستظل تجده في الإضافات والقوالب القديمة.

# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot

إنه يعمل، ولكنه غير محفوظ مقارنة بـ WP-CLI وأبطأ في الإعداد. استخدمه فقط عندما تقوم بصيانة مشروع قديم يعتمد عليه بالفعل؛ لأي شيء جديد، فضل wp i18n make-pot.

حافظ على تحديث القالب مع تغيرات الكود الخاص بك

ملف .pot هو لقطة لسلاسلك النصية في لحظة معينة. في كل مرة تضيف فيها ميزة، أو تغير تسمية، أو تصلح خطأ مطبعيًا في سلسلة نصية مرئية، يصبح القالب قديمًا ويفوت المترجمون الصياغة الجديدة.

اجعل إعادة الإنشاء جزءًا من روتين إصدارك. أعد تشغيل wp i18n make-pot قبل كل تحديث للإصدار، ثم ادمج القالب المحدث في الترجمات الموجودة باستخدام wp i18n update-po أو msgmerge حتى يحتفظ المترجمون بعملهم المكتمل ويرون فقط الفجوات الجديدة. تعامل مع ملف .pot كمنتج بناء تقوم بإعادة إنشائه، وليس كملف تقوم بتحريره يدويًا.

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

بمجرد أن يعيد المترجمون ملفات .po المكتملة، لا تزال بحاجة إلى تجميعها إلى ملف .mo الثنائي الذي يقوم WordPress بتحميله بالفعل — وإذا كنت تفضل تخطي حلقة التنزيل والترجمة وإعادة التجميع بأكملها، يمكن لأداة سحابية التعامل معها من البداية إلى النهاية. SimplePoTranslate تقبل ملف .pot الخاص بك مباشرةً، وترجمه باستخدام الذكاء الاصطناعي الواعي بالسياق (Context-Aware AI) الذي يفهم معنى كل سلسلة نصية في واجهتك، وتعيد ملف ZIP واحدًا يحتوي على .po و .mo والمزيد مجهزًا ومسمى بالفعل. يقوم قفل بناء الجملة (Syntax Locking) بتجميد العناصر النائبة مثل %s و %1$s بحيث لا تتعطل متغيراتك أبدًا في الترجمة.

خلاصة القول

لـ إنشاء ملف POT بالطريقة الصحيحة، اجعل الكود الخاص بك قابلاً للاكتشاف أولاً — قم بتغليف كل سلسلة نصية مرئية في __()، _e()، _x()، أو أحد المتغيرات الهروبية، وكلها تشترك في نطاق نص واحد، وأعلن عن هذا النطاق بالإضافة إلى Domain Path في ترويستك. ثم أنشئ القالب باستخدام WP-CLI للمشاريع الجديدة، أو Poedit إذا كنت تفضل واجهة المستخدم الرسومية، أو makepot فقط عند صيانة الكود القديم.

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

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