اصول localization

اصول آموزش Laravel

تاریخ : جمعه 27 بهمن 1396

امکان localization در فریم ورک Laravel به شما این اجازه را می دهد تا رشته ها را به زبان های مختلف در اپلیکیشن خود ترجمه و بازیابی کنید.

متغیرهای رشته ای language داخل فایل هایی در پوشه ی resources/lang ذخیره می شود. در این پوشه بایستی به ازای هر زبان که اپلیکیشن پشتیبانی می کند، یک subdirectory وجود داشته باشد:

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

تمامی فایل های language صرفا یک آرایه از رشته های با کلید (keyed strings) را به عنوان خروجی برمی گردانند. مثال:

<?php

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


تنظیم زبان جاری (locale)

زبان پیش فرض اپلیکیشن داخل فایل تنظیمات config/app.php ذخیره می شود. البته شما می توانید این مقدار را مطابق نیازهای اپلیکیشن خود ویرایش نمایید. همچنین می توانید با فراخوانی متد setLocale در App facade زبان فعلی برنامه را در زمان اجرا (runtime) تغییر دهید:

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

    //
});

همچنین می توانید یک زبان جایگزین (fallback) تنظیم کنید. این زبان جایگزین زمانی بکار می رود که زبان فعلی دربردارنده ی رشته مورد نظر نباشد. زبان جایگزین نیز مانند زبان فعلی برنامه در فایل تنظیمات config/app.php قابل دسترسی و تنظیم می باشد:

'fallback_locale' => 'en',


تعیین محل فعلی

می توانید با استفاده از متدهای getLocale و isLocale مرتبط با فاساد App، مکان فعلی تنظیم شده را بررسی نمایید :

$locale = App::getLocale();

if (App::isLocale('en')) {
    //
}


Defining Translation Strings


Using Short Keys

به طور معمول، رشته های ترجمه در فایل ها در دایرکتوری resources / lang ذخیره می شوند. در این فهرست باید یک زیرپوشه برای هر زبان پشتیبانی شده توسط برنامه وجود داشته باشد:

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

تمام فایل های زبان یک آرایه از رشته های کلید می گیرند. مثلا:

<?php

// resources/lang/en/messages.php

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


Using Translation Strings As Keys

برای برنامه های با نیازهای ترجمه سنگین، تعریف هر رشته با "کلید کوتاه" می تواند به سرعت در هنگام اشاره به آنها در نظرات شما گیج کننده باشد. به همین دلیل، Laravel همچنین پشتیبانی از تعریف رشته های ترجمه را با استفاده از «پیش فرض» ترجمه رشته به عنوان کلید ارائه می دهد.

فایل های ترجمه که از رشته های ترجمه به عنوان کلید استفاده می کنند، به عنوان فایل های JSON در دایرکتوری resource / lang ذخیره می شوند. به عنوان مثال، اگر درخواست شما یک ترجمه اسپانیایی باشد، باید یک فایل resource / lang / es.json ایجاد کنید:

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


Retrieving Translation Strings

می توانید با بهره گیری از تابع کمکی __ رشته هایی را از فایل های language بازیابی کنید. متد __ فایل و کلید مربوط به رشته ی زبان مورد نظر را به عنوان آرگوامان اول می پذیرد. در زیر با فراخوانی تابع مذکور رشته ی welcome را از فایل مربوط به زبانresources/lang/messages.php خوانده و بازیابی می کنیم.

echo __('messages.welcome');

echo __('I love programming.');

البته در صورتی که از موتور تولید قالب Blade استفاده می کنید، می توانید از سینتکس{{ }} برای چاپ {{ }}مورد نظر به زبان معین استفاده نمایید:

{{ __('messages.welcome') }}

@lang('messages.welcome')

در صورتی که رشته ی مورد نظر در فایل language وجود نداشت، تابع trans کلید آن رشته را برمی گرداند. حال با توجه به مثال قبلی می توان نتیجه گرفت که در صورت عدم وجود رشته ی مورد نظر تابع نام برده messages.welcome را به عنوان خروجی برمی گرداند.


جایگزین کردن پارامترها در رشته های زبان

placeholder ها (مکان نگهدارها) ابزاری کارامدی هستند که می توانید در رشته های متنی زبان خود نیز از آن ها استفاده کنید. برای درجplaceholder کافی است ابتدا کاراکتر دو نقطه و سپس اسم مکان نگهدار دلخواه را مشخص نمایید. در زیر با استفاده از placeholder ای به نامname یک پیغام خوش آمدگویی نمایش می دهیم:

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

به منظور جایگذاری مقدار مورد نظر در مکان نگهدار تعریف شده، در زمان بازیابی خط زبان (رشته ی متنی زبان)، آرایه ای از مقادیر جایگزین را به عنوان آرگومان دوم به تابع __ ارسال نمایید:

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

اگر دارنده مکان شما حاوی تمام حروف بزرگ است، یا فقط اولین حرف خود را با حروف بزرگ می نویسد، ارزش ترجمه شده به ترتیب به ترتیب سرمایه گذاری می شود:

'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle


Pluralization

از آنجایی که هر زبانی قواعد خاص خود را برای جمع بندی دارد، pluralizationمشکل پیچیده ای را در چند زبانه کردن اپلیکیشن به وجود آورده است. با بهره گیری از کاراکتر " | " می توان فرم های جمع و مفرد یک رشته را از هم تمایز بخشید:

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

مترجم Laravel توسط کامپوننت ترجمه ی Symphony طراحی و پشتیبانی می شود، بنابراین می توانید قواعد پیچیده تری برای جمع بندی رشته ها تعریف کنید:

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

پس از آن می توانید به وسیله ی تابع trans choice رشته مورد نظر را با توجه به آرگومان دوم (تعداد کلمات مشخص شده) ترجمه و بازیابی کنید. در این مثال، از آنجایی که مقدار آرگومان دوم از 1 بزرگتر است، فرم جمع رشته برگردانده می شود:

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

You may also define place-holder attributes in pluralization strings. These place-holders may be replaced by passing an array as the third argument to the trans_choice function:

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

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


Overriding Package Language Files

برخی از پکیج ها همراه با فایل های language اختصاصی خود ارائه می شوند. بجای اینکه فایل های اصلی پکیج را هک کرده و اقدام به ویرایش خط ها و رشته های متنی زبان کنید، می توانید با قرار دادن فایل های خود در پوشه ی resources/lang/vendor/{package}/{locale} به طور کامل آن ها را بازنویسی یا به اصطلاح override نمایید.

برای مثال اگر بخواهید متن های زبان انگلیسی را در فایل messages.php پکیج ای به نام skyrim/hearthfire بازنویسی کنید، در آن صورت بایستی فایل language دلخواه را در آدرس resources/lang/vendor/hearthfire/en/messages.php جایگذاری نمایید. یادآور می شویم که در این فایل فقط می بایست آن دسته از رشته های متنی (خط های زبان) که می خواهید بازنویسی شوند را تعریف کنید. هر رشته ی متنی یا خط زبانی (language line) که بازنویسی نکنید، از فایل های language اصلی پکیج خوانده و لود می شوند.


منابع مورد مطالعه جهت جمع آوری این مطلب:
https://laravel.com/docs/5.6/localization
www.tahlildadeh.com/ArticleDetails/آموزش-Localization-در-لاراول


نظرات