چندزبانه

جوملا پشتیبانی قدرتمندی از چندین زبان فراهم می‌کند و به توسعه‌دهندگان اجازه می‌دهد افزونه‌هایی بسازند که به‌راحتی قابل ترجمه و استفاده در زبان‌های مختلف باشند.

چگونه جوملا از چند زبان پشتیبانی می‌کند

جوملا بین زبان‌های نصب‌شده (زبان‌هایی که هسته جوملا یا افزونه‌ها به آن‌ها ترجمه شده‌اند) و زبان‌های محتوا (زبان‌هایی که محتواهای سایت می‌توانند به آن‌ها نوشته شوند) تمایز قائل می‌شود.

این تمایز به مدیریت بهتر ترجمه‌ها کمک می‌کند.

ثابت‌های زبان

برای مدیریت ترجمه‌ها، جوملا از ثابت‌های زبان استفاده می‌کند. این ثابت‌ها در فایل‌های زبان (.ini و .sys.ini) تعریف شده‌اند و در سراسر کد استفاده می‌شوند.

با استفاده از این ثابت‌ها می‌توانید مطمئن شوید که افزونه‌های شما به‌راحتی قابل ترجمه هستند.

فایل‌های زبان

فایل‌های زبان، فایل‌های متنی ساده‌ای هستند که ثابت‌های زبان را به ترجمه‌های آن‌ها نگاشت می‌کنند. دو نوع اصلی فایل زبان وجود دارد:

- فایل‌های .ini: برای ترجمه‌های معمولی استفاده می‌شوند.

- فایل‌های .sys.ini: برای پیغام‌های نصب و سیستم و همچنین هر جایی که افزونه در بخش مدیریتی نمایش داده می‌شود (مثل لیست افزونه‌های نصب‌شده) مورد استفاده قرار می‌گیرند.

نمونه‌ای از یک فایل زبان (mod_example.ini) به این صورت است:

MOD_EXAMPLE_HELLO="سلام" 
MOD_EXAMPLE_GOODBYE="خداحافظ"

 

این فایل را در مسیر language/en-GB افزونه خود قرار دهید. اطلاعات بیشتر را می‌توانید در صفحه فایل‌های زبان بیابید.

پیاده‌سازی پشتیبانی چندزبانه در افزونه شما

محل ذخیره فایل‌های زبان

فایل‌های زبان در جوملا به صورت فایل‌های `.ini` ذخیره می‌شوند و بسته به نوع افزونه در مسیرهای مشخصی قرار می‌گیرند:

- کامپوننت‌ها: `language/en-GB/com_example.ini`

- ماژول‌ها: `language/en-GB/mod_example.ini`

- پلاگین‌ها: `language/en-GB/plg_example.ini`

- قالب‌ها: `language/en-GB/tpl_example.ini`

دایرکتوری‌های ریشه زبان

فایل‌های زبان می‌توانند در یکی از دو دایرکتوری ریشه زیر ذخیره شوند:

- فرانت‌اند (نمایش کاربران): `/language`

- مدیریت (بک‌اند): `/administrator/language`

چه زمانی از هر دایرکتوری استفاده کنیم

- از `/language`: برای فایل‌های زبان مرتبط با بخش فرانت‌اند سایت (مثلاً کامپوننت‌ها، ماژول‌ها یا قالب‌هایی که برای بازدیدکنندگان نمایش داده می‌شوند) استفاده کنید.

- از `/administrator/language`: برای فایل‌های زبان مرتبط با بخش مدیریت یا رابط مدیر سایت (مثلاً کامپوننت‌ها، ماژول‌ها یا پلاگین‌هایی که فقط توسط مدیران بکار گرفته می‌شوند) استفاده کنید.

با قرار دادن فایل‌های زبان در دایرکتوری مناسب، جوملا می‌تواند رشته‌های زبان را به درستی بسته به اینکه افزونه در فرانت‌اند یا بک‌اند استفاده می‌شود، بارگذاری کند.

فایل‌های زبان در کامپوننت‌ها

توجه: از نسخه ۴ و ۵ جوملا دیگر نیازی به اضافه کردن پیشوند زبان (مثل en-GB.) در نام فایل‌های زبان نیست.

ساختار فایل‌های زبان برای کامپوننت‌ها باید به شکل زیر باشد:

components

    com_example

        language

            en-GB

                com_example.ini          // رشته‌های زبان سایت (فرانت‌اند)

                com_example.sys.ini      // رشته‌های زبان سیستم (بک‌اند/مدیریت)

فایل‌های زبان در ماژول‌ها

modules

    mod_example

        language

            en-GB

                mod_example.ini          // رشته‌های زبان سایت (فرانت‌اند)

                mod_example.sys.ini      // رشته‌های زبان سیستم (بک‌اند/مدیریت)

افزودن فایل‌های زبان به فایل مانیفست

برای اطمینان از شناسایی فایل‌های زبان افزونه توسط جوملا، آنها را در فایل مانیفست افزونه خود وارد کنید:

<languages>
    <language tag="en-GB">language/en-GB/mod_example.ini</language>
    <language tag="en-GB">language/en-GB/mod_example.sys.ini</language>
</languages>

 برای اطلاعات بیشتر درباره فایل مانیفست می‌توانید به مرحله چهارم در آموزش توسعه ماژول مراجعه کنید.

