ترجمة واستخدام رسائل التحقق بإطار العمل Laravel

إن مفهوم التحقق من البيانات يقصد به التحقق من صحتها حسب قواعد معينة، ويقدم إطار العمل Laravel العديد من قواعد التحقق المتنوعة والجاهزة للإستخدام، كل ما يجب عليك فعله هو تحديد القواعد التي تريد التحقق منها على كل حقل، فمثلا أي حقل بريد إلكتروني يجب أن يكون على الصيغة التالية name@example.com فبهذه قاعدة يجب على أي نص بريد إلكتروني أن يكون بهذا الشكل، وإلا فإنه غير صحيح.

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

1. إضافة مجلد الترجمة و تغيير لغة التطبيق إلى العربية
2. استخدام أنواع قواعد تحقق مختلفة على أنواع متنوعة من الحقول، وتخصيص رسائلها، لتغطية كل المميزات التي يوفرها laravel لرسائل أخطاء التحقق، والتي هي:
3. رسائل الأخطاء الافتراضية، المتوفرة من قبل إطار العمل
4. تخصيص أسماء بديلة لأسماء الحقول المستخدمة
5. تخصيص رسائل بدلا من الرسائل الافتراضية
6. تخصيص قيم بديلة لقيم الحقول المستخدمة
   لتوضيح هذه النقاط سنحتاج إلى إنشاء نموذج، وسنفترض أننا سنقوم بإضافة حساب خاص بالمستخدم عن طريق هذا النموذج، الذي يتكون من الحقول التالية:

• اسم المستخدم
• البريد الإلكتروني
• تاريخ الميلاد
• نوع الحساب (حساب شخصي، حساب شركة)
• اسم الشركة، في حال كان نوع الحساب شركة
• رمز المرور

نقوم أولاً بإنشاء تطبيق جديد بإستخدام الأمر laravel new project-name ليأتي هذا التطبيق تلقائيا مستخدما اللغة الإنجليزية، ونلاحظ ذلك عند دخولنا لمجلد resources\lang الذي يحتوي على مجلدات فرعية بها بأسماء اللغات التي يدعمها التطبيق، لنجد أن مجلد اللغة الانجليزية مكون تلقائاً.



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

و لتوضيح هذه الرسائل وسنقوم بإضافة دالة store الخاصة بإضافة حساب مستخدم، تتكون من جزء التحقق من بيانات المدخلة وجزء إنشاء الحساب.

public function store()
{
     request()->validate([
         'name'         => 'required|string',
         'email'        => 'required|email|unique:users',
         'birth_date'   => 'required|before_or_equal: - 18 year',
         'type'         => 'required|in:person,company',
         'company_name' => 'required_if:type,company',
         'password'     => 'required|min:8',
     ]);

     User::create([
         'name'         => request('name'),
         'email'        => request('email'),
         'birth_date'   => request('birth_date'),
         'type'         => request('type'),
         'company_name' => request('company_name'),
         'password'     => bcrypt(request('password')),
     ]);
}

وعند تجربتنا لإدخال كل الحقول فارغة ستظهر رسائل الأخطاء كالتالي:

ملاحظة: لن أتطرق بهذه المقالة عن كيفية تصميم الواجهة والفورم، وعن كيفية عرض رسائل الأخطاء على الواجهة.

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

هكذا نكون قد كونا مجلداّ للغة العربية ولكن النصوص الرسائل الموجودة بالملفات لاتزال باللغة الانجليزية، لترجمة محتوى هذه الملفات يمكننا ترجمتها كما نريد بتغيير النصوص المذكورة به إلى مرادفها باللغة العربية ولكن هذا سيأخذ وقتا طويلاً وسيتطلب منك جهدا لترجمتهم باللغة النحوية الصحيحة. الحل الاخر والذي أنا أتبعه هو البحث على github على ترجمة اللغات لإطار العمل laravel وستجد العديد من الحزم التي الذي يمكنك استخدامها، أنا سأقوم بإستخدام هذه الحزمة laravel lang.

بمجلد src سنجد مجلدات لعدة لغات وكل مجلد لغة يحتوي على ملفات الترجمة الإفتراضية التي يستخدمها Laravel مترجمةً لهذه اللغة، لنقوم بالبحث عن اللغة العربية بالاختصار ar ونقوم باستبدال محتويات الملفات الموجودة بمجلد ar الموجود لدينا بمحتويات الملفات الموجودة بالحزkمة.

الى الآن نحن لم نقم بتغيير اللغة، فقط قمنا بإضافتها وإضافة ترجمة النصوص التي سيتمكن التطبيق من استخدامها عند تغيير اللغة عن طريق الذهاب إلى ملف app.php الموجود داخل مجلد config وتتغير قيمة locale إلى ar.

والأن ستلاحظ تغيير رسائل أخطاء التطبيق إلى اللغة العربية

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

أولاً: حقليٍ اسم المستخدم والبريد الإلكتروني

للتحقق من صحة هذين الحقلين استخدمنا القواعد التالية عليهم

 'name'  => 'required|string',
  'email' => 'required|email|unique:users',

وهذا يعني أن كلاهما يجب إدخاله، ويجب على الاسم أن يكون من نوع string وعلى البريد الإلكتروني أن يمتثل لصيغة البريد الالكتروني، في حال قيام المستخدم بالإضافة دون إدخال هذين الحقلين، سيتم تلقائيا عرض رسالة الخطأ الإفتراضية لقاعدة required بإطار العمل بملف validation والتي هي:

 'required' => ':attribute مطلوب.',

لتظهر على الواجهة كالتالي:

ولكن ما هو المتغير :attribute الذي تم استخدامه بالرسالة؟

