الفرق بين المراجعتين لصفحة: «Laravel/localization»
رؤيا-بنعطية (نقاش | مساهمات) لا ملخص تعديل |
رؤيا-بنعطية (نقاش | مساهمات) ط استبدال النص - '\[\[تصنيف:(.*)\]\]' ب'{{SUBPAGENAME}}' |
||
| (13 مراجعة متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة) | |||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:التوطين في Laravel}}</noinclude> | <noinclude>{{DISPLAYTITLE:التوطين في Laravel}}</noinclude> | ||
== مقدمة == | |||
تُقدِّم خاصيّة التوطين في Laravel طريقةً مريحةً وسهلةً لإعطاء ترجمات للكلمة في عدّة لغات، ممّا يسمح للتطبيق بدعم لغات متعدّدة. تُحفظ سلاسل المحارف الخاصّة بكل لغة يدعمها التطبيق في المجلد resources/lang. يحتوي هذا الملف على مجلدٍ فرعي لكل | تُقدِّم خاصيّة التوطين في [[Laravel]] طريقةً مريحةً وسهلةً لإعطاء ترجمات للكلمة في عدّة لغات، ممّا يسمح للتطبيق بدعم لغات متعدّدة. تُحفظ سلاسل المحارف الخاصّة بكل لغة يدعمها التطبيق في المجلد <code>resources/lang</code>. يحتوي هذا الملف على مجلدٍ فرعي لكل لغة يدعمها التطبيق:<syntaxhighlight lang="text"> | ||
/resources | |||
/lang | |||
/en | |||
messages.php | |||
/es | |||
messages.php | |||
</syntaxhighlight>تتمثل القيمة المعادة لكل ملف لغة في مصفوفة لسلاسل المحارف مرفقةً بمفاتيح:<syntaxhighlight lang="php"> | |||
<?php | |||
return [ | |||
'welcome' => 'Welcome to our application' | |||
]; | |||
</syntaxhighlight> | |||
=== ضبط المحليّة === | |||
تُحفظ اللغة الأولى للتطبيق في ملف الضبط <code>config/app.php</code>. يمكن بالطبع تغيير اللغة الأولى لتتناسب مع ما يحتاجه التطبيق. يمكن أيضا تغيير اللغة النشيطة للتطبيق في زمن التشغيل باستعمال التابع <code>setLocale</code> من [[Laravel/facades|الواجهة الساكنة]] App.<syntaxhighlight lang="php"> | |||
Route::get('welcome/{locale}', function ($locale) { | |||
App::setLocale($locale); | |||
// | |||
}); | |||
</syntaxhighlight> | |||
=== تحديد المحليّة الحالية === | |||
يُستعمَل التابعان <code>getLocale</code> و <code>isLocale</code> من الواجهة App لتحديد ما هي المحليّة (locale) أو التحقق أنها تساوي قيمةً معطاة:<syntaxhighlight lang="php"> | |||
$locale = App::getLocale(); | |||
if (App::isLocale('en')) { | |||
// | |||
} | |||
</syntaxhighlight> | |||
== تعريف سلاسل الترجمة == | |||
=== استعمال مفاتيح قصيرة === | |||
في العادة، تُحفظ سلاسل الترجمة في ملفّات في المجلد <code>resources/lang</code>. وفيه مجلدٌ فرعي لكل لغة مدعومة من التطبيق:<syntaxhighlight lang="text"> | |||
/resources | |||
/lang | |||
/en | |||
messages.php | |||
/es | |||
messages.php | |||
</syntaxhighlight> | |||
تتمثل القيمة المعادة لكل ملف لغة في مصفوفة لسلاسل نصية مرفقةً بمفاتيح:<syntaxhighlight lang="php"> | |||
<?php | |||
// resources/lang/en/messages.php | |||
return | |||
'welcome' => 'Welcome to our application' | |||
]; | |||
</syntaxhighlight> | |||
=== استعمال سلاسل الترجمة كمفاتيح === | |||
إنّ استعمال مفاتيح قصيرة في تطبيقات تتطلب الكثير من الترجمة يصبح مربكًا عند استعمالها في الواجهات (views). لهذا السبب يوفّر [[Laravel]] دعمًا لتعريف سلاسل ترجمة باستعمال سلسلة الترجمة الأصلية كمفتاح. | |||
تُحفظ ملفات الترجمة التي تستعمل سلاسل الترجمة كمفاتيح على شكل ملفّات JSON في المجلد <code>resources/lang</code>. مثلا، إن أردت ترجمة إسبانية يجب أن تصنع الملف <code>resources/lang/es.json</code><syntaxhighlight lang="php"> | |||
{ | |||
تُحفظ | |||
"I love programming.": "Me encanta programar." | |||
} | } | ||
</syntaxhighlight> | |||
استرجاع سلاسل الترجمة | == استرجاع سلاسل الترجمة == | ||
تُسترجع سطور من ملفات اللغة باستعمال دالة المساعدة <code>__</code> .تقبل الدالة <code>__</code> اسم الملف و المفتاح كمعامل أول. على سبيل المثال، لنبحث عن ترجمة السلسلة welcome في ملف اللغة <syntaxhighlight lang="php"> | |||
تُسترجع سطور من ملفات اللغة باستعمال دالة المساعدة __ .تقبل الدالة __ اسم الملف و المفتاح كمعامل أول. على سبيل المثال، لنبحث عن ترجمة السلسلة welcome في ملف اللغة resources/lang/messages.php | resources/lang/messages.php | ||
echo __('messages.welcome'); | echo __('messages.welcome'); | ||
echo __('I love programming.'); | echo __('I love programming.'); | ||
</syntaxhighlight> | |||
بالطبع إن كنت تستعمل محرك القولبة [[Laravel/blade|Blade]]<nowiki> يمكنك استعمال {{ }} لعرض سلسلة الترجمة أو استعمال التعليمة </nowiki><code>lang@</code>:<syntaxhighlight lang="php"> | |||
{{ __('messages.welcome') }} | |||
@lang('messages.welcome') | |||
</syntaxhighlight> | |||
إن كانت سلسلة الترجمة غير موجودة، فستعيد الدالة __ مفتاح الترجمة. لذا في المثال السابق، إن كانت سلسلة الترجمة غير موجودة،فستعيد الدالة __ النتيجة messages.welcome. | إن كانت سلسلة الترجمة غير موجودة، فستعيد الدالة <code>__</code> مفتاح الترجمة. لذا في المثال السابق، إن كانت سلسلة الترجمة غير موجودة،فستعيد الدالة <code>__</code> النتيجة messages.welcome. | ||
تعويض المعاملات في سلاسل الترجمة | === تعويض المعاملات في سلاسل الترجمة === | ||
إن أردت، بإمكانك تعريف نص بديل (place-holder) في سلسلة الترجمة. يُسبق كل نص بديل بالرمز :. مثلًا يمكن تعريف نص بديل لاسم في رسالة الترحيب:<syntaxhighlight lang="php"> | |||
إن أردت، بإمكانك تعريف نص بديل (place-holder) في سلسلة الترجمة. يُسبق كل نص بديل بالرمز :. مثلًا يمكن تعريف نص بديل لاسم في رسالة الترحيب: | 'welcome' => 'Welcome, :name', | ||
</syntaxhighlight> | |||
'welcome' => 'Welcome, :name', | |||
لتعويض النص البديل عند عادة سلسلة الترجمة، أدخل مصفوفة للبدائل كمعامل ثاني للدالة <code>__</code>:<syntaxhighlight lang="php"> | |||
echo __('messages.welcome', ['name' => 'dayle']); | echo __('messages.welcome', ['name' => 'dayle']); | ||
</syntaxhighlight> | |||
إن كان النص البديل مكتوبًا بحروف كبيرة، أو إن كان الحرف الأول فقط كبيرا فإن الصيغة المحوَّلة ستُكتب بنفس الطريقة: | إن كان النص البديل مكتوبًا بحروف كبيرة، أو إن كان الحرف الأول فقط كبيرا فإن الصيغة المحوَّلة ستُكتب بنفس الطريقة:<syntaxhighlight lang="php"> | ||
'welcome' => 'Welcome, :NAME', // Welcome, DAYLE | |||
'welcome' => 'Welcome, :NAME', // Welcome, DAYLE | 'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle | ||
</syntaxhighlight> | |||
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle | |||
=== الجمع === | |||
الجمع مشكلة معقّدة إذ تملك كل لغة العديد من القواعد المعقّدة للقيام بالجمع. نُفرّق بين الصيغة الفردية و صيغة الجمع للسلسلة باستخدام رمز "خط عمودي":<syntaxhighlight lang="php"> | |||
'apples' => 'There is one apple|There are many apples', | 'apples' => 'There is one apple|There are many apples', | ||
</syntaxhighlight> | |||
يمكن أيضا تعريف صيغ جمع أكثر تعقيدًا بتعريف صيغة جمع لكل نطاق أو مجال: | يمكن أيضا تعريف صيغ جمع أكثر تعقيدًا بتعريف صيغة جمع لكل نطاق أو مجال:<syntaxhighlight lang="php"> | ||
'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many', | 'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many', | ||
</syntaxhighlight> | |||
بعد تعريف سلسلة ترجمة بعدّة صيغ جمع، تُستعمل الدالة trans_choice لاسترجاع سطر الترجمة بعدد معيّن. في المثال التالي، لأن العدد أكبر من واحد، صيغة الجمع هي التي تُعاد: | بعد تعريف سلسلة ترجمة بعدّة صيغ جمع، تُستعمل الدالة <code>trans_choice</code> لاسترجاع سطر الترجمة بعدد معيّن. في المثال التالي، لأن العدد أكبر من واحد، صيغة الجمع هي التي تُعاد:<syntaxhighlight lang="php"> | ||
echo trans_choice('messages.apples', 10); | echo trans_choice('messages.apples', 10); | ||
</syntaxhighlight> | |||
يمكن أيضًا تعريف نص بديل لسلاسل ترجمة في صيغة الجمع. تعوَّض النصوص البديلة تلك بتمرير مصفوفة كمعامل ثالث للدالة trans_choice: | يمكن أيضًا تعريف نص بديل لسلاسل ترجمة في صيغة الجمع. تعوَّض النصوص البديلة تلك بتمرير مصفوفة كمعامل ثالث للدالة <code>trans_choice</code>:<syntaxhighlight lang="php"> | ||
'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago', | |||
'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago', | |||
echo trans_choice('time.minutes_ago', 5, ['value' => 5]); | echo trans_choice('time.minutes_ago', 5, ['value' => 5]); | ||
</syntaxhighlight> | |||
تجاوز حزم اللغات | == تجاوز حزم اللغات == | ||
قد تُشحن بعض الحزم بملفات لغاتها الخاصّة. بدل تغيير ملفات الحزمة لتعديل بعض هذه الترجمات، يمكن تجاوزها بصنع ملفات ترجمتك الخاصّة في الملف <code>{resources/lang/vendor/{package}/{locale</code>. على سبيل المثال، إن أردت تجاوز سلاسل الترجمة الإنجليزية في <code>messages.php</code> من الحزمة <code>skyrim/hearthfire</code>، يجب عليك وضع ملفات الترجمة الجديدة في <code>resources/lang/vendor/hearthfire/en/messages.php</code>. في هذا الملف، يجب تعريف سلاسل الترجمة التي تريد تجاوزها وإعادة تعريفها فقط. تُحمَّل كل سلسلة ترجمة لا يُعاد تعريفها من ملف الترجمة الأصلي للحزمة. | |||
قد تُشحن بعض الحزم بملفات لغاتها الخاصّة. بدل تغيير ملفات الحزمة لتعديل بعض هذه الترجمات، يمكن تجاوزها بصنع ملفات ترجمتك الخاصّة في الملف | == مصادر == | ||
* [https://laravel.com/docs/5.6/localization صفحة Localization في توثيق Laravel الرسمي.] | |||
resources/lang/vendor/{package}/{locale | [[تصنيف:Laravel|{{SUBPAGENAME}}]] | ||
[[تصنيف:Laravel Frontend|{{SUBPAGENAME}}]] | |||
على سبيل المثال، إن أردت تجاوز سلاسل الترجمة الإنجليزية في messages.php من الحزمة skyrim/ | |||
resources/lang/vendor/hearthfire/en/messages.php. | |||
في هذا الملف، يجب تعريف سلاسل الترجمة التي تريد تجاوزها وإعادة تعريفها فقط. تُحمَّل كل سلسلة ترجمة لا يُعاد تعريفها من ملف الترجمة الأصلي للحزمة. | |||
مصادر | |||
صفحة Localization في توثيق Laravel الرسمي. | |||
المراجعة الحالية بتاريخ 13:22، 23 أكتوبر 2018
مقدمة
تُقدِّم خاصيّة التوطين في 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. في هذا الملف، يجب تعريف سلاسل الترجمة التي تريد تجاوزها وإعادة تعريفها فقط. تُحمَّل كل سلسلة ترجمة لا يُعاد تعريفها من ملف الترجمة الأصلي للحزمة.