Как добавить поддержку мультиязычности в собственном плагине WordPress

При разработке собственного плагина для WordPress важно обеспечить его готовность к использованию на многоязычных сайтах. Это не только улучшает опыт пользователей из разных стран, но и значительно расширяет аудиторию вашего продукта. В этой статье подробно разберём, как грамотно добавить поддержку мультиязычности в собственный плагин WordPress с примерами кода и рекомендациями по работе с переводами.

Почему важно делать плагин мультиязычным

WordPress — глобальная платформа, и многие сайты работают сразу на нескольких языках. Если ваш плагин не поддерживает локализацию, пользователи увидят интерфейс и сообщения только на одном языке, что негативно скажется на восприятии и удобстве. Правильная реализация мультиязычности позволяет:

Переводить интерфейс плагина и его сообщения на любой язык;
Интегрироваться с системами перевода и популярными плагинами (например, Polylang, WPML);
Повышать рейтинг плагина в репозитории и на сторонних площадках за счёт доступности для международной аудитории;
Упрощать поддержку и модификацию, так как тексты отделены от кода.

Основы локализации WordPress-плагинов

В основе мультиязычности лежит механизм локализации (localization) и интернационализации (internationalization). Это означает, что все строки текста в плагине должны быть обёрнуты в специальные функции, позволяющие загружать переводы из файлов .mo и .po.

Для плагинов WordPress используются функции __(), _e(), _x(), esc_html__() и другие. Они принимают строку и домен текстового пространства (text domain) — уникальный идентификатор вашего плагина для переводов.

Пример:

echo __('Hello, world!', 'wptranslate');
_e('Settings saved.', 'wptranslate');

Здесь 'wptranslate' — это домен текстов, обычно совпадает с названием папки плагина.

Шаг 1. Объявляем домен текстов и загружаем переводы

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

function wptranslate_load_textdomain() {
    load_plugin_textdomain(
        'wptranslate',
        false,
        dirname(plugin_basename(__FILE__)) . '/languages/'
    );
}
add_action('plugins_loaded', 'wptranslate_load_textdomain');

Здесь мы указываем путь к папке /languages/, где будут храниться .mo-файлы с переводами.

Шаг 2. Оборачиваем все строки в функции локализации

Весь выводимый текст в плагине — заголовки, описания, сообщения об ошибках, подсказки — должен быть обёрнут в функции перевода. Например, вместо:

echo 'Настройки сохранены';

пишем:

echo __('Настройки сохранены', 'wptranslate');

Или если нужно сразу вывести текст с экранированием HTML:

esc_html_e('Ошибка при сохранении настроек', 'wptranslate');

Если строка требует контекста, чтобы избежать неоднозначностей, используйте _x():

$label = _x('Post', 'noun', 'wptranslate');

Шаг 3. Создаём файлы перевода (.pot, .po, .mo)

Для удобства работы с переводами используйте программы, например, Poedit или плагин Loco Translate. Сначала создайте шаблон перевода (.pot) с помощью:

wp i18n make-pot . languages/wptranslate.pot

Далее, на базе .pot создаются .po-файлы для каждого языка (например, ru_RU.po, en_US.po). После перевода они компилируются в бинарные .mo-файлы, которые WordPress загружает автоматически.

Шаг 4. Поддержка мультиязычности в админке и на фронтенде

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

function wptranslate_settings_page() {
    ?>
    <h1><?php esc_html_e('Настройки плагина WPTranslate', 'wptranslate'); ?></h1>
    <form method="post" action="options.php">
        <?php settings_fields('wptranslate_options_group'); ?>
        <label for="wptranslate_option">
            <?php _e('Введите значение', 'wptranslate'); ?>:
            <input type="text" name="wptranslate_option" id="wptranslate_option" value="<?php echo esc_attr(get_option('wptranslate_option')); ?>">
        </label>
        <?php submit_button(); ?>
    </form>
    <?php
}

Таким образом, вся админка будет готова к переводу.

Шаг 5. Интеграция с плагинами мультиязычности (Polylang, WPML)

Если ваш плагин создаёт свои типы записей, таксономии или пользовательские строки, важно учитывать их перевод. Для этого:

Регистрируйте типы записей с параметром 'show_in_rest' => true, так они будут доступны для WPML и Polylang.
Добавляйте строки с помощью функции pll_register_string() (Polylang) или API WPML для перевода настроек и других пользовательских текстов.

Пример регистрации строки для Polylang:

if (function_exists('pll_register_string')) {
    pll_register_string('Welcome message', __('Добро пожаловать!', 'wptranslate'), 'WPTranslate');
}

Практический пример: подключение локализации в плагине WPTranslate

Объединим основные шаги в одном примере.

/**
 * Plugin Name: WPTranslate
 * Text Domain: wptranslate
 * Domain Path: /languages/
 */

// Загружаем переводы
function wptranslate_load_textdomain() {
    load_plugin_textdomain('wptranslate', false, dirname(plugin_basename(__FILE__)) . '/languages/');
}
add_action('plugins_loaded', 'wptranslate_load_textdomain');

// Пример вывода строки с переводом
function wptranslate_show_welcome() {
    echo '<p>' . esc_html__('Добро пожаловать в WPTranslate!', 'wptranslate') . '</p>';
}

// Использование в шорткоде
add_shortcode('wptranslate_welcome', 'wptranslate_show_welcome');

Советы по работе с переводами в плагинах

Используйте уникальный текстовый домен, совпадающий с названием плагина или его папки.
Не вставляйте переводы напрямую в базу данных, используйте функции WordPress для интернационализации и локализации.
Регулярно обновляйте .pot-файл и переводы при добавлении новых строк.
Тестируйте плагин на разных языках и с популярными плагинами мультиязычности.
Документируйте строки, требующие перевода, чтобы другие переводчики быстрее ориентировались.

Заключение

Добавление поддержки мультиязычности в собственный плагин WordPress — это обязательный этап для расширения аудитории и повышения качества продукта. С помощью стандартных функций интернационализации, правильной организации файлов переводов и интеграции с популярными плагинами мультиязычности вы сделаете плагин удобным и востребованным на международных сайтах.

Для удобства управления переводами рекомендуем использовать Loco Translate — мощный плагин для редактирования переводов прямо из админки WordPress.