Керування баготомовністю
(*Ця стаття є частиною посібника “Розробка MVC-компоненти для Joomla 4.x”. Вона є продовженням посібника з програмування. Тому, якщо ви не читали попередні частини, ми рекомендуємо вам це зробити.
Попередня стаття «Додавання пункту меню до клієнтської частини сайту»)
Базовий устрій з керуванням багатомовністю
У цій статті ми додамо керування перекладами текстів до нашої нової компоненти. Можливо, ви помітили у попередній частині цієї серії підручників, що коли ми додали посилання на меню до компоненти, ми жорстко прописали англійські слова у цьому фрагменті:
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="Hello World!">
<message><![CDATA[My first Joomla! page]]></message>
</layout>
</metadata>
Це працює як початковий тест, але жорстке прописування однієї мови в системі - погана ідея. Перш ніж заглиблюватися у створення сторінок і форм, варто додати до компоненти багатомовну підтримку.
Навіть якщо ви особисто не маєте ресурсів для самостійного перекладу, ми наполегливо рекомендуємо вам старанно керувати перекладами тексту у вашій компоненті. Компоненти з відкритим вихідним кодом можуть бути перекладені членами спільноти, а кінцеві користувачі можуть створювати власні переклади, якщо вони цього бажають.
Давайте створимо мовні файли і оновимо маніфест, щоб посилатися на них:
1 Створіть файл: admin/language/en-GB/com_helloworld.ini
(Переклади текстових констант компоненти для частини адмін-панелі)
2 Створіть файл: admin/language/en-GB/com_helloworld.sys.ini
(Переклади текстових констант для системної частини (такі як заголовки меню, загальні заголовки адмінки) вашої компоненти)
3 Створіть файл: site/language/en-GB/com_helloworld.ini
(Переклади текстових констант компоненти для клієнтської частини сайту (фронтенду))
4 Оновіть: helloworld.xml (Потрібно додати шляхи до мовних файлів у маніфест)
5 Оновіть: admin/tmpl/hello/default.php (Заміна жорстко прописаних мовних текстів на мовні константи.)
6 Оновіть: site/tmpl/hello/default.php (Виправлення текстів на текстові константи, як в пункті 5.)
7 Оновіть: site/tmpl/hello/default.xml (Виправлення текстів на текстові константи, як в пункті 5.)
Опис файлів
** admin/language/en-GB/com_helloworld.ini**
Цей файл містить переклади текстових констант, що використовуються на сторінках компоненти в адміністративній панелі Joomla.
; Hello World Admin Strings
; Copyright (C) 2020 John Smith. All rights reserved.
COM_HELLOWORLD_MSG_HELLO_WORLD="Hello World!"
** admin/language/en-GB/com_helloworld.sys.ini**
Цей файл містить переклади текстових констант, що належить до ядра системи Joomla (системні заголовки, заголовки панелей/меню). Наприклад, рядки нашого пункту меню належать компоненті, але використовуються системою меню Joomla, а не на сторінках нашої компоненти, тому вони знаходяться у цьому файлі.
; Hello World Sys.ini
; Copyright (C) 2020 John Smith. All rights reserved.
COM_HELLOWORLD_MENU_HELLO_WORLD_TITLE="Hello World!"
COM_HELLOWORLD_MENU_HELLO_WORLD_DESC="My first Joomla! page"
site/language/en-GB/com_helloworld.ini
Цей файл містить переклади текстових констант, що використовуються на “публічних” сторінках компоненти (фронтенд). Варто звернути увагу на кілька речей, які є спільними для всіх мовних файлів, які ви будете створювати. По-перше, текстові контанти зберігаються в загальному форматі INI, а назва кожної властивості починається з системного імені компоненти: com_helloworld. За домовленістю, всі текстові константи записуються великими літерами.
Назва каталогу мовних файлів має код локалізації, “en-GB”. Для кожної локалізації, яку ви бажаєте підтримувати, вам знадобиться новий набір файлів.
; Hello World Public Site Strings
; Copyright (C) 2020 John Smith. All rights reserved.
COM_HELLOWORLD_MSG_HELLO_WORLD="Hello World!"
(*ред. в перекладі змінено за актуальним станом вимог до назви мовних файлів)
helloworld.xml
Як і раніше, нам потрібно додати нові мовні папки до маніфесту, щоб Joomla знала, куди їх скопіювати. Крім того, нам потрібно повідомити Joomla про те, що у нас є мовні файли, де їх знайти, і які локалі вони підтримують. Це робиться за допомогою додавання двох XML-блоків <language />, по одному для кожної частини компоненти.
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="4.0" method="upgrade">
<name>Hello World</name>
<!-- Наступні елементи є необов'язковими і не мають обмежень щодо форматування -->
<creationDate>December 2020</creationDate>
<!-- Умовний автор, не соромтеся замінювати будь-де, де побачите -->
<author>John Smith</author>
<authorUrl>https://smith.ca</authorUrl>
<copyright>John Smith</copyright>
<license>GPL v3</license>
<!-- Дані про версію записується в таблицю компонентів -->
<version>0.0.4</version>
<!-- Опис, опціонально, і за замовчуванням співпадає з назвою -->
<description>
A hello world component!
</description>
<!-- Це простір імен PHP, у якому розширенні
реалізовано код. Він повинен мати такий формат:
Vendor\Component\ComponentName
"Vendor" може бути назва вашої компанії або ваше власне ім`я
Секція "Назва компонента" ПОВИННА збігатися з назвою, що використовується
для вашої компоненти в інших місцях. У будь-якому випадку, назва
XML-файлу та простір імен повинен збігатися (ігноруючи CamelCase).
-->
<namespace path="src/">JohnSmith\Component\HelloWorld</namespace>
<files folder="site/">
<folder>language</folder>
<folder>src</folder>
<folder>tmpl</folder>
</files>
<languages>
<language tag="en-GB">site/language/en-GB/com_helloworld.ini</language>
</languages>
<administration>
<!-- Посилання, яке з'явиться в адмін-панелі меню "Копонентів" -->
<menu link="index.php?option=com_helloworld">Hello World</menu>
<!-- Список файлів і папок для копіювання, а також куди їх копіювати -->
<files folder="admin/">
<folder>language</folder>
<folder>services</folder>
<folder>src</folder>
<folder>tmpl</folder>
</files>
<languages>
<language tag="en-GB">admin/language/en-GB/com_helloworld.ini</language>
<language tag="en-GB">admin/language/en-GB/com_helloworld.sys.ini</language>
</languages>
</administration>
</extension>
** admin/tmpl/hello/default.php**
Замініть жорстко прописані англійською тексти на мовні константи. Ми використовуємо клас Joomla\CMS\Language\Text для виведення наших текстових констант на сторінці. Якщо кінцевий користувач використовує іншу мову, яка підтримується в нашому компоненті, цей клас автоматично отримає правильно перекладані тексти для цієї мови і виведе їх замість текстових констант.
<?php
use Joomla\CMS\Language\Text;
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2020 John Smith. All rights reserved.
* @license GNU General Public License version 3; see LICENSE
*/
// No direct access to this file
defined('_JEXEC') or die('Restricted Access');
?>
<h2><?= JText::_('COM_HELLOWORLD_MSG_HELLO_WORLD') ?></h2>
site/tmpl/hello/default.php
Наразі наші шаблони сторінок ідентичні, тому зробіть заміни ідентично попереднього файлу.
<?php
use Joomla\CMS\Language\Text;
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2020 John Smith. All rights reserved.
* @license GNU General Public License version 3; see LICENSE
*/
// No direct access to this file
defined('_JEXEC') or die('Restricted Access');
?>
<h2><?= JText::_('COM_HELLOWORLD_MSG_HELLO_WORLD') ?></h2>
site/tmpl/hello/default.xml
Так само, як і у випадку з файлами шаблонів PHP, нам потрібно замінити жорстко прописану англійську мову у цьому файлі на нові мовні текстові константи. Однак, на відміну від PHP-файлів, нам не потрібен ніякий додатковий код для цього - просто замініть англійські тексти на назви текстових констант, і Joomla буде достатньо розумною, щоб підібрати їх для нас.
Пам’ятайте: оскільки ці тексти використовуються Joomla у ядрі системи (за межами нашої компоненти), вони знаходяться у спеціальному файлі admin/language/en-GB/com_helloworld.sys.ini.
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_MENU_HELLO_WORLD_TITLE">
<message><![CDATA[COM_HELLOWORLD_MENU_HELLO_WORLD_DESC]]></message>
</layout>
</metadata>
Тестування компоненти
Як і раніше, заархівуйте вашу нову версію компоненти і завантажте її в адмін-панелі вашого інсталятора Joomla. Після того, як компонент буде встановлено, перевірте, чи всі ваші сторінки та посилання меню виглядають точно так само, як і раніше. Якщо все працює належним чином, не повинно бути жодних змін.