Языковые файлы

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

Где лежат файлы

Создайте вручную папку language в модуле. Внутри — по папке на язык, код языка состоит из языка и страны:

modules/mod_hello/
├── language/
│   ├── en-GB/
│   │   ├── mod_hello.ini
│   │   └── mod_hello.sys.ini
│   └── ru-RU/
│       ├── mod_hello.ini
│       └── mod_hello.sys.ini
├── mod_hello.xml
├── services/provider.php
├── src/...
└── tmpl/default.php

Добавьте папку в манифест, в раздел files:

<files>
    <folder module="mod_hello">services</folder>
    <folder>language</folder>
    <folder>src</folder>
    <folder>tmpl</folder>
</files>

Английский en-GB — язык по умолчанию: его строки Joomla берёт, если перевода на язык сайта нет. Поэтому английский файл нужен всегда.

Файл перевода

; modules/mod_hello/language/ru-RU/mod_hello.ini
MOD_HELLO_LATEST="Последние статьи"

Слева ключ — заглавными буквами, с приставкой из имени расширения. Справа строка в двойных кавычках.

Вывод строки

<?php
// modules/mod_hello/tmpl/default.php
 
defined('_JEXEC') or die;
 
use Joomla\CMS\Language\Text;
?>
<h4><?php echo Text::_('MOD_HELLO_LATEST'); ?></h4>

Text::_() находит строку по ключу на текущем языке сайта. На странице появится заголовок «Последние статьи». Языковой файл модуля Joomla загружает сама.

Подстановка значений

MOD_HELLO_GREETING="Привет, %s!"
MOD_HELLO_N_ARTICLES="Статей: %d"
MOD_HELLO_N_ARTICLES_1="Одна статья"

// modules/mod_hello/tmpl/default.php
echo Text::sprintf('MOD_HELLO_GREETING', $app->getIdentity()->name);
echo Text::plural('MOD_HELLO_N_ARTICLES', count($articles));

Text::sprintf() подставляет значения на место %s и %d. Text::plural() по числу ищет ключ с подходящим окончанием — для единицы это _1 — и берёт основной ключ, если такого нет. Вошедший пользователь увидит «Привет, Анна!» и «Статей: 5».

Файл sys.ini

Файл с окончанием .sys.ini нужен панели управления: в списке расширений и в окне выбора типа модуля Joomla загружает только его.

; modules/mod_hello/language/ru-RU/mod_hello.sys.ini
MOD_HELLO="Приветствие"
MOD_HELLO_XML_DESCRIPTION="Блок с приветствием и последними статьями"

Ключи в манифесте

Подписи в манифесте тоже заменяют ключами — Joomla переведёт их сама:

<name>MOD_HELLO</name>
<description>MOD_HELLO_XML_DESCRIPTION</description>
 
<field name="greeting" type="text" label="MOD_HELLO_FIELD_GREETING_LABEL" default="Привет!" />

Ключ MOD_HELLO_FIELD_GREETING_LABEL добавляют в mod_hello.ini: этот файл загружается, когда открыта форма модуля.

Как найти непереведённое

Включите «Система → Общие настройки → Система → Отладка языка». Строки без перевода будут выведены в виде ??КЛЮЧ??, а панель отладки покажет, какие языковые файлы загружены.

Частая ошибка

Вместо текста на странице виден сам ключ: MOD_HELLO_LATEST. Причин обычно три: опечатка в ключе, строка без закрывающей кавычки (весь файл после неё не читается) или папка language не указана в манифесте, из-за чего при установке из архива файлы не скопировались.