1. Home
  2. Documentation
  3. Глава 10. Локализация и интернационализация (i18n)

Глава 10. Локализация и интернационализация (i18n)

07-07-26 15:38

В этой главе рассматривается устройство мультиязычности (интернационализации) в Seditio CMS, правила расположения и структура языковых файлов ядра, модулей, плагинов и тем оформления, а также логика автоподгрузки и переопределения локализаций.

10.1. Мультиязычность в Seditio CMS

Seditio CMS изначально проектировалась с возможностью гибкой поддержки нескольких языков как для интерфейса (панели управления, системных сообщений, тем оформления), так и для элементов структуры (категорий страниц и разделов форума).

10.1.1. Определение активного языка

Язык интерфейса для каждого конкретного посетителя определяется во время загрузки страницы в ядре системы:

  • Для зарегистрированных пользователей: Язык считывается из профиля пользователя (поле user_lang в БД) и записывается в переменную $usr['lang'].
  • Для гостей: Используется значение по умолчанию из глобального конфигурационного файла (datas/config.php), хранящееся в $cfg['defaultlang'] (по умолчанию обычно 'en' или 'ru').
  • Окончательный выбор: Выбранный двухсимвольный код языка (например, 'ru', 'en', 'tr') записывается в глобальную переменную $lang, которая используется во всех последующих вызовах локализации.

10.1.2. Локализация структуры сайта

Для поддержки мультиязычности категорий страниц (структуры) и разделов форума в панели администратора предусмотрены поля альтернативных названий и описаний. Это позволяет выводить категории на выбранном языке пользователя без необходимости дублирования дерева страниц.

10.2. Файловая структура языковых пакетов ядра

Все языковые пакеты для ядра Seditio CMS располагаются в системном каталоге /system/lang/.

10.2.1. Каталоги языков

Внутри /system/lang/ для каждого языка создается отдельная подпапка с двухсимвольным кодом (ISO 639-1):

  • /system/lang/en/ — английский пакет.
  • /system/lang/ru/ — русский пакет.
  • /system/lang/tr/ — турецкий пакет.

10.2.2. Состав языкового пакета ядра

Внутри папки каждого языка находятся три основных файла:

  1. main.lang.php — содержит локализацию публичной части сайта (кнопки, заголовки, тексты форм, даты, разметка прав доступа). Все фразы записываются в глобальный массив $L (например, $L['Home'] = "Главная";).
  2. admin.lang.php — локализация административной зоны управления. Используется только в панели управления (SED_ADMIN) и заполняет массив фраз администрирования.
  3. message.lang.php — локализация системных предупреждений, ошибок и уведомлений (например, сообщения об успешном добавлении, ошибки валидации форм, ошибки ЧПУ, ошибки 404).

10.3. Локализация модулей и плагинов

Каждый дополнительный модуль и плагин в Seditio является автономным компонентом и содержит собственные файлы локализации.

10.3.1. Размещение языковых файлов

  • Модули: Файлы локализации модуля располагаются в его папке по пути: /modules/{код_модуля}/lang/{код_модуля}.{код_языка}.lang.php Пример: /modules/page/lang/page.ru.lang.php — файл русской локализации модуля Страниц.
  • Плагины: Файлы локализации плагина располагаются в его папке по пути: /plugins/{код_плагина}/lang/{код_плагина}.{код_языка}.lang.php Пример: /plugins/recentitems/lang/recentitems.ru.lang.php — файл русской локализации плагина RecentItems.

10.3.2. Локализация конфигураций (Префикс cfg_)

Seditio CMS использует файлы локализации модулей и плагинов для перевода названий и описаний настроек, выводимых в административной панели. Если модуль или плагин имеет зарегистрированную настройку (например, maxpages в плагине recentitems), то для её перевода в языковом файле объявляется элемент массива с префиксом cfg_:

$L['cfg_maxpages'] = array("Количество страниц", "Укажите максимальное количество страниц для вывода в блоке");
  • Первый элемент массива — человекочитаемое краткое название настройки.
  • Второй элемент массива — подробное всплывающее описание/подсказка к этой настройке.

10.3.3. Локализация интерфейса компонента

Все прочие строки, необходимые для работы контроллера или вывода в TPL-шаблонах компонента, записываются в глобальный массив $L с уникальными префиксами во избежание коллизий:

$L['pag_titletooshort'] = "Заголовок слишком короткий либо отсутствует";
$L['lis_submitnew'] = "Добавить новую запись";

10.4. Механизм поиска и загрузки языков (sed_langfile)

Для корректного подключения файлов локализации используется системная функция sed_langfile() из файла system/functions.php.

10.4.1. Сигнатура функции

function sed_langfile($code, $type = 'plugin', $lang = null)
  • $code (string) — уникальный код компонента (код плагина или модуля).
  • $type (string, необязательный) — тип компонента ('plugin' или 'module'). По умолчанию — 'plugin'.
  • $lang (string, необязательный) — принудительно запрашиваемый язык. Если не указан, берется активный язык посетителя $usr['lang'] или дефолтный $cfg['defaultlang'].

10.4.2. Алгоритм поиска и резервная логика (Fallback)

Функция выполняет поиск файла на диске по следующим приоритетам:

  1. Основной язык: Ищется файл по выбранному языку. Например, для плагина myplugin при русском языке пользователя путь будет: /plugins/myplugin/lang/myplugin.ru.lang.php.
  2. Английский резервный вариант (Fallback): Если основной файл локализации не найден (например, у пользователя выбран французский язык 'fr', а для плагина есть только английский), система ищет английскую локализацию: /plugins/myplugin/lang/myplugin.en.lang.php.
  3. Результат: Функция возвращает абсолютный путь к существующему файлу на диске или пустую строку, если локализаций не найдено.