يقوم laravel بإستخدام هذا المتغير وعدة متغيرات أخرى تخص الحقل تحت قاعدة التحقق واستبدالها بقيم خلال التنفيذ، فمثلا

• attribute: متغير يدل على اسم الحقل.
• format: يدل على نوع الملف
• value: يدل على قيمة الحقل
• وعدة متغيرات أخرى تستخدم على حسب نوع القاعدة، ليتم عرض رسائل مفهومة وواضحة للمستخدمين، وكما رأينا فقد تم إستبدال متغير :attribute باسم الحقل.

ولكننا لاحظنا بٍكلا المثالين أنه قد تم ترجمة اسم الحقل أيضا، كيف تم هذا؟

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

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

'attributes' => [
       'name'                  => 'الاسم',
       'username'              => 'اسم المُستخدم',
       'email'                 => 'البريد الالكتروني',
       'first_name'            => 'الاسم الأول',
       'last_name'             => 'اسم العائلة',
       'password'              => 'كلمة المرور',
       'password_confirmation' => 'تأكيد كلمة المرور',
       'city'                  => 'المدينة',
       'country'               => 'الدولة',
       'address'               => 'عنوان السكن',
       'phone'                 => 'الهاتف',
       'mobile'                => 'الجوال',
       'age'                   => 'العمر',
       'sex'                   => 'الجنس',
       'gender'                => 'النوع',
       'day'                   => 'اليوم',
       'month'                 => 'الشهر',
       'year'                  => 'السنة',
       'hour'                  => 'ساعة',
       'minute'                => 'دقيقة',
       'second'                => 'ثانية',
       'title'                 => 'العنوان',
       'content'               => 'المُحتوى',
       'description'           => 'الوصف',
       'excerpt'               => 'المُلخص',
       'date'                  => 'التاريخ',
       'time'                  => 'الوقت',
       'available'             => 'مُتاح',
       'size'                  => 'الحجم',
     ,
   ],

في مثالنا هذا قمنا قمت بتسمية الحقلي email,name ولكن عند عرض الرسالة تم استبدالهم "البريد الالكتروني"، "الاسم" نظرا لاحتواء المصفوفة على هذين الحقلين.

'name'  => 'الاسم',
'email' => 'البريد الالكتروني',

ثانياً: تاريخ الميلاد للتحقق من هذا الحقل، قمنا بتأكد من أنه يجب على المستخدم إدخاله ويجب أن يكون عمر المستخدم أكبر أو يساوي من 18 سنة.

 'birth_date'   => 'required|before_or_equal: - 18 year',

واستخدمت لهذا القاعدة before_or_equal ليتم عرض الرسالة الإفتراضية لهذه القاعدة كالتالي:

ولكن هذه الرسالة ليست مفهومة للمستخدم، كيف نقوم باستبدالها برسالة أخرى!

بغض النظر أنها غير مفهومة للمستخدم فهذه القاعدة تعمل بشكل صحيح فنحن لا نريد إزالتها، في هذه الحالة يقدم ملف الترجمة مصفوفة أخرى التي ستقوم بحل هذه المشكلة وهي custom

'custom' => [
       'attribute-name' => [
           'rule-name' => 'custom-message',
       ],
   ],

يمكنك من خلال هذه المصفوفة تحديد رسائل مخصصة لكل حقل ولكل قاعدة مستخدمة عليه ليتم بعرض هذه الرسالة والتغاضي عن الرسالة الافتراضية المحددة لهذه القاعدة.

فنحن يمكننا استخدامها كالاتي:

'custom' => [
       'birth_date' => [
           'before_or_equal' => 'يجب أن يكون عمر المستخدم أكبر من 18 سنة.',
       ],
   ],

هنا قمنا بتحديد أنه على الحقل birth_date وعند وجود خطأ على القاعدة 'before_or_equal' أن يقوم بعرض رسالة الخطأ هذه بدل الرسالة الإفتراضية، لتكون كالتالي:.

ثالثا: نوع الحساب واسم الشركة

للتحقق من نوع حساب المستخدم ليكون حساب شركة أم حساب شخصي، ولتأكد من أن المستخدم يحب عليه أن يدخل اسم شركته في حال اختار نوع الحساب لشركة، استخدمنا القواعد التالية:

'type'         => 'required|in:person,company',
'company_name' => 'required_if:type,company',

في حال اختيارنا لحساب من نوع شركة، وتركنا اسم الشركة فارغ ستظهر الرسالة التالية:

كما فعلنا سابقا نستطيع ترجمة اسم الحقلي company_name ,type بوضع قيمة بديلة لهم بمصفوفة attributes كالتالي:

'company_name'          => 'اسم الشركة',
'type'                  => 'نوع الحساب',

لتتغير الرسالة إلى الأتي:

ولكن لماذا تظهر القيمة company هكذا، لن يستطيع المستخدمين فهمها، هل يوفر إطار العمل حل لهذا أيضا؟

نعم إضافةً لترجمة أسماء الحقول،يمكنك أيضا ترجمة القيم التي يمكن أن تحتويها هذه الحقول، فمثلا هنا نوع الحساب يمكن أن يحتوي على قيمتي person أو company وذلك حسب ما سميناهم برمجيا لدينا، يمكننا ترجمتهم عن طريقة مصفوفة values، لن نجد هذه المصفوفة بملف validation عند أي مشروع laravel جديد ولكن يمكننا

تعريفها حسب ما ذكر بالتوثيق ، لتكون كالتالي:

'values' => [
       'type' => [
           'company' => 'حساب شركة'
       ]
   ],

وهكذا ستتغير الرسالة لتصبح كالتالي:

الخلاصة

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

كما رأينا فإن سهولة التحقق من البيانات هي من أقوى المميزات laravel، للتعرف على المزيد عنها يمكنك زيارة الموقع الرسمي وقراءة التوثيق.