البته، ترجمه بخش «استفاده از کلاس Text» برای ترجمه رشته‌ها در کد جوملا به صورت زیر است:

استفاده از کلاس Text

برای ترجمه رشته‌ها در کد خود، از کلاس مدیریت متن (Text) جوملا استفاده کنید. کلاس Text شامل شش متد استاتیک اصلی و یک متد کمکی است که می‌توانید از آن‌ها بهره ببرید.

نکته: کلیدی که به متدهای کلاس Text می‌دهید باید دقیقاً با کلید تعریف‌شده در فایل زبان مربوطه یا override زبان مطابقت داشته باشد.

مثال از تعریف‌ها در فایل زبان:

MOD_EXAMPLE_HELLO="سلام" 
MOD_EXAMPLE_GOODBYE="خداحافظ"

 

استفاده از متد Text::_

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

use Joomla\CMS\Language\Text;
// استفاده در کد PHP
echo Text::_("MOD_EXAMPLE_HELLO");    // خروجی: سلام

echo Text::_("MOD_EXAMPLE_GOODBYE");  // خروجی: خداحافظ

 

استفاده از Text::alt

این متد همانند Text::_ رشته زبان را در فایل زبان جاری جستجو می‌کند و نمایش می‌دهد. اما پارامتر دوم آن یعنی `$alt` تعیین می‌کند که ترجمه باید از کدام فایل منبع گرفته شود.

مثال:

در فایل زبان عمومی:

JALL="همه"

  در فایل زبان ماژول:

JALL="همه با هم"

 

کد استفاده:

use Joomla\CMS\Language\Text;
echo Text::alt('JALL', 'language'); // will generate a 'All' string in English but a "Toutes" string in French
echo Text::alt('JALL', 'module');   // will generate a 'All' string in English but a "Tous" string in French

 نکته: به طور پیش‌فرض، جوملا همیشه از فایل زبان همراه با افزونه استفاده می‌کند و امکان override ثابت‌های زبان عمومی نیز وجود دارد. اما اگر بخواهید در جایی از افزونه مقدار اصلی ثابت زبان عمومی (که override نشده) استفاده کنید، می‌توانید با استفاده از `Text::alt` این کار را انجام دهید.

استفاده از Text::plural

این متد به صورت خودکار بر اساس مقدار ارسال‌شده، شکل صحیح ترجمه جمع بندی شده را انتخاب و نمایش می‌دهد.

مثال در فایل قالب mod_example:

use Joomla\CMS\Language\Text;
echo Text::plural('MOD_EXAMPLE_N_ITEMS_FOUND', 2);

 

تعریف رشته‌های زبان در فایل MOD_EXAMPLE:

MOD_EXAMPLE_N_ITEMS_FOUND="%d مورد پیدا شد." 
MOD_EXAMPLE_N_ITEMS_FOUND_0="هیچ موردی پیدا نشد." 
MOD_EXAMPLE_N_ITEMS_FOUND_1="فقط یک مورد پیدا شد." 
MOD_EXAMPLE_N_ITEMS_FOUND_2="دو مورد پیدا شد."

 

نتیجه:

دو مورد پیدا شد.

برای توضیح بیشتر در مورد روش plural می‌توانید به مقاله مربوط به Plural مراجعه کنید.

استفاده از Text::sprintf

این متد ترکیبی از تابع `sprintf` در PHP و ترجمه‌هاست که اجازه می‌دهد متغیرها را در رشته‌های ترجمه‌شده قرار داده و آنها را فرمت کنید.

مثال رشته زبان با جایگذین (placeholder):

COM_EXAMPLE_MY_STRING="There's a lot of laundry in the %s."

 

استفاده و ارسال متغیر به ترجمه:

use Joomla\CMS\Language\Text;
echo Text::sprintf("COM_EXAMPLE_MY_STRING", "laundry basket");

 خروجی:

There's a lot of laundry in the laundry basket.

نکته مهم: اگر `sprintf` با تعداد پارامترهای کمتر از مقدار مورد انتظار فراخوانی شود، باعث خطای شدید (Fatal Error) در PHP می‌شود که توسط جوملا کنترل نمی‌شود.

 برای اطلاعات بیشتر به مستندات PHP مربوط به این تابع در لینک زیر مراجعه کنید

