محلی‌سازی

مجتبی پاکزاد لاراول 5.6.29 در حال تکمیل رایگان

مقدمه

فیچرهای محلی‌سازی لاراول، روش مناسبی برای بازآوری (retrieve) استرینگ‌ها در زبان‌های مختلف را ارائه می‌دهند که به شما این امکان را می‌دهد تا به راحتی از چندین زبان در اپلیکیشن خود پشتیبانی کنید. استرینگ‌های زبان در فایل‌هایی در دایرکتوری 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);

    //
});

می‌توانید یک زبان جایگزین را کانفیگ کنید که زمانی که زبان فعال، فاقد استرینگ ترجمه مشخصی باشد، از آن استفاده می‌شود. مشابه زبان پیش‌فرض، زبان جایگزین نیز در فایل config/app.php کانفیگ می‌شود.

'fallback_locale' => 'en',

مشخص کردن زبان فعلی

از متدهای getLocale و isLocale در فساد App می‌توانید برای مشخص کردن زبان جاری یا بررسی اینکه آیا زبان مورد نظر شما سِت شده است، استفاده کنید.

$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'
];

استفاده از استرینگ‌های ترجمه در نقش کلید

برای اپلیکیشن‌هایی که نیاز به ترجمه سنگین دارند، تعریف هر استرینگ با یک کلید کوتاه، در هنگام رفرنس به آن‌ها در فایل‌های ویو، می‌تواند کمی گیج کننده به نظر آید. به همین دلیل، لاراول از تعریف استرینگ‌های ترجمه با استفاده از ترجمه پیش‌فرض استرینگ‌ها به عنوان کلید، نیز پشتیبانی می‌کند.

فایل‌های ترجمه که از استرینگ‌های زبان به عنوان کلید استفاده می‌کنند، به شکل فایل‌های 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 message را با پلیس‌هولدر name می‌توانید به شکل زیر تعریف کنید:

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

برای جایگذاری پلیس‌هولدرها هنگام دریافت استرینگ ترجمه، مقادیری که می‌خواهید در استرینگ ترجمه با پلیس‌هولدرها جایگزین شوند را به شکل یک آرایه به آرگومان دوم فانکشن __ پاس دهید:

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

اگر پلیس‌هولدر تماما به شکل حروف بزرگ باشد، یا به شکل کپیتال (اولین حرف بزرگ) باشد، مقدار ترجمه شده نیز به همان شکل نوشته می‌شود:

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

جمع بستن

پلورالیزاسیون (Pluralization) یا جمع بستن، موضع پیچیده‌ای است، زیرا زبان‌های مختلف، قوانین پیچیده گوناگونی برای جمع بستن دارند. با استفاده از کاراکتر پایپ (|)، می‌توانید شکل‌های مفرد و جمع استرینگ را مشخص کنید:

'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