Локализация плагинов и модулей в Cotonti: полный практический разбор от принципов до вывода в шаблонах

Введение

Локализация расширений в Cotonti — это не просто перевод текста интерфейса. Это системный механизм, встроенный в архитектуру движка, который позволяет:

• хранить все языковые строки централизованно;
• разделять код и текст;
• поддерживать несколько языков без изменения бизнес-логики;
• корректно работать с числительными и формами слов;
• локализовать конфигурацию, админ-интерфейс и шаблоны.

В данной статье последовательно разобран весь процесс: от понимания механики языковой системы до создания собственного файла перевода и вывода строк на работающем сайте.

Материал построен по принципу «от базовых понятий к практической реализации». Прочитав статью частями, вы получите целостное понимание механизма.

1. Архитектура локализации в Cotonti

1.1. Единый реестр языковых строк

В Cotonti используется глобальный массив:

• $L — основной реестр языковых строк;
• $Ls — отдельный реестр форм слов для склонений (используется с cot_declension()).

Все языковые файлы, подключаемые системой, объединяются в единый массив. Это означает:

• строки из ядра,
• строки из модулей,
• строки из плагинов

в итоге находятся в одном пространстве имен.

Важное следствие

Нельзя использовать произвольные короткие ключи. Они могут перезаписать существующие системные строки.

Правильный подход — использовать уникальный префикс расширения.

2. Где располагаются файлы локализации

2.1. Путь к языковым файлам

Для плагина:

plugins/plug_name/lang/plugin_name.ru.lang.php

Для модуля: 

modules/module_name/lang/module_name.ru.lang.php

ru — двухбуквенный код языка.

Файл подключается автоматически при загрузке расширения.

3. Структура языкового файла

Минимальная структура:

<?php
defined('COT_CODE') or die('Wrong URL.');

$L['myplg_title'] = 'Заголовок';

Обязательная проверка defined('COT_CODE') защищает файл от прямого вызова.

4. Основные строки: как правильно создавать

4.1. Правило именования

Если плагин называется reviews, используем префикс rev_.

Правильно:

$L['rev_add_review'] = 'Добавить отзыв';
$L['rev_delete_review'] = 'Удалить отзыв';

Неправильно:

$L['title'] = 'Заголовок';

4.2. Использование в PHP-коде

Пример с ошибкой:

Передача в шаблон:

5. Формы числительных и массив $Ls

Русский язык требует корректных окончаний.

Для этого используется функция:

5.1. Определение форм

В языковом файле:

5.2. Использование в коде

Результат:

5.3. Использование напрямую

Но предпочтительно использовать $Ls.

6. Использование языковых строк в шаблонах

В шаблоне:

Для склонений:

Если $count = 3, вывод будет:

7. Локализация конфигурации расширения

7.1. Определение переменной в setup-файле

7.2. Локализация

Шаблон формирования:

8. Системные строки расширения

Обязательные строки описания:

Отображаются в панели управления.

9. Заголовок standalone-плагина

Если плагин работает по хуку standalone:

Ключ формируется как:

10. Администрирование (hook tools)

В коде нужно вручную инициализировать:

И определить их в языковом файле:

11. Локализация экстра-полей

Если создано поле:

Можно определить:

В шаблоне:

12. Локализация списков (современный формат)

Нельзя использовать массивы:

Неправильно:

Правильно:

Если ключ-значение:

13. Использование ресурсов ($R)

Ресурс — это шаблон строки.

Определение:

Использование:

14. Полный пример языкового файла

15. Полный цикл работы перевода

Теперь рассмотрим последовательность:

Шаг 1. Создаём файл

Шаг 2. Определяем строки

Шаг 3. Используем в коде

Шаг 4. Используем в шаблоне

16. Ключевые правила, которые нельзя нарушать

1. Всегда используйте уникальный префикс.
2. Не используйте массивы в языковых файлах.
3. Склонения храните в $Ls.
4. Для конфигурации используйте шаблон cfg_.
5. Не выводите текст напрямую в коде — только через $L.

17. Частые ошибки новичков

• Жёстко прописанные строки в PHP.
• Отсутствие префикса.
• Использование массивов вместо строк.
• Неправильное использование cot_declension.

Заключение

Локализация в Cotonti — это строгая, но логичная система.

Если соблюдать структуру:

• файл → строки → код → шаблон,
• префиксы,
• разделение $L и $Ls,
• правила конфигурации,

то расширение становится полностью независимым от языка интерфейса.

Грамотно организованный перевод делает модуль:

• расширяемым,
• совместимым с коллективным переводом,
• удобным для сопровождения,
• безопасным при обновлениях.

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