Управление языками при создании компонента в Joomla 4.x

Эта статья является частью учебника "Разработка компонента MVC для Joomla 4.x". Он предназначен для последующего руководства по программированию, поэтому, если вы не читали предыдущие части руководства, вам рекомендуется сделать это. Предыдущая статья: «Добавление типа меню для фронтенда в компоненте Joomla 4».

• Основы создания мультиязычного компонента в Joomla 4
• Содержимое файлов компонента для Joomla 4.x
  • admin/language/en-GB/en-GB.com_helloworld.ini
  • admin/language/en-GB/en-GB.com_helloworld.sys.ini
  • site/language/en-GB/en-GB.com_helloworld.ini
  • helloworld.xml
  • admin/tmpl/hello/default.php
  • site/tmpl/hello/default.php
  • site/tmpl/hello/default.xml
• Тестирование компонента в Joomla 4 в режиме мультиязычности

Основы создания мультиязычного компонента в Joomla 4

В этой статье мы добавим управление языковыми строками в наш новый компонент. Возможно, вы заметили в последней статье, что, когда мы добавили ссылку меню к компоненту, мы жестко прописали английские слова в ссылку:

<?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/en-GB.com_helloworld.ini
   • Файл с языковыми константами компонента для панели администратора
2. Новый файл: admin/language/en-GB/en-GB.com_helloworld.sys.ini
   • Файл с языковыми константами компонента с переводом сообщений в системе
3. Новый файл: site/language/en-GB/en-GB.com_helloworld.ini
   • Файл с языковыми константами компонента для фронтенда (сайта)
4. Обновления: helloworld.xml
   • Необходимо добавить языковые файлы в манифест компонента
5. Обновления: admin/tmpl/hello/default.php
   • Замена жестко прописанных строк на языковые константы
6. Обновления: site/tmpl/hello/default.php
   • Замена жестко прописанных строк на языковые константы
7. Обновления: site/tmpl/hello/default.xml
   
   • Замена жестко прописанных строк на языковые константы

Содержимое файлов компонента для Joomla 4.x

admin/language/en-GB/en-GB.com_helloworld.ini

Этот файл содержит языковые строки, используемые на страницах компонента в панели администратора Joomla 4.

; Hello World Admin Strings
; Copyright (C) 2021 John Smith. All rights reserved.

COM_HELLOWORLD_MSG_HELLO_WORLD="Hello World!"

admin/language/en-GB/en-GB.com_helloworld.sys.ini

Этот файл содержит языковые строки, используемые в системе Joomla 4 за пределами собственных страниц компонента. Например, строки нашего пункта меню принадлежат этому компоненту, но используются 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/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

Как и прежде, нам нужно добавить новые папки language с файлами языковых констант в манифест, чтобы Joomla знала, как скопировать их в нужное место файловой системы сайта. Кроме того, нам нужно сообщить Joomla, что у нас есть языковые файлы, где их найти и какие языковые локали они поддерживают. Это делается с добавлением двух XML-блоков <language />, по одному для каждой части компонента (как для админки, так и для фронтенда).

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" method="upgrade">
<!-- атрибут 'version' для тега расширения больше не используется -->
 
    <name>Hello World</name>
    <!-- Следующие элементы являются необязательными и не содержат ограничений на форматирование -->
    <creationDate>May 2021</creationDate>
    <!-- Фиктивный автор, не стесняйтесь заменять его в любом месте, где вы его видите -->
    <author>John Smith</author>
    <authorUrl>https://mb4.ru</authorUrl>
    <copyright>Пётр Васечкин</copyright>
    <license>GPL v3</license>
    <!-- Строка 'version' записывается в таблицу компонентов -->
    <version>0.0.4</version>
    <!-- Описание является необязательным и по умолчанию используется имя сомпонента -->
    <description>
        A hello world component!
    </description>
 
    <!-- Это пространство имен PHP, в котором организован
    код расширения. Он должен следовать этому формату:
    
    Vendor\Component\ComponentName
 
    "Vendor" может быть названией компании или вашим собственным именем
    
    Раздел "ComponentName" ДОЛЖЕН соответствовать имени, используемому 
    везде для вашего компонента. Каким бы ни было имя этого XML-файла, 
    пространство имен должно совпадать (заглавные/прописные буквы не учитываются). 
    -->
    <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/en-GB.com_helloworld.ini</language>
    </languages>
            
    <administration>
        <!-- Ссылка, которая появится в меню админки Joomla "Components" -->
        <menu link="index.php?option=com_helloworld">Hello World</menu>
        <!-- Список файлов и папок для копирования.
             Обратите внимание на атрибут "folder".
             Это имя папки в пакете компонентов для копирования в CMS Joomla 4. -->
        <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/en-GB.com_helloworld.ini</language>
            <language tag="en-GB">admin/language/en-GB/en-GB.com_helloworld.sys.ini</language>
        </languages>
    </administration>
 
