Сайт справки

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

Предыдущая статья: Добавление типа меню для фронтенда в компоненте 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.

Наверх

© Сайт справки 2024