مرحله ۴: افزودن پشتیبانی زبان

مقدمه

تا این مرحله، تمام متن‌های مرتبط با ماژول ما به زبان انگلیسی بودند. در این مرحله تنظیماتی انجام می‌دهیم که ماژول بتواند چندزبانگی را پشتیبانی کند، به گونه‌ای که:

- یک مدیر سایت بتواند توضیحات ماژول را به زبان موردنظر خود مشاهده کند.

- بازدیدکننده سایت بتواند خروجی ماژول را با «Hello» به زبان خودش ببیند.

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

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

کد منبع این مرحله در mod_hello مرحله ۴ موجود است

https://github.com/joomla/manual-examples/tree/main/module-tutorial/step4_languages

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

ماژول mod_hello ما سه محل دارد که متنی نمایش داده می‌شود:

1. نام ماژول که در عنصر `<name>` فایل Manifest تعریف شده است.

2. توضیح ماژول که در عنصر `<description>` فایل Manifest قرار دارد.

3. سلام ("Hello") که توسط ماژول روی صفحه سایت نمایش داده می‌شود.

برای این متن‌ها سه ثابت زبان (language constants) تعریف می‌کنیم: 

`MOD_HELLO_NAME`، `MOD_HELLO_DESCRIPTION` و `MOD_HELLO_GREETING`

تمامی ثابت‌های زبان باید با نام یکتای افزونه (extension) شروع شوند تا با افزونه‌های دیگر تداخل نداشته باشند. معمولاً این ثابت‌ها با حروف بزرگ نوشته می‌شوند.

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

mod_hello/language/en-GB/mod_hello.sys.ini

; رشته‌های زبان mod_hello برای نمایش در فهرست ماژول‌ها در پنل مدیریت
MOD_HELLO_NAME="Joomla Module Tutorial"
MOD_HELLO_DESCRIPTION="Source code for the Joomla module tutorial"

mod_hello/language/en-GB/mod_hello.ini

; رشته‌های زبانی که داخل mod_hello استفاده می‌شوند
MOD_HELLO_NAME="Joomla Module Tutorial"
MOD_HELLO_DESCRIPTION="Source code for the Joomla module tutorial"
MOD_HELLO_GREETING="Hello "

- فایل `.sys.ini` برای متونی است که در فرم‌های HTML نمایش چند ماژول ظاهر می‌شوند؛ مثلاً در پنل مدیریت در مسیر **System / Manage / Extensions** که فهرست افزونه‌ها نشان داده می‌شود:

  - نام افزونه در فیلد Name (که در `<name>` فایل manifest است)

  - توضیح افزونه به عنوان توضیح نشان‌داده‌شده هنگام قرار گرفتن نشانگر روی نام افزونه (tooltip) (که در `<description>` فایل manifest است).

- فایل `.ini` برای زمانی که ماژول به صورت مجزا نمایش داده می‌شود.

نام و توضیح (name and description) باید هم در `.ini` و هم در `.sys.ini` ذکر شوند چون جوملا هنگام انتخاب Content / Site Modules و ویرایش ماژول `mod_hello` فقط `.ini` را می‌خواند (چون این فقط یک ماژول است).

این تقسیم‌بندی برای بهبود کارایی است تا تعداد ثابتی که باید خوانده شوند کمتر شود.

به‌روزرسانی فایل Manifest

متن انگلیسی در فایل manifest را با نام‌های ثابت زبان جایگزین می‌کنیم و به نصب‌کننده جوملا اطلاع می‌دهیم که کجا می‌تواند فایل‌های زبان را پیدا کند.

همان طور که در بخش زبان‌های فایل manifest توضیح داده شده، دو روش برای افزودن فایل زبان وجود دارد؛ ما روش دوم را انتخاب کرده‌ایم.

mod_hello/mod_hello.xml

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" client="site" method="upgrade">
    <name>MOD_HELLO_NAME</name>
    <version>1.0.4</version>
    <author>me</author>
    <creationDate>today</creationDate>
    <description>MOD_HELLO_DESCRIPTION</description>
    <namespace path="src">My\Module\Hello</namespace>
    <files>
        <folder module="mod_hello">services</folder>
        <folder>src</folder>
        <folder>tmpl</folder>
        <folder>language</folder>
    </files>
</extension>

تفسیر ثابت های زبانی

برای دستیابی به متن مرتبط با یک ثابت زبان، کد منبع باید دو کار انجام دهد:

1. بارگذاری فایل زبان مناسب (.ini یا .sys.ini) 

2. دریافت متن مرتبط با یک ثابت زبان خاص

می‌توانیم فایل زبان ini را در ماژول خود با کد زیر بارگذاری کنیم:

use Joomla\CMS\Factory;
$language = Factory::getApplication()->getLanguage();
$language->load('mod_hello', JPATH_BASE . '/modules/mod_hello');

متن مرتبط با یک ثابت زبان خاص را با استفاده از کد زیر به دست می‌آوریم:

use Joomla\CMS\Language\Text;
...
$text = Text::_('MOD_HELLO_GREETING');

نگران نام تابع که فقط یک آندرلاین (_) است نباشید — این یک تابع معمولی PHP است.

این خطوط را در کد Dispatcher خود اضافه خواهیم کرد.

در فرم‌های مدیریت، جوملا خودش بارگذاری زبان و تفسیر ثوابت زبان را انجام می‌دهد، برای مثال هنگام ویرایش ماژول از طریق مسیر Content / Site Modules.

فایل به‌روزشده ی اصلی کد منبع Dispatcher ما اکنون به صورت زیر است: 

`mod_hello/src/Dispatcher/Dispatcher.php`

<?php
namespace My\Module\Hello\Site\Dispatcher;
\defined('_JEXEC') or die;
use Joomla\CMS\Dispatcher\DispatcherInterface;
use Joomla\CMS\Helper\ModuleHelper;
use Joomla\CMS\Factory;
use Joomla\CMS\Language\Text;
use My\Module\Hello\Site\Helper\HelloHelper;
class Dispatcher implements DispatcherInterface
{
    public function dispatch()
    {
        $language = Factory::getApplication()->getLanguage();
        $language->load('mod_hello', JPATH_BASE . '/modules/mod_hello');
       $username = HelloHelper::getLoggedonUsername('Guest');
        $hello = Text::_('MOD_HELLO_GREETING') . $username;
        require ModuleHelper::getLayoutPath('mod_hello');
    }
}

نصب، نکات و رفع خطا

دوباره پوشه `mod_hello` خود را فشرده (zip) کنید و ماژول به‌روزشده را روی جوملا نصب نمایید.

متن رشته‌های زبانی در فایل `.sys.ini` کمی متفاوت از مراحل قبل است، پس باید بتوانید این تفاوت‌ها را پس از نصب افزونه و هنگام مراجعه به مسیر Administrator / System / Manage / Extensions مشاهده کنید.

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

یک نکته مفید این است که به مسیر System / Global Configuration / System رفته، گزینه Debug Language را به Yes تغییر دهید و سپس ذخیره کنید.

این کار باعث می‌شود رشته‌های زبانی بین دو ستاره (*) برجسته شود. با تغییر گزینه Language Display که ظاهر می‌شود، می‌توانید جوملا را طوری تنظیم کنید که ثابت زبان یا متن مربوطه را نمایش دهد.

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