Laravel/localization

مقدمة

تُقدِّم خاصيّة التوطين في Laravel طريقةً مريحةً وسهلةً لإعطاء ترجمات للكلمة في عدّة لغات، ممّا يسمح للتطبيق بدعم لغات متعدّدة. تُحفظ سلاسل المحارف الخاصّة بكل لغة يدعمها التطبيق في المجلد resources/lang. يحتوي هذا الملف على مجلدٍ فرعي لكل للغة يدعمها التطبيق:

/resources
    /lang
        /en
            messages.php
        /es
            messages.php

تتمثل القيمة المعادة لكل ملف لغة في مصفوفة لسلاسل المحارف مرفقةً بمفاتيح:

<?php

return [
    'welcome' => 'Welcome to our application'
];

ضبط المحليّة

تُحفظ اللغة الأولى للتطبيق في ملف الضبط config/app.php. يمكن بالطبع تغيير اللغة الأولى لتتناسب مع ما يحتاجه التطبيق. يمكن أيضا تغيير اللغة النشيطة للتطبيق في زمن التشغيل باستعمال التابع setLocale من الواجهة الساكنة App.

Route::get('welcome/{locale}', function ($locale) {
   App::setLocale($locale);
  //
});

تحديد المحليّة الحالية

يُستعمَل التابعان getLocale و isLocale من الواجهة App لتحديد ما هي المحليّة (locale) أو التحقق أنها تساوي قيمةً معطاة:

$locale = App::getLocale();
if (App::isLocale('en')) {
  //
}

تعريف سلاسل الترجمة

استعمال مفاتيح قصيرة

في العادة، تُحفظ سلاسل الترجمة في ملفّات في المجلد resources/lang. وفيه مجلدٌ فرعي لكل لغة مدعومة من التطبيق:

/resources
   /lang
       /en
           messages.php
       /es
           messages.php

تتمثل القيمة المعادة لكل ملف لغة في مصفوفة لسلاسل نصية مرفقةً بمفاتيح:

<?php
// resources/lang/en/messages.php
return 
   'welcome' => 'Welcome to our application'
];

استعمال سلاسل الترجمة كمفاتيح

إنّ استعمال مفاتيح قصيرة في تطبيقات تتطلب الكثير من الترجمة يصبح مربكًا عند استعمالها في الواجهات (views). لهذا السبب يوفّر Laravel دعمًا لتعريف سلاسل ترجمة باستعمال سلسلة الترجمة الأصلية كمفتاح.

تُحفظ ملفات الترجمة التي تستعمل سلاسل الترجمة كمفاتيح على شكل ملفّات JSON في المجلد resources/lang. مثلا، إن أردت ترجمة إسبانية يجب أن تصنع الملف resources/lang/es.json

{

   "I love programming.": "Me encanta programar."

}

استرجاع سلاسل الترجمة

تُسترجع سطور من ملفات اللغة باستعمال دالة المساعدة __ .تقبل الدالة __ اسم الملف و المفتاح كمعامل أول. على سبيل المثال، لنبحث عن ترجمة السلسلة welcome في ملف اللغة

resources/lang/messages.php

echo __('messages.welcome');

echo __('I love programming.');

بالطبع إن كنت تستعمل محرك القولبة Blade يمكنك استعمال {{ }} لعرض سلسلة الترجمة أو استعمال التعليمة ‎@lang:قالب:('messages.welcome')@lang('messages.welcome')

إن كانت سلسلة الترجمة غير موجودة، فستعيد الدالة __ مفتاح الترجمة. لذا في المثال السابق، إن كانت سلسلة الترجمة غير موجودة،فستعيد الدالة __ النتيجة messages.welcome.

تعويض المعاملات في سلاسل الترجمة

إن أردت، بإمكانك تعريف نص بديل (place-holder) في سلسلة الترجمة. يُسبق كل نص بديل بالرمز :. مثلًا يمكن تعريف نص بديل لاسم في رسالة الترحيب:

'welcome' => 'Welcome, :name',

لتعويض النص البديل عند عادة سلسلة الترجمة، أدخل مصفوفة للبدائل كمعامل ثاني للدالة __:

echo __('messages.welcome', ['name' => 'dayle']);

إن كان النص البديل مكتوبًا بحروف كبيرة، أو إن كان الحرف الأول فقط كبيرا فإن الصيغة المحوَّلة ستُكتب بنفس الطريقة:

'welcome' => 'Welcome, :NAME', // Welcome, DAYLE

'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

الجمع

الجمع مشكلة معقّدة إذ تملك كل لغة العديد من القواعد المعقّدة للقيام بالجمع. نُفرّق بين الصيغة الفردية و صيغة الجمع للسلسلة باستخدام رمز "خط عمودي":

'apples' => 'There is one apple|There are many apples',

يمكن أيضا تعريف صيغ جمع أكثر تعقيدًا بتعريف صيغة جمع لكل نطاق أو مجال:

'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',

بعد تعريف سلسلة ترجمة بعدّة صيغ جمع، تُستعمل الدالة trans_choice لاسترجاع سطر الترجمة بعدد معيّن. في المثال التالي، لأن العدد أكبر من واحد، صيغة الجمع هي التي تُعاد:

echo trans_choice('messages.apples', 10);

يمكن أيضًا تعريف نص بديل لسلاسل ترجمة في صيغة الجمع. تعوَّض النصوص البديلة تلك بتمرير مصفوفة كمعامل ثالث للدالة trans_choice:

'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',

echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

تجاوز حزم اللغات

قد تُشحن بعض الحزم بملفات لغاتها الخاصّة. بدل تغيير ملفات الحزمة لتعديل بعض هذه الترجمات، يمكن تجاوزها بصنع ملفات ترجمتك الخاصّة في الملف:

resources/lang/vendor/{package}/{locale}

على سبيل المثال، إن أردت تجاوز سلاسل الترجمة الإنجليزية في messages.php من الحزمة skyrim/hearthfire، يجب عليك وضع ملفات الترجمة الجديدة في:

resources/lang/vendor/hearthfire/en/messages.php.

في هذا الملف، يجب تعريف سلاسل الترجمة التي تريد تجاوزها وإعادة تعريفها فقط. تُحمَّل كل سلسلة ترجمة لا يُعاد تعريفها من ملف الترجمة الأصلي للحزمة.

مصادر

صفحة Localization في توثيق Laravel الرسمي.