Пример подключения в коде плагина:

$langfile = sed_langfile('myplugin', 'plugin');
if (!empty($langfile)) {
    require($langfile);
}

10.5. Последовательность инициализации языков при загрузке страницы

Инициализация языкового окружения происходит на этапе первоначальной загрузки ядра в системном файле system/common.php. Подключение файлов строго упорядочено:

10.5.1. Загрузка ядра локализации

Сначала подключается основной системный языковой файл:

$mlang = SED_ROOT . '/system/lang/' . $usr['lang'] . '/main.lang.php';
// ...
require($mlang);

После этого становятся доступны базовые массивы локализации сайта (например, даты, служебные слова, базовые заголовки).

10.5.2. Автоматическая загрузка языков активных модулей

Для того чтобы общие строки модулей (такие как названия категорий, префиксы заголовков страниц $L['core_page'] и т.д.) были доступны глобально (например, при рендеринге меню в шапке или виджетов в подвале), ядро перебирает массив активных модулей $sed_modules и подключает их языковые файлы:

foreach ($sed_modules as $mod_code => $mod_row) {
    if ($mod_lang_file = sed_langfile($mod_code, 'module', $lang)) {
        include_once($mod_lang_file);
    }
}

10.5.3. Переопределение строк на уровне скина (темы оформления)

Наивысшим приоритетом локализации обладает активный скин сайта. После загрузки всех системных файлов и файлов модулей ядро проверяет наличие языкового файла внутри папки темы (например, skins/sympfy/sympfy.ru.lang.php):

if (@file_exists($usr['skin_lang'])) {
    require($usr['skin_lang']);
}

Благодаря этому верстальщик может переопределить любую языковую строку ядра или модулей (массив $skinlang) непосредственно на уровне активной темы оформления без вмешательства в исходные PHP-файлы системы.

10.6. Практическое руководство по созданию мультиязычного плагина

Создадим файлы локализации для плагина с кодовым именем myplugin, имеющего одну текстовую настройку banner_text.

10.6.1. Создание папки языков

Внутри каталога /plugins/myplugin/ создайте подпапку lang/. В ней создайте два файла: myplugin.en.lang.php (английский язык) и myplugin.ru.lang.php (русский язык).

10.6.2. Создание английского файла myplugin.en.lang.php

<?php
/* ====================
[BEGIN_SED]
File=plugins/myplugin/lang/myplugin.en.lang.php
Version=1.0.0
Updated=2026-jul-06
Type=Plugin.lang
Name=My Plugin (English Localization)
[END_SED]
==================== */

if (!defined('SED_CODE')) exit();

// Перевод настроек плагина в админ-панели
$L['cfg_banner_text'] = array("Banner html text", "Enter the text or HTML markup to display in the header banner.");

// Строки вывода в пользовательской части
$L['myplug_welcome'] = "Welcome to our website!";
$L['myplug_readmore'] = "Read more";

10.6.3. Создание русского файла myplugin.ru.lang.php

<?php
/* ====================
[BEGIN_SED]
File=plugins/myplugin/lang/myplugin.ru.lang.php
Version=1.0.0
Updated=2026-jul-06
Type=Plugin.lang
Name=My Plugin (Russian Localization)
[END_SED]
==================== */

if (!defined('SED_CODE')) exit();

// Перевод настроек плагина в админ-панели
$L['cfg_banner_text'] = array("HTML текст баннера", "Введите текст или HTML-разметку для отображения в баннере шапки.");

// Строки вывода в пользовательской части
$L['myplug_welcome'] = "Добро пожаловать на наш сайт!";
$L['myplug_readmore'] = "Читать далее";

10.6.4. Использование в PHP-коде плагина (myplugin.php)

<?php
if (!defined('SED_CODE')) exit();

// Подключаем языковой файл (сработает автовыбор языка или fallback на .en.)
$langfile = sed_langfile('myplugin', 'plugin');
if (!empty($langfile)) {
    require($langfile);
}

// Рендерим шаблон (нет необходимости передавать строки $L в шаблонизатор вручную)
$t->parse("MAIN");
$t->out("MAIN");

[!TIP] Исключение избыточного вызова assign: В Seditio CMS нет необходимости принудительно регистрировать каждую языковую строку плагина в шаблонизаторе с помощью метода $t->assign(). Поскольку шаблонизатор поддерживает префикс глобального контекста PHP., любые языковые фразы из массива $L (после подключения языкового файла) доступны напрямую в TPL-шаблоне через синтаксис {PHP.L.имя_переменной}. Это делает PHP-код плагина чистым и лаконичным.

10.6.5. Использование в TPL-шаблоне плагина (myplugin.tpl)

<!-- BEGIN: MAIN -->
<div class="welcome-banner">
    <h2>{PHP.L.myplug_welcome}</h2>
    <p>{PHP.cfg.plugin.myplugin.banner_text}</p>
    <a href="index.php?module=page" class="btn">{PHP.L.myplug_readmore}</a>
</div>
<!-- END: MAIN -->

При открытии страницы гостем с русским языком шаблонизатор автоматически выведет надпись «Добро пожаловать на наш сайт!», а для англоязычного гостя — «Welcome to our website!», считывая значения напрямую из глобального массива $L.

Amro
0

Ratings:
(0.00)

Comments: (0)

No comments yet