Руководство по созданию локализации интерфейса Cotonti

Руководство по созданию локализации интерфейса Cotonti

Полное практическое руководство по созданию локализации интерфейса Cotonti CMF для разработчика сайта. Пошагово разобраны все три уровня языковых файлов: системный, тема, расширения. Описано, как добавить новый язык (например, грузинский, чеченский, татарский), как переопределить нестандартный код языка без правки ядра, как настроить язык сайта и язык пользователя. Приведены таблицы кодов ISO 639-1 для языков стран бывшего СССР и республик РФ, схема размещения файлов, примеры кода и раздел по устранению типичных проблем. Все данные — на основе архитектуры Cotonti V.1.

Оглавление

1. Введение
2. Коды языков
3. Структура языковых файлов
4. Создание локализации ядра
5. Создание локализации темы
6. Создание локализации расширений
7. Добавление нового языка
8. Переопределение кода языка
9. Настройка языка сайта
10. Устранение неполадок
11. Заключение

1. Введение

Cotonti CMF спроектирован как многоязычная система. Вся текстовая информация интерфейса хранится в отдельных языковых файлах, которые представляют собой обычные PHP-файлы с массивами языковых строк. Базовая установка включает языковые пакеты для английского и русского языков.

Существует два принципиально разных подхода к локализации:

1. Полная локализация — создание нового языкового пакета с нуля. Редактируются все языковые файлы, создаётся полноценный перевод интерфейса.
2. Частичное переопределение — изменение отдельных языковых строк без создания полного языкового пакета. Рекомендуется для изменения конкретных фраз в существующей локализации.

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

2. Коды языков

Для обозначения языков система использует двухбуквенные коды согласно стандарту ISO 3166-1. Примеры: en (английский), ru (русский), de (немецкий).

Код языка используется в имени каждого языкового файла: xxxx.en.lang.php, xxxx.ru.lang.php и т.д.

Государственные языки стран бывшего СССР

Языки республик в составе РФ

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

Языковые файлы Cotonti делятся на три типа, каждый из которых размещается в своём каталоге.

Системные языковые файлы

Размещаются в каталоге /system/lang/{lang_code}/:

Языковые файлы модулей

Размещаются в каталоге modules/{module_name}/lang/:

modules/{module_name}/lang/{module_name}.{lang_code}.lang.php

Языковые файлы плагинов

Размещаются в каталоге plugins/{plugin_name}/lang/:

plugins/{plugin_name}/lang/{plugin_name}.{lang_code}.lang.php

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

Размещаются в корне каталога темы:

themes/{theme_name}/{theme_name}.{lang_code}.lang.php

4. Создание локализации ядра

Шаг 1. Создание каталога языка

Создайте каталог с кодом языка в /system/lang/. Например, для грузинского языка (ka):

/system/lang/ka/

Шаг 2. Копирование английских файлов

Скопируйте все файлы из /system/lang/en/ в созданный каталог. Переименуйте их в соответствии с кодом нового языка:

/system/lang/ka/admin.ka.lang.php
/system/lang/ka/countries.ka.lang.php
/system/lang/ka/main.ka.lang.php
/system/lang/ka/message.ka.lang.php
/system/lang/ka/translit.ka.lang.php
/system/lang/ka/users.ka.lang.php

Шаг 3. Перевод содержимого

Откройте каждый файл и переведите значения языковых переменных. Языковые файлы представляют собой PHP-массивы вида:

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

$L['Home'] = 'მთავარი';
$L['Users'] = 'მომხმარებლები';
$L['Login'] = 'შესვლა';

Правила перевода:

• Переводится только значение переменной, ключ остаётся неизменным.
• Файлы должны быть в кодировке UTF-8 без BOM.
• Нельзя удалять или переименовывать существующие ключи.
• Новые ключи можно добавлять.

Шаг 4. Обновление названия языка в списке

В файле system/functions.php содержится массив $cot_languages с отображаемыми названиями языков:

$cot_languages['cn'] = '中文';
$cot_languages['de'] = 'Deutsch';
$cot_languages['en'] = 'English';
$cot_languages['ru'] = 'Русский';
$cot_languages['ua'] = 'Українська';

Чтобы добавить название нового языка, используйте файл system/functions.custom.php:

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

$cot_languages['ka'] = 'ქართული';
$cot_languages['ce'] = 'Нохчийн мотт';
$cot_languages['tt'] = 'Татарча';

Для загрузки этого файла в datas/config.php должна быть включена опция:

$cfg['customfuncs'] = true;

5. Создание локализации темы

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

Создание файла локализации темы

Создайте файл по пути:

themes/{theme_name}/{theme_name}.{lang_code}.lang.php

Например, для темы index36 и грузинского языка:

themes/index36/index36.ka.lang.php

Пример содержимого

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

// Переопределение системной строки
$L['Contact'] = 'კონტაქტი';

// Добавление новой строки для темы
$L['theme_custom_greeting'] = 'მოგესალმებით';

Использование в шаблонах

В .tpl-файлах темы строки вызываются через тег {PHP.L.key}:

{PHP.L.Contact}
{PHP.L.theme_custom_greeting}

Порядок загрузки

Загрузка языковых файлов происходит в следующей последовательности:

1. Системные языковые файлы
2. Языковые файлы темы
3. Языковые файлы плагинов

Каждый следующий файл может переопределять переменные из предыдущего.

6. Создание локализации расширений

Модули

Создайте файл:

modules/{module_name}/lang/{module_name}.{lang_code}.lang.php

Плагины

Создайте файл:

plugins/{plugin_name}/lang/{plugin_name}.{lang_code}.lang.php

Локализация административной панели плагинов

Для перевода административной панели плагина используется массив $L. Строки для настроек плагина определяются в файле {plugin_name}.setup.php и могут быть переведены через языковой файл плагина.

7. Добавление нового языка

Общий порядок действий

1. Создайте каталог языка в /system/lang/{lang_code}/
2. Скопируйте и переведите все системные языковые файлы
3. Добавьте название языка в system/functions.custom.php
4. Создайте языковые файлы тем для используемых тем оформления
5. Создайте языковые файлы расширений для установленных модулей и плагинов
6. Установите язык по умолчанию или разрешите пользователям выбирать его в профиле

Установка языка по умолчанию

В файле datas/config.php:

$cfg['defaultlang'] = 'ka'; // грузинский язык по умолчанию

Выбор языка пользователем

Зарегистрированный пользователь может выбрать язык в своём профиле. Значение сохраняется в поле user_lang таблицы cot_users.

Администратор может принудительно установить язык для всех пользователей в разделе: Панель администрирования → Конфигурация → Локализация.

8. Переопределение кода языка

Переопределение кода ua на uk

В штатном Cotonti для украинского языка используется код ua, который не является стандартным кодом ISO 639-1. Стандартный код — uk.

Для переопределения без правки ядра добавьте в system/functions.custom.php:

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

// Удаляем нестандартный код
unset($cot_languages['ua']);
// Добавляем стандартный код
$cot_languages['uk'] = 'Українська';

Создание каталога для нового кода

Создайте каталог /system/lang/uk/ и скопируйте туда языковые файлы из /system/lang/ua/.

Переименование файлов темы

Если языковые файлы темы использовали код ua, переименуйте их:

themes/{theme}/{theme}.ua.lang.php → themes/{theme}/{theme}.uk.lang.php

9. Настройка языка сайта

Основные параметры

Определение языка браузера

Функция cot_lang_determine() автоматически определяет предпочитаемый язык пользователя на основе заголовка HTTP_ACCEPT_LANGUAGE и сопоставляет его с доступными языковыми пакетами.

10. Устранение неполадок

Язык не отображается в списке

• Проверьте наличие каталога /system/lang/{lang_code}/
• Убедитесь, что название языка добавлено в $cot_languages через functions.custom.php
• Проверьте, включена ли опция $cfg['customfuncs'] = true;

Перевод не применяется

• Проверьте кодировку файла (UTF-8 без BOM)
• Убедитесь, что ключ языковой переменной указан верно
• Проверьте порядок загрузки: файлы темы переопределяют системные файлы

Ошибки после обновления

• Не редактируйте системные языковые файлы напрямую
• Используйте файлы локализации темы для переопределения строк
• Ведите собственный файл functions.custom.php для кастомизаций

Не переведена административная панель

• Для перевода админ-панели плагинов используется массив $L в языковом файле плагина
• Убедитесь, что файл локализации размещён по правильному пути

11. Заключение

Локализация Cotonti CMF выполняется через систему языковых файлов, состоящую из трёх уровней:

1. Системный уровень — /system/lang/{lang_code}/
2. Уровень темы — themes/{theme_name}/{theme_name}.{lang_code}.lang.php
3. Уровень расширений — modules/{module_name}/lang/ и plugins/{plugin_name}/lang/

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

Кастомизация, не затрагивающая ядро системы, выполняется через system/functions.custom.php. Этот файл не перезаписывается при обновлениях Cotonti, что обеспечивает сохранность пользовательских изменений.