[sprintf](https://www.php.net/manual/en/function.sprintf.php)

استفاده از Text::printf

این متد مشابه `sprintf` است با این تفاوت که مستقیماً خروجی را چاپ می‌کند و نیازی به `echo` نیست.

مثال:

use Joomla\CMS\Language\Text;
Text::printf("COM_EXAMPLE_MY_STRING", "laundry basket");

 خروجی مشابه مثال قبل خواهد بود.

هشدار: مثل `sprintf`، استفاده از این متد با پارامترهای کمتر از حد لازم باعث خطای شدید PHP می‌شود که توسط جوملا کنترل نمی‌شود.

برای دیدن مراجعه جزئیات بیشتر به مستندات PHP در لینک زیر مراجعه کنید.

[printf](https://www.php.net/manual/en/function.printf.php)

استفاده از Text::script

این متد زمانی کاربرد دارد که بخواهید رشته‌های چندزبانه را به کدهای جاوااسکریپت سمت کلاینت منتقل کنید، مثلاً در فرانت‌اند.

موارد استفاده معمول:

- دیالوگ‌ها یا پنجره‌های پاپ‌آپ داینامیک که باید پیام‌های کاربری را به زبان مناسب نمایش دهند.

- پیام‌های اعتبارسنجی که در جاوااسکریپت تولید می‌شوند.

- هر کامپوننت یا تعامل سفارشی جاوااسکریپتی که به متن‌های بومی‌شده نیاز دارد.

مثال در فایل زبان:

COM_EXAMPLE_CONFIRM_DELETE="Are you sure you want to delete this item?"

 

ثبت رشته زبان برای استفاده در جاوااسکریپت:

use Joomla\CMS\Language\Text;
Text::script('COM_EXAMPLE_CONFIRM_DELETE');

 استفاده در کد جاوااسکریپت:

// Retrieve the registered string in JavaScript
const deleteConfirmText = Joomla.Text._('COM_EXAMPLE_CONFIRM_DELETE');
// Use it in a dialog
alert(deleteConfirmText); // Displays: "Are you sure you want to delete this item?"

نکته: فعلاً امکان استفاده مستقیم از متغیرها داخل ترجمه‌های جاوااسکریپتی مانند sprintf وجود ندارد، اما می‌توانید در رشته‌ها از placeholders استفاده کنید و سپس در جاوااسکریپت آنها را با مقادیر دلخواه جایگزین کنید.

استفاده از ابزار Text::getScriptStrings

متد `Text::getScriptStrings` در جوملا یک ابزار کاربردی است که به شما اجازه می‌دهد آرایه‌ای از تمام رشته‌های زبان ثبت شده برای جاوااسکریپت با استفاده از متد `Text::script` را دریافت کنید. هدف اصلی این متد، واکشی تمامی رشته‌هایی است که برای استفاده در جاوااسکریپت ثبت شده‌اند و دسترسی به آنها به صورت آرایه فراهم می‌شود.

مثال در فایل زبان

COM_EXAMPLE_CONFIRM_DELETE="آیا مطمئن هستید که می‌خواهید این مورد را حذف کنید؟" 
COM_EXAMPLE_SUCCESSFULLY_SAVED="مورد با موفقیت ذخیره شد." 
COM_EXAMPLE_ACTION_FAILED="عملیات ناموفق بود. لطفاً دوباره تلاش کنید."

 

ثبت چند رشته زبان

<?php
use Joomla\CMS\Language\Text;
Text::script('COM_EXAMPLE_CONFIRM_DELETE'); 
Text::script('COM_EXAMPLE_SUCCESSFULLY_SAVED'); 
Text::script('COM_EXAMPLE_ACTION_FAILED');
?>

 دریافت تمام رشته‌های ثبت شده برای اسکریپت

<?php
$registeredStrings = Text::getScriptStrings();
// نمایش آرایه برای اشکال‌زدایی یا پردازش دلخواه 
print_r($registeredStrings);
?>

 

خروجی نمونه

Array ( 
[COM_EXAMPLE_CONFIRM_DELETE] => "آیا مطمئن هستید که می‌خواهید این مورد را حذف کنید؟" 
[COM_EXAMPLE_SUCCESSFULLY_SAVED] => "مورد با موفقیت ذخیره شد." 
[COM_EXAMPLE_ACTION_FAILED] => "عملیات ناموفق بود. لطفاً دوباره تلاش کنید." 
)

فایل‌های زبان

این بخش استفاده از فایل‌های زبان برای افزونه‌ها را توضیح می‌دهد. فایل‌های تعریف زبان جوملا به فرمت ساده INI نوشته می‌شوند و باید با کدگذاری UTF-8 ذخیره شوند. خطوط خالی و خطوطی که با سمیکالن (;) شروع می‌شوند نادیده گرفته می‌شوند و سمیکالن می‌تواند برای نوشتن توضیح در فایل به کار رود. هر خط شامل یک جفت کلید-مقدار است که با علامت مساوی از هم جدا شده‌اند:

KEY="value"

 که در آن KEY رشته‌ای است برای ترجمه و value مقدار ترجمه شده است. برای مثال:

COM_EXAMPLE_ADDITIONAL_INFO_LABEL="Additional Information"

قراردادها و مشخصات کلیدهای زبان (ثابت‌ها)

کلید (KEY) باید فقط شامل کاراکترهای ASCII باشد. فقط باید شامل حروف بزرگ، اعداد، آندرلاین (_) و خط تیره (-) باشد، و باید با حرف بزرگ شروع شود. نقطه (.) به صورت رسمی مجاز است ولی به طور کامل پشتیبانی نمی‌شود. معمولاً جایگزین کردن فاصله‌های موجود در کلید با آندرلاین یک قرارداد است. همچنین باید از فاصله‌گذاری دور علامت مساوی (=) خودداری شود.

کلیدهای زبان باید همیشه یکتا باشند. برای اطمینان از این موضوع، ساختار زیر پیشنهاد می‌شود:

- نوع افزونه => COM (کامپوننت‌ها) / MOD (ماژول‌ها) / PLG (پلاگین‌ها)

- نام افزونه / کد کوتاه => EXAMPLE (نام افزونه نمونه)

- شناسایی عنصر (فیلد، دکمه، هدر، ...)

- نوع عنصر (برچسب / توضیحات / ...)

مثلاً اگر برای برچسب و توضیحات یک فیلد انتخاب رنگ فونت در کامپوننت نمونه بخواهیم کلید تعریف کنیم، چنین خواهد بود:

COM_EXAMPLE_FONT_COLOR_FIELD_LABEL="Font-Color"
COM_EXAMPLE_FONT_COLOR_FIELD_DESCRIPTION="Select the Font-Color for xy"

و برای برچسب دکمه در ماژول My News کلید می‌تواند به این شکل باشد:

MOD_MYNEWS_LEARN_MORE_BTN_LABEL="Learn more"

 توجه

توصیه و بهترین عمل این است که پیشوندهای MOD_XY، COM_XY یا PLG_XY را برای کلیدهای زبان استفاده کنید.

مشخصات مقدارهای زبان

مقدار باید همیشه در داخل کوتیشن‌های دوتایی (`"`) قرار بگیرد، همانطور که در مثال دیده می‌شود. هر کوتیشن دوتایی موجود در مقدار باید با بک‌اسلش (`\`) فرار داده شود. برای مثال، برای مقدار `<span class="red">Warning!</span>` که به کلید `WARNING_TEXT` نسبت داده می‌شود، می‌توان به این صورت نوشت:

رشته‌های زبان حاوی تگ‌های HTML با کوتیشن دوتایی فرار داده شده

WARNING_TEXT="<span class=\"red\">Warning!</span>"

یا با کوتیشن‌های تک:

WARNING_TEXT="<span class='red'>Warning!</span>"

 

توجه

این قوانین سخت‌تر از parser فایل INI در PHP است. برای مثال، parser می‌تواند کوتیشن را کنار بگذارد اگر مقدار کاراکتر خاصی نداشته باشد. خودداری از نادیده گرفتن کوتیشن‌ها کمک می‌کند از اشتباهات جلوگیری شود.

HTML در مقادیر زبان

استفاده از HTML در ترجمه‌ها توصیه نمی‌شود. ساختار HTML باید خارج از رشته‌های زبان و در جای مناسب قرار گیرد:

فایل زبان:

WARNING_TEXT="Warning!"

 فایل قالب PHP (محل استفاده:

<span class="red"><?php echo Text::_("WARNING_TEXT"); ?></span>

 

حساسیت به حروف هنگام استفاده از Text::

در فراخوانی Text:: حساسیت به حروف وجود ندارد چون کلیدها قبل از جستجو به حروف بزرگ تبدیل می‌شوند. مثلاً رشته‌های `additional_information`, `Additional_Information` یا حتی `AdDiTiOnAl_InFoRmAtIoN` همگی مطابقت داده می‌شوند. با این حال، نوشتن کلید به صورت حروف بزرگ یک قرارداد و بهترین عمل است.

برچسب‌های زبان

اگر فایل‌های زبان برای افزونه نوشته شوند باید در پوشه‌ای متناسب با برچسب زبان (language tag) در افزونه ذخیره شوند. جوملا در هنگام نصب/به‌روزرسانی، این فایل‌ها را به مسیرهای صحیح منتقل می‌کند.

ساختار پوشه‌ها به شکل زیر است: 

`languages / [languageTag] / *.ini` 

که برچسب‌های زبان مانند `"en-GB"`, `"fa-IR"`, `"de-AT"` براساس استانداردهای ISO 639-1 و ISO 3166-1 هستند. این برچسب‌ها ترکیبی از زبان و گویش منطقه‌ای یا کشوری را مشخص می‌کنند.

این برچسب‌ها شامل دو قسمتند: 

- قسمت اول: کد زبان (ISO 639-1)، مثلاً 

  - `en` برای انگلیسی 

  - `de` برای آلمانی 

  - `fr` برای فرانسوی 

  - `it` برای ایتالیایی 

- قسمت دوم: کد کشور (ISO 3166-1 Alpha 2)، مثلاً 

  - `GB` برای بریتانیا 

  - `US` برای آمریکا 

  - `CH` برای سوئیس 

  - `FR` برای فرانسه 

  - `AT` برای اتریش

خطاها در فایل‌های زبان

اگر در یک فایل زبان خطایی باشد، فایل به درستی پردازش نمی‌شود و ترجمه‌های جداگانه کنار گذاشته می‌شوند. در این حالت، بررسی فایل با ویرایشگری که هایلایت سینتکس برای INI دارد کمک‌کننده است.

 

کوتیشن دوتایی بدون فرار در مقدار

معمول‌ترین خطا وقتی رخ می‌دهد که مقدار در کوتیشن دوتایی قرار نگیرد یا کوتیشن دوتایی در مقدار فرار داده نشده باشد:

MOD_EXAMPLE_WORKING_HEADING="My Heading"
MOD_EXAMPLE_UNESCAPED_ERROR_MSG="<span class=\"error">Oh no an Error</span>"
MOD_EXAMPLE_NOT_WORKING_SUCCESS_MSG="Success!"

 

کمبود کوتیشن دوتایی در انتهای مقدار

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

MOD_EXAMPLE_WORKING_HEADING="My Heading"
MOD_EXAMPLE_UNESCAPED_ERROR_MSG="<span class=\"error\">Oh no an Error</span>
MOD_EXAMPLE_NOT_WORKING_SUCCESS_MSG="Success!"

 

مقدارهای چندخطی

مقدار چندخطی معتبر نیستند – فقط کلید-مقدارهای تک‌خطی مورد قبول هستند:

MOD_EXAMPLE_WORKING_HEADING="My Heading"

MOD_MOD_EXAMPLE_UNESCAPED_ERROR_MSG="<div class=\"error\">
<span>This will not work</span>
</div>"
MOD_EXAMPLE_NOT_WORKING_SUCCESS_MSG="Success!"

 

کلیدهای نامعتبر

اگر کلید زبان (ثابت) مطابق مشخصات نباشد، نمی‌توان از آن استفاده کرد:

MOD_EXAMPLE_WORKING_HEADING="My Heading"
MOD_EXAMPLE WHITESPACE_ERROR_MSG="This will not be translated"
MOD_EXAMPLE_WORKING_SUCCESS_MSG="Success!"

 

جمع‌بندی (Plural)

رشته‌های زبان جوملا از حالت مفرد و جمع پشتیبانی می‌کنند. مثال زیر نحوه استفاده از متد `Text::plural` را نشان می‌دهد، جایی که `$ids` یک آرایه از شناسه‌های عناصر است:

use Joomla\CMS\Language\Text;
echo Text::plural('MOD_EXAMPLE_N_ITEMS_FOUND', count($ids));

 

فایل زبان MOD_EXAMPLE

MOD_EXAMPLE_N_ITEMS_FOUND="%d items found."
MOD_EXAMPLE_N_ITEMS_FOUND_0="No items found."
MOD_EXAMPLE_N_ITEMS_FOUND_1="Only one item found."
MOD_EXAMPLE_N_ITEMS_FOUND_2="Two items found."

 

اگر آرایه `$ids` تنها یک عنصر داشته باشد، رشته زبان `MOD_EXAMPLE_N_ITEMS_FOUND_1` چاپ می‌شود، اگر دو عنصر باشد `MOD_EXAMPLE_N_ITEMS_FOUND_2` و اگر سه یا بیشتر باشد، `MOD_EXAMPLE_N_ITEMS_FOUND` مورد استفاده قرار می‌گیرد.

اطلاع

متد plural به صورت خودکار مناسب‌ترین کلید ترجمه را بر اساس عدد ورودی و کلیدهای موجود با پسوندهایی مانند `_1`, `_2`, ..., `_MORE, _OTHER` انتخاب می‌کند. اگر ورژن جمع‌بندی در فایل زبان نباشد، جوملا از کلید پایه (Base) استفاده می‌کند.

کلیدهای MORE و OTHER

علاوه بر مقادیر مشخص شده، متد `plural` می‌تواند از کلیدهای `MORE` یا `OTHER` نیز استفاده کند. در صورتی که هر دو تعریف شده باشند، کلید `OTHER` در اولویت قرار می‌گیرد.

مثال فایل زبان:

MOD_EXAMPLE_N_APPLES_MSG="Apples"
MOD_EXAMPLE_N_APPLES_MSG_5="There are exactly five apples"
MOD_EXAMPLE_N_APPLES_MSG_MORE="There are %d apples."
MOD_EXAMPLE_N_APPLES_MSG_OTHER="There are a lot of apples."

 

اگر متد با مقداری بزرگتر از ۵ فراخوانی شود:

use Joomla\CMS\Language\Text;
$n = 6; 
echo Text::plural("MOD_EXAMPLE_N_APPLES_MSG", $n);

 

نتیجه:

There are a lot of apples.

جوملا از ترجمه مربوط به کلید `OTHER` استفاده می‌کند. ترتیب قرارگیری کلیدهای `MORE` یا `OTHER` در فایل زبان تأثیری ندارد و همیشه `OTHER` در صورت وجود ترجیح داده می‌شود.

 اگر مقدار کمتر از مقادیر تعیین شده باشد (مثلاً ۳)، باز هم ترجمه `MOD_EXAMPLE_N_APPLES_MSG_OTHER` استفاده می‌شود. اما اگر کلید `OTHER` از فایل زبان حذف شود، جوملا از کلید `MORE` برای مقادیر جمع استفاده خواهد کرد.

مثال فایل زبان بدون تعریف `OTHER`:

MOD_EXAMPLE_N_APPLES_MSG="Apples"
MOD_EXAMPLE_N_APPLES_MSG_5="There are exactly five apples"
MOD_EXAMPLE_N_APPLES_MSG_MORE="There are %d apples."

 

فراخوانی متد با مقدار کوچکتر از ۵:

use Joomla\CMS\Language\Text;
$n = 3; echo Text::plural("MOD_EXAMPLE_N_APPLES_MSG", $n);

 

نتیجه:

There are 3 apples.

استفاده از متغیرها

گاهی اوقات لازم است در ترجمه‌ها از متغیرها یا متغیرهای قالب‌بندی شده به صورت خاص استفاده شود. این موضوع معمولاً هنگام کار با اعداد رخ می‌دهد، اما ممکن است برای تاریخ و زمان یا زمانی که فرمت دقیق نیاز است نیز کاربرد داشته باشد. اگر نیاز به ترجمه نبود، می‌توان از توابع استاندارد PHP مانند `printf` و `sprintf` استفاده کرد. تابع `printf` یک رشته قالب‌بندی شده را مستقیماً چاپ می‌کند و تابع `sprintf` همان رشته قالب‌بندی شده را برمی‌گرداند.

کلاس `Text` در جوملا متدهای کمکی (wrapper) برای `printf` و `sprintf` ارائه می‌دهد که امکان ترجمه متن ثابت را فراهم کرده و در عین حال اجازه می‌دهد متغیرهای قالب‌بندی شده با همان نحو PHP درج شوند. با استفاده از `Text::sprintf` می‌توانید از شناسه‌های قالب‌بندی مثل `%s` (برای رشته) در ترجمه استفاده کنید. شناسه‌های زیر قابل استفاده هستند:

متغیر تکی

رشته زبان شامل جایگزین متغیر:

COM_EXAMPLE_MY_STRING="The value of my transferred variable is %s and is included like this."

 فراخوانی ترجمه و انتقال متغیر:

use Joomla\CMS\Language\Text;
echo Text::sprintf("COM_EXAMPLE_MY_STRING", $someVariable);

 

مثال عملی دیگر در کامپوننت تماس:

فایل زبان COM_CONTACT:

COM_CONTACT_CHECKED_OUT_BY="Checked out by %s"

  

در PHP:

use Joomla\CMS\Language\Text;
echo Text::sprintf("COM_CONTACT_CHECKED_OUT_BY", $checkoutUser->name);

 

چند متغیر

چندین متغیر نیز می‌توانند به رشته زبان منتقل شوند؛ این متغیرها به ترتیب در موقعیت‌های تعریف شده در رشته زبان قرار می‌گیرند. ترتیب ارسال متغیرها اهمیت دارد و نباید تغییر کند.

فایل زبان MOD_EXAMPLE:

MOD_EXAMPLE_MULTIVAR_STRING="This string contains three placeholders: %s, %s, %s << They are placed in order"

 فایل قالب mod_example:

use Joomla\CMS\Language\Text;
$a = "First String"; $b = "Second String"; $c = "Third String";
echo Text::sprintf('MOD_EXAMPLE_MULTIVAR_STRING', $a, $b, $c);

 

رشته ترجمه شده

This string contains three placeholders: First String, Second String, Third String << They are placed in order

اگر جای `$a، $b` و `$c` در کد PHP جابجا شود، ترتیب قرارگیری آنها در رشته ترجمه شده هم تغییر می‌کند.

در ادامه ترجمه بخش مربوط به **تعیین محل قرارگیری متغیرها در رشته‌های ترجمه و نکات مرتبط با آرگومان‌ها** آمده است:

تعیین محل قرارگیری متغیرها در رشته ترجمه

ساختار جملات بسته به زبان‌ها اغلب متفاوت است. برای مثال جمله انگلیسی زیر:

There are 7 balls in the hat

ممکن است در زبان‌های دیگر ساختار کاملاً متفاوتی داشته باشد. حتی اگر ساختار زبان انگلیسی هم تغییر کند و جای متغیرها عوض شود، این کار باید در کد PHP انجام شود که پیچیده و غیرقابل مدیریت است.

جوملا راه حل شیک‌تری ارائه داده است.

توجه

برای ساده‌سازی جابجایی متغیرها در این مثال از `%s` استفاده شده، ولی توصیه می‌شود برای اعداد صحیح از `%d` استفاده شود.

مثال در قالب mod_example

use Joomla\CMS\Language\Text;
$number = 7; $location = "hat";
echo Text::sprintf('MOD_EXAMPLE_BALLS_IN_THE_BUCKET_MSG', $location, $number);

 

رشته ترجمه با متغیرها

MOD_EXAMPLE_BALLS_IN_THE_BUCKET_MSG="There are %s balls in the %s."

 

رشته ترجمه شده خروجی:

There are 7 balls in the hat.

اما اگر ترجمه به شکل دیگری تنظیم شود، جایگذاری متغیرها اشتباه خواهد بود:

رشته ترجمه مشکل‌دار:

MOD_EXAMPLE_BALLS_IN_THE_BUCKET_MSG="The %s contains %s balls."

رشته خروجی اشتباه:

The 7 contains hat balls.

این نتیجه کاملاً بی‌معنی است. به جای تغییر در کد PHP، می‌توانید در رشته ترجمه مشخص کنید که هر جایگاه متغیر به کدام آرگومان در فراخوانی مربوط است.

رشته ترجمه با نشانگر جایگاه آرگومان‌ها

MOD_EXAMPLE_BALLS_IN_THE_BUCKET_MSG="The %2$s contains %1$s balls."

 

در اینجا `%2$s ` به آرگومان دوم (یعنی مقدار `$location`) و `%1$s `به آرگومان اول (`$number`) اشاره دارد.

رشته ترجمه خروجی صحیح:

The hat contains 7 balls.

مزیت دیگر این روش این است که می‌توانید از متغیرها چند بار در رشته ترجمه استفاده کنید بدون آنکه لازم باشد چند بار در فراخوانی `sprintf` آنها را ارسال کنید:

MOD_EXAMPLE_BALLS_IN_THE_BUCKET_MSG="The %2$s contains %1$s balls, so there are %1$s balls in the %2$s."

 

رشته ترجمه با استفاده چندباره از متغیرها:

The hat contains 7 balls, so there are 7 balls in the hat.

تعداد آرگومان‌ها و متغیرهای نادرست

ارسال آرگومان بیش از حد

اگر متد `sprintf` با آرگومان‌های بیشتری نسبت به نیاز فراخوانی شود، آرگومان‌های اضافی نادیده گرفته می‌شوند.

توجه 

توابع `sprintf` و `printf` به طور کلی قادر به گرفتن آرگومان‌های اضافی هستند که این قابلیت می‌تواند برای ارسال گزینه‌ها (Options) استفاده شود.

ارسال آرگومان کمتر از حد

اگر متد `sprintf` با آرگومان‌های کمتری نسبت به نیاز فراخوانی شود، این باعث یک خطای جدی (fatal error) در PHP می‌شود که توسط جوملا گرفته نمی‌شود.

مثال: اگر یک رشته زبان انتظار دو متغیر داشته باشد ولی فقط یک متغیر ارسال شود، خطایی مانند زیر رخ می‌دهد.

تعریف رشته زبان با دو متغیر انتظار:

MOD_EXAMPLE_INV_ARGS_CRASH="Custom String awaits two variables: %s and %s."

 

فراخوانی با فقط یک متغیر:

use Joomla\CMS\Language\Text;
Text::sprintf("MOD_EXAMPLE_INV_ARGS_CRASH", 12);

 

نتیجه در سمت کاربر (مثلاً صفحه ۴۰۴):

خطای زیر نمایش داده می‌شود:

2 arguments are required, 1 given

 

در کد، Call Stack خطا مرتبط با رشته زبان و `sprintf` یا `printf` را نمایش می‌دهد.

استفاده از آرایه گزینه‌ها (Options Array)

آخرین آرگومان متد می‌تواند یک آرایه از گزینه‌ها باشد که شامل موارد زیر است:

- `jsSafe` (پیش‌فرض: `false`) 

  نوع داده: بولی (boolean) 

  مشخص می‌کند که آیا رشته تولید شده باید برای استفاده در جاوااسکریپت ایمن باشد یا خیر.

- `interpretBackSlashes` (پیش‌فرض: `true`) 

  نوع داده: بولی (boolean) 

  مشخص می‌کند آیا کاراکترهای فرار مانند `\n` (خط جدید)، `\t` (تب)، `\\` (بک‌اسلش) تفسیر شوند یا خیر.

- `script` (پیش‌فرض: `false`) 

  نوع داده: بولی (boolean) 

  نشان می‌دهد که آیا رشته به انبار زبان جاوااسکریپت (javascript language store) ارسال شود یا خیر.

ساختار آرایه گزینه‌ها:

array(
    'jsSafe' => boolean,          // ایمن‌سازی برای جاوااسکریپت
    'interpretBackSlashes' => boolean,  // تفسیر بک‌اسلش‌ها
    'script' => boolean           // ارسال به زبان جاوااسکریپت
)

 

تعیین‌کننده‌های قالب (Format Specifiers)

متد `Text::sprintf` در جوملا، یک پوشش (wrapper) برای متد `sprintf` در پی‌اچ‌پی است. اصولاً همه اطلاعات موجود در صفحه رسمی مستندات PHP را می‌توان برای استفاده از `sprintf` در جوملا نیز به کار برد. برای جزئیات بیشتر به [مستندات PHP sprintf] مراجعه کنید.

(https://www.php.net/manual/en/function.sprintf.php)

فهرست تعیین‌کننده‌های قالب

- `%b` آرگومان به عنوان عدد صحیح در مبنای دو (باینری) نمایش داده می‌شود.

- `%c` آرگومان به عنوان عدد صحیح گرفته شده و به کاراکتری با مقدار ASCII متناظر تبدیل می‌شود.

- `%d` آرگومان به عنوان عدد صحیح و عدد دهدهی علامت دار نمایش داده می‌شود.

- `%e` آرگومان به صورت نماد علمی (Scientific notation) نمایش داده می‌شود (مثلاً 1.2e+2).

- `%u` آرگومان به عنوان عدد صحیح و به صورت عدد دهدهی بدون علامت نمایش داده می‌شود.

- `%f` آرگومان به عنوان اعشاری (float) و به صورت عدد اعشاری نمایش داده می‌شود (با توجه به تنظیمات محلی).

- `%F` آرگومان به عنوان اعشاری و به صورت عدد اعشاری نمایش داده می‌شود (بدون توجه به تنظیمات محلی).

- `%o` آرگومان به عنوان عدد صحیح و به صورت عدد هشت‌تایی (octal) نمایش داده می‌شود.

- `%s` آرگومان به صورت رشته (string) نمایش داده می‌شود.

- `%x` آرگومان به عنوان عدد صحیح و به صورت عدد هگزا دسیمال با حروف کوچک نمایش داده می‌شود.

- `%X` آرگومان به عنوان عدد صحیح و به صورت عدد هگزا دسیمال با حروف بزرگ نمایش داده می‌شود.

نحوه نوشتاری دستورها (Syntax of Directives)

ترتیب	۱	۲	۳	۴	۵	۶
علامت	نشانه	تراز	پر کردن	عرض	دقت	نوع تعیین‌کننده

 

علامت (Sign)

- مقادیر ممکن: `+`

این علامت باعث می‌شود که در عدد مثبت نیز علامت + نمایش داده شود. به صورت پیش‌فرض فقط اعداد منفی علامت `-` دارند، اما این تعیین‌کننده باعث نمایش علامت مثبت `+` برای اعداد مثبت نیز می‌شود.

استفاده از علامت '+' (مثال)

MOD_EXAMPLE_POSITIVE_NEGATIVE_NUMBER="این عدد %+d است که چه مثبت باشد و چه منفی." 

use Joomla\CMS\Language\Text;
$positive_num = 42; $negative_num = -12;
echo Text::sprintf("MOD_EXAMPLE_POSITIVE_NEGATIVE_NUMBER", $positive_num); echo Text::sprintf("MOD_EXAMPLE_POSITIVE_NEGATIVE_NUMBER", $negative_num);

 

 نتیجه:

این عدد+42 است که چه مثبت باشد و چه منفی.

این عدد -12 است که چه مثبت باشد و چه منفی.

تراز (Alignment)

- مقادیر ممکن: `<null>` یا `-`

مشخص می‌کند که متن خروجی چپ‌چین یا راست‌چین باشد. به طور پیش‌فرض راست‌چین است. استفاده از `-` باعث می‌شود متن چپ‌چین شود.

نکته: علامت `+` برای نمایش علامت مثبت به کار می‌رود و علامت `-` برای چپ‌چین کردن، هر دو می‌توانند با هم استفاده شوند.

نمونه استفاده از `-` برای چپ‌چین

MOD_EXAMPLE_RIGHT_JUSTIFY="|%+6d|%+6d|"
MOD_EXAMPLE_LEFT_JUSTIFY="|%-6d|%-6d|"
MOD_EXAMPLE_FORCE_POSITIVE_LEFT_JUSTIFY="|%+-6d|%+-6d|"

use Joomla\CMS\Language\Text;
...
    <?php echo Text::sprintf("MOD_EXAMPLE_RIGHT_JUSTIFY", 42, -42); ?> <br>
    <?php echo Text::sprintf("MOD_EXAMPLE_LEFT_JUSTIFY", 42, -42); ?> <br>
    <?php echo Text::sprintf("MOD_EXAMPLE_FORCE_POSITIVE_LEFT_JUSTIFY", 42, -42); ?>

 

 خروجی:

|   +42|   -42|

|42    |-42   |

|+42   |-42   |

پر کردن (Padding)

- مقادیر ممکن: `<space>` یا `0` یا `'char`

کاراکتری که برای پر کردن فضای خالی (padding) به کار می‌رود. می‌تواند یک فضای خالی، صفر یا هر کاراکتر دلخواه باشد که با `'` مشخص می‌شود.

نمونه استفاده از Padding

MOD_EXAMPLE_PADDING_MSG = "عدد با padding: %'.9d"

 

وقتی عدد ۵۰۰ داده می‌شود و نقطه به عنوان کاراکتر پرکننده:

عدد با padding: ......500

 

استفاده از وضع دهی موقعیت (`position directive`)

MOD_EXAMPLE_PADDING_MSG = "عدد %1$d با padding: %1

 

وقتی عدد ۵۰۰ است و از دو نقطه به عنوان کاراکتر استفاده شود:

عدد 500 عدد 500 با padding: ::::::500
استفاده از فضای خالی (space)
به طور پیش‌فرض فضای خالی به عنوان padding استفاده می‌شود.
MOD_EXAMPLE_PADDING_MSG = "عدد با padding: %9d"

مثلاً برای عدد ۵۰۰، باید ۶ فضای خالی قبل از عدد باشد. در بیشتر مرورگرها این فاصله‌ها به یک فاصله تبدیل می‌شود، برای نمایش درست نیاز به CSS زیر است:

.padding-support {
white-space: pre-wrap;
}

نمونه کد PHP برای نمایش فاصله‌ها:

use Joomla\CMS\Language\Text;
$num = 500;
echo '' . Text::sprintf("MOD_EXAMPLE_PADDING_MSG", $num) . '';

 

خروجی:

عدد با padding: 500

⚠️ هشدار: تعیین‌کننده نوع `c` پر کردن و عرض را نادیده می‌گیرد.

در ادامه ترجمه بخش مربوط به «عرض (Width)» و «دقت (Precision)» متد `Text::sprintf` جوملا آمده است:

عرض (Width)

- مقادیر ممکن: عدد

تعداد حداقل کاراکترهایی که خروجی تبدیل باید داشته باشد. اگر عرض فیلد در placeholder تابع `sprintf` مشخص شود، خروجی تولید شده تا آن عرض حداقل پر می‌شود.

تنظیم عرض به ۱۰ کاراکتر

MOD_EXAMPLE_WIDTH_MSG = "[%10s]"

use Joomla\CMS\Language\Text;
...
<?php echo Text::sprintf("MOD_EXAMPLE_WIDTH_MSG", "Example"); ?>

 

نتیجه:

[  Example]

عرض را می‌توان با علامت تراز (Alignment Flag) ترکیب کرد:

تنظیم عرض ۱۰ کاراکتر با ترازبندی به سمت چپ

MOD_EXAMPLE_WIDTH_MSG = "[%-10s]"

 

 

نتیجه (چپ‌چین):

[Example ]

 

⚠️ هشدار: تعیین‌کننده نوع `c` مقدار padding و width را نادیده می‌گیرد.

دقت (Precision)

- مقادیر ممکن: `.<عدد>`

تعداد ارقام اعشاری که باید برای عددهای اعشاری نمایش داده شود. هنگام استفاده برای رشته‌ها، نقش برش (cutoff) را دارد و حداکثر طول رشته را محدود می‌کند.

MOD_EXAMPLE_PI_MSG = "عدد پی برابر است با: %.4f"

use Joomla\CMS\Language\Text;
$pi = 3.1415926536; 
echo Text::sprintf("MOD_EXAMPLE_PI_MSG", $pi);

 

 خروجی:

عدد پی برابر است با: 3.1416

منابع خارجی

- [مستندات PHP برای sprintf]

(https://www.php.net/manual/en/function.sprintf.php)