گام چهارم - افزودن فایل زبان به ماژول

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

جوملا ترجمه افزونه های خود را در فایل های متنی ساده با پسوند .ini نگهداری می کند. در فایل های زبان جوملا هر خط را یک رشته می نامند. در زیر تصویری از فایل زبان کامپوننت مطالب جوملا را می بینید. هر رشته از زوج ثابت/متغیر تشکیل شده است. بخش ثابت بصورت حروف انگلیسی بزرگ است و در بین کدهای PHP نیز نوشته می شود و همیشه برای هر متن، ثابت است، برای همین به آن ثابت می گویند و بخش متغیر داخل دبل کوتیشن و همان ترجمه متناظر با آن ثابت هست که در هر زبان با توجه به آن زبان فرق می کند، برای همین به آن متغیر می گویند.

نمونه فایل زبان جوملا

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

تاکنون هر متنی مرتبط با ماژول ما به زبان انگلیسی بوده است. در این مرحله ما این متون را تغییر می دهیم تا بتوانید ماژول خود را به زبانهای مختلف ترجمه کنید، این تغییر این امکان را می دهد که:

یک مدیر بتواند توضیحات ماژول را به زبان ترجیحی خود مشاهده کند.
یک بازدید کننده سایت بتواند خروجی ماژول را یعنی Hello را با معادل آن به زبان خود جایگزین کند.

همانطور که می دانید، برای مشاهده چندین زبان در سایت خود باید وبسایت را بصورت چند زبانه پیکربندی کنید. نحوه چند زبانه کردن وبسایت را در چند زبانه کردن جوملا - آموزش ساخت وب سایت چند زبانه در جوملا بطور کامل توضیح داده ایم.

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

فایل های زبان

ماژول mod_hello ما در 3 جا دارای خروجی متن است:

نام ماژول که در تگ <name> فایل مانیفست تنظیم شده است
توضیحات ماژول تنظیم شده در تگ <description> فایل
پیام خوشآمدگویی Hello ماژول در بخش کاربری

ما 3 ثابت زبان را برای این رشته های متن تعریف می کنیم: MOD_HELLO_NAME ، MOD_HELLO_DESCRIPTION و MOD_HELLO_GREETING.

تمام ثابت های زبان باید با نام منحصر به فرد افزونه (در این مثال چون نام افزونه mod_hello است با عبارت _MOD_HELLO ) شروع شوند ، زیرا این امر تضمین می کند که هیچ تداخلی با افزونه های دیگر وجود ندارد. طبق مستندات جوملا، تمام این متون بصورت کپیتال (حروف بزرگ) هستند.

ما مقادیر این ثابت ها را در 2 فایل زبانی تعریف می کنیم. اولی در مسیر mod_hello/language/en-GB/mod_hello.sys.ini

; mod_hello language strings for administrator listings of modules
MOD_HELLO_NAME="Joomla Module Tutorial"
MOD_HELLO_DESCRIPTION="Source code for the Joomla module tutorial"

و دومی در مسیر mod_hello/language/en-GB/mod_hello.ini

; language strings used inside mod_hello 
MOD_HELLO_NAME="Joomla Module Tutorial"
MOD_HELLO_DESCRIPTION="Source code for the Joomla module tutorial"
MOD_HELLO_GREETING="Hello

همانطور که قبلا اشاره کردیم این افزونه را برای زبان انگلیسی آماده می کنیم. بنابراین برای افزودن فایل زبان فارسی نیاز هست که فایل های زبان در مسیر mod_hello/language/fa-IR قرار بگیرند.

فایل .sys.ini برای ثابت هایی استفاده می شود که اطلاعات مربوط به افزونه ها بصورت HTML در بخش مدیریت افزونه ها ( System / Manage / Extensions )نمایش داده می شود.

مدیریت افزونه های جوملا

به عنوان مثال در بخش مدیریت افزونه ها در System / Manage / Extensions این موارد وجود دارد:

نام افزونه در قسمت نام (همانطور که در تگ مانیفست <name> تعریف شده است)
توضیحات افزونه، به عنوان یک ابزار ابزار برای نام پسوند (همانطور که در تگ مانیفست <description> تعریف شده است).

از فایل .ini برای ثابت هایی که هنگام نمایش جداگانه ماژول ظاهر می شود، استفاده می شود.

ثابت نام و توضیحات در فایل .ini نیز مورد نیاز است زیرا جوملا زمانی که مدیر ماژول‌های محتوا/سایت را انتخاب می‌کند و یک ماژول mod_hello را ایجاد یا ویرایش می‌کند، آنها را نمایش می‌دهد. در این مورد جوملا فقط فایل .ini را می خواند، زیرا تنها ماژول mod_hello در حال نمایش است.

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

بروز رسانی فایل مانیفست

ما متون انگلیسی درتگ های <name> و <description> در فایل مانیفست را با ثابت زبان جایگزین می کنیم، و همچنین به نصاب جوملا می گوییم که کجا می توان پرونده های زبان را پیدا کرد.

همانطور که در بخش زبان فایل مانیفست توضیح داده شده است، 2 روش برای استفاده از فایل های زبانی در یک افزونه وجود دارد و ما رویکرد دوم را انتخاب می کنیم ( یعنی افزودن پوشه زبان به تگ files :

<?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>

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

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

پرونده زبان مناسب را بارگیری کنید (.ini یا .sys.ini)
متن مرتبط با یک ثابت زبان منفرد را تعیین کنید.

ما می توانیم فایل .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.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 را روی بله تنظیم کنید و سپس ذخیره کنید.

اینکار باعث می شود رشته های زبان بین 2 ستاره برجسته شوند. با جابجایی گزینه Display Language که ظاهر می شود می توانید جوملا را برای خروجی ثابت زبان یا متن مرتبط دریافت کنید.

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

توضیحات: نوشته شده توسط: مسعود نیک صفت; دسته: آموزش توسعه ماژول جوملا از صفر; منتشر شده در 05 فروردين 1404; بازدید: 19