</extension>

Обратите внимания на строки:

• стр.14 — обновление версии компонента Joomla 4
• стр.34 — добавление папки language с языковыми константами для сайта компонента Joomla 4
• стр.39..41 — добавление описаний, где брать языковые константы для фронтенда сайта компонента Joomla 4
• стр.50 — добавление папки language с языковыми константами для админки компонента Joomla 4
• стр.56..59 — добавление описаний, где брать языковые константы для админки сайта и системы компонента Joomla 4

admin/tmpl/hello/default.php

Замените жестко прописанные английские строки новыми свойствами языка. Мы используем класс Joomla\CMS\Language\Text для вывода наших языковых констант на страницу в нужных местах. Если конечный пользователь использует другой язык, поддерживаемый в нашем компоненте, этот класс автоматически извлекает правильные строки для этого языка и выводит их вместо языковых констант.

<?php

use Joomla\CMS\Language\Text;
 
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2021 John Smith. All rights reserved.
 * @license     GNU General Public License version 3; see LICENSE
 */
 
 // Нет прямого доступа к этому файлу
defined('_JEXEC') or die('Всем кыш! =D');
?>
<h2><?= Text::_('COM_HELLOWORLD_MSG_HELLO_WORLD') ?></h2>

Обратите внимания на строки:

• стр.3 — добавление класса Joomla\CMS\Language\Text для вывода наших языковых констант
• стр.16 — замена жёстко прописанной фразы её языковой константой, хранящейся в файле с её значением

site/tmpl/hello/default.php

Наши шаблоны страниц сайта тоже надо поправить, поэтому необходимые замены похожи тем, что мы сделали с файлами админской части шаблона. Удалите жестко прописанные фразы и замените их вызовом языковых констант.

<?php

use Joomla\CMS\Language\Text;
 
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2021 John Smith. All rights reserved.
 * @license     GNU General Public License version 3; see LICENSE
 */
 
 // Не дать прямого доступа к выполнению PHP-кода в файле
defined('_JEXEC') or die('Но пасаран! =)');
?>
<h2><?= Text::_('COM_HELLOWORLD_MSG_HELLO_WORLD') ?></h2>

Обратите внимания на строки:

• стр.3 — добавление класса Joomla\CMS\Language\Text для вывода наших языковых констант
• стр.16 — замена жёстко прописанной фразы её языковой константой, хранящейся в файле с её значением

site/tmpl/hello/default.xml

Так же, как и файлы шаблонов PHP, нам нужно заменить жестко прописанные фразы в этом файле созданными языковыми константами. Однако, в отличие от файлов PHP, нам не нужен никакой дополнительный код для этого - просто замените английские строки именами языковых свойств, и Joomla достаточно умна, чтобы подставить их при выводе этого шаблона.

Напоминалочка: поскольку эти строки используются Joomla в ее собственной системе (за пределами страниц нашего компонента), они находятся в специальном файле admin/language/en-GB/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>

Обратите внимания на строки:

• стр.3..4 — мы просто заменили текст на языковые константы, вместо которых будут подставляться их значения из файлов языков.

Тестирование компонента в Joomla 4 в режиме мультиязычности

Как и раньше, заархивируйте новую версию компонента и загрузите ее в панель администратора установки Joomla. Как только он будет установлен, обойдите его и убедитесь, что ваши страницы и ссылки на меню отображаются точно так же, как и раньше. Если все работает правильно, не должно быть никаких изменений вообще.

В следующей части рассмотрим: Добавление модели фронтенда в наш компонент для Joomla 4.

Перевод с английского:
https://docs.joomla.org/J4.x:Developing_an_MVC_Component/Language_Management

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)