Локализация в Moodle сводится к одному правилу: в коде нет ни одной строки, видимой пользователю. Всё идёт через get_string() и языковые файлы. Это решает сразу три задачи: администратор может переопределить текст без правки кода, плагин можно перевести на другой язык, а ошибки и подсказки лежат в одном месте. Русский язык добавляет свои ловушки: склонение, кодировка, кавычки. Ниже я прохожу по структуре и по тому, что ломается чаще всего. Общую структуру плагина смотрите в статье про файлы плагина.
Где лежат строки
Каждый компонент имеет собственный языковой файл: lang/en/local_hello.php для плагина local_hello. Исключение сделано для модулей активностей: их файл называется по имени модуля без префикса типа (lang/en/quiz.php для mod_quiz). Английский файл обязателен и является источником истины. Файлы других языков (lang/ru/...) добавляются поверх; если строки в них нет, Moodle берёт английскую.
<?php
defined('MOODLE_INTERNAL') || die();
$string['pluginname'] = 'Hello';
$string['notesfor'] = 'Notes of {$a}';
$string['studentcount'] = '{$a->count} students in {$a->course}';
Ключи пишутся строчными латинскими буквами и цифрами, расположены по алфавиту, повторов быть не должно. Часть ключей предопределена соглашениями: pluginname название плагина, privacy:metadata описание для Privacy API, имя:право описание права, messageprovider:имя название типа уведомления. Об этих служебных строках не забывайте: их отсутствие даёт технические надписи в интерфейсе.
get_string и параметры
Вызов принимает ключ, компонент и необязательный параметр $a:
$title = get_string('pluginname', 'local_hello');
$one = get_string('notesfor', 'local_hello', fullname($USER));
$a = (object) ['count' => 12, 'course' => format_string($course->fullname)];
$many = get_string('studentcount', 'local_hello', $a);
Если параметр один, в строке пишут {$a}. Если их несколько, передают объект или массив, а в строке используют {$a->count}. Названия курсов и пользователей прогоняйте через format_string() или fullname() до подстановки: сама строка языка этого не сделает. Если строка нужна позже или в нескольких местах, создайте отложенный объект new lang_string('ключ', 'компонент'): он превратится в текст только в момент вывода.
В шаблонах Mustache это конструкция {{#str}} ключ, компонент {{/str}}, в JavaScript модуль core/str. Последний возвращает обещание, поэтому строки в нём запрашивают заранее, до отрисовки. Не вставляйте русский текст прямо в файл JS: его нельзя будет ни перевести, ни переопределить.
Русский язык и кодировка
Файлы строк должны быть в UTF-8 без BOM. BOM, невидимый символ в начале файла, выводится перед ответом сервера и ломает заголовки: пользователь видит ошибку про уже отправленные заголовки, а на AJAX-запросах приходит испорченный JSON. Редакторы вроде Блокнота Windows добавляют BOM по умолчанию. Включите в редакторе сохранение без него и проверьте командой поиска первых байтов файла.
Одинарные кавычки внутри строки в PHP экранируются обратной косой чертой, поэтому текст «Don't» записывается как 'Don\'t'. В русских текстах проще пользоваться типографскими кавычками «ёлочками», которые не конфликтуют с синтаксисом. Знак доллара перед буквой в строке с одинарными кавычками безопасен, а вот в двойных PHP попытается подставить переменную. Поэтому строки языка всегда оборачивают в одинарные кавычки.
Если плагин ставится на русскоязычный сайт, русский перевод можно положить в сам плагин, lang/ru/local_hello.php. Для публикации в каталоге moodle.org переводы идут через систему AMOS, а не через файлы плагина, о чём я пишу в статье про публикацию в каталоге. Для своего сайта удобнее хранить русские строки рядом с кодом: они переезжают вместе с плагином и версионируются в git. Если строка меняется, очищайте кэш строк: Moodle не перечитывает языковые файлы на каждом запросе.
Множественные числа и склонения
Фраза «{$a} студентов» корректна для пяти и некорректна для одного и двух. Для русского нужны три формы, и ни простая подстановка, ни английское «s» тут не помогут. Варианты решения такие:
- Формулировать так, чтобы склонение не требовалось: «Студентов: 12», «Количество: 12».
- Делать отдельные строки для форм и выбирать нужную в коде по остатку от деления на 10 и 100.
- В новых версиях Moodle использовать поддержку ICU MessageFormat в строках языка. Синтаксис и поддерживаемые версии уточняйте в разделе String API на moodledev.io, чтобы не ошибиться с деталями.
Первый способ самый надёжный, и я к нему прибегаю чаще всего: он работает на любой ветке Moodle и не оставляет «1 студентов» в отчётах.
Переопределение без правки кода
Любую строку можно изменить в «Администрирование → Язык → Настройка языка». Правки хранятся в каталоге данных в виде локального пакета, который накладывается поверх основного языка. Он переживает обновления плагина, поэтому правка названия кнопки или заголовка отчёта не требует программиста. Обратная сторона: после смены ключа в новой версии плагина старое переопределение перестаёт работать, и текст возвращается к исходному. Об этом стоит помнить при обновлениях.
Типичные ошибки
| Симптом | Причина | Решение |
|---|---|---|
Вместо текста [[ключ]] | Нет ключа в файле, неверный компонент или старый кэш | Проверить ключ и компонент, очистить кэши |
| Ошибка про отправленные заголовки, испорченный JSON | BOM или пробел перед <?php | Пересохранить в UTF-8 без BOM |
| Ломается файл языка, белый экран | Неэкранированная одинарная кавычка в строке | Экранировать или заменить на «ёлочки» |
В тексте виден {$a} | Параметр не передан третьим аргументом | Передать значение или объект с нужными полями |
| Название права показано кодом | Нет строки имя:право | Добавить строку для каждого права |
| Русская строка не применилась | Файл назван неверно (не по компоненту) или кэш не очищен | Проверить имя файла и очистить кэш строк |
| Модуль активности не находит строки | Файл назван с префиксом mod_ | Назвать файл по имени модуля без префикса |
| Ошибка проверки Code Checker по порядку ключей | Ключи идут не по алфавиту | Отсортировать |
Строки в JavaScript и в уведомлениях
Модуль core/str получает строки с сервера и кэширует их в браузере. Использовать его просто: запрашиваете строку по ключу и компоненту и получаете обещание, которое вернёт текст.
import {get_string as getString} from 'core/str';
getString('confirmdelete', 'local_hello').then((text) => {
window.alert(text);
});
Вместо запроса по одной строке за раз используйте массовый вариант, чтобы не делать много обращений к серверу. Для окон подтверждения в Moodle есть готовые модальные окна, а тексты для них берутся так же из языковых файлов. Строки, которые нужны сразу при загрузке страницы, удобнее передать из PHP параметрами в js_call_amd: тогда не придётся ждать ответа.
Числа, даты и склонения в тексте
Форматировать числа и даты вручную в строке языка нельзя. Даты выводятся через userdate(), которая учитывает язык и часовой пояс пользователя, числа через format_float() и number_format с локалью, чтобы десятичный разделитель соответствовал языку. Если строка содержит ссылку, соберите её в коде и передайте как параметр: так переводчик не сломает адрес.
Отдельно о HTML внутри строк. Допустимо хранить в строке простые теги (<strong>, <br />), но не вёрстку: тема не должна зависеть от переводчика. Если строка выводится в атрибуте, экранируйте её; если в тексте, пропустите через format_text() или s() в зависимости от источника. Всё, что пришло от пользователя, выводится только экранированным.
Как называть ключи
Единое именование экономит время при поддержке. Я придерживаюсь такого порядка: название и описание настройки имя и имя_desc, сообщения об ошибках с префиксом error, названия кнопок и действий глаголом (save, approve), подписи полей существительными. Ключ описывает назначение, а не текст: confirmdelete, а не areyousure, потому что формулировка со временем меняется, а смысл остаётся. Не склеивайте фразу из нескольких строк: порядок слов в русском и английском различается, и склейка ломает перевод.
Проверка недостающих и лишних строк
Перед релизом полезно найти ключи, которые используются в коде, но не описаны, и наоборот. Для этого достаточно двух команд в корне плагина:
grep -rhoE "get_string\('[a-z0-9_:]+', 'local_hello'" . | sort -u
grep -oE "^\$string\['[^']+'\]" lang/en/local_hello.php | sort -u
Первая показывает ключи, вызываемые из PHP, вторая определённые в файле. Сравните списки глазами или утилитой comm. Строки из шаблонов Mustache и JS ищутся отдельными шаблонами поиска. Это не замена Code Checker, но ловит самые частые пропуски за минуту.
Чек-лист локализации перед релизом
- В PHP, шаблонах и JS нет пользовательского текста в коде: только
get_string,{{#str}}иcore/str. - В английском файле есть
pluginname, описания всех прав, типов уведомлений и строка Privacy API. - Названия плановых задач и событий возвращаются через методы
get_name(), которые используютget_string. - Все файлы в UTF-8 без BOM, кавычки экранированы, ключи отсортированы.
- Склонение числительных не зависит от значения: фразы построены без склонения или обработаны явно.
- Проверка выполнена на русском и английском интерфейсе под учётной записью без прав администратора.
Мелочь, которая окупается: при разработке включайте на тестовом сайте отладку с выводом всех сообщений, и отсутствующие строки будут видны сразу. На рабочем сайте оставляйте режим по умолчанию. Если вам нужен плагин с готовым русским интерфейсом под вашу организацию, подробности на странице разработки плагинов Moodle. Следующая тема серии: страница настроек плагина, где почти все надписи тоже берутся из языковых файлов.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.