Перейти к содержимому
M
Все статьи
Разработка 9 мин чтения

Локализация плагина Moodle: файлы языка, get_string и типичные ошибки с русским

Как локализовать плагин Moodle: lang/en, get_string, русские строки, параметры и множественные числа, переопределение. Чек-лист и таблица типичных ошибок.

Как локализовать плагин Moodle: lang/en, get_string, русские строки, параметры и множественные числа, переопределение. Чек-лист и таблица типичных ошибок.

Локализация в 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 студентов» в отчётах.

Переопределение без правки кода

Любую строку можно изменить в «Администрирование → Язык → Настройка языка». Правки хранятся в каталоге данных в виде локального пакета, который накладывается поверх основного языка. Он переживает обновления плагина, поэтому правка названия кнопки или заголовка отчёта не требует программиста. Обратная сторона: после смены ключа в новой версии плагина старое переопределение перестаёт работать, и текст возвращается к исходному. Об этом стоит помнить при обновлениях.

Типичные ошибки

СимптомПричинаРешение
Вместо текста [[ключ]]Нет ключа в файле, неверный компонент или старый кэшПроверить ключ и компонент, очистить кэши
Ошибка про отправленные заголовки, испорченный JSONBOM или пробел перед <?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. Следующая тема серии: страница настроек плагина, где почти все надписи тоже берутся из языковых файлов.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.