Как установить и настроить полное i18n в WordPress для тем и плагинов

Одной из важных задач при разработке тем и плагинов для WordPress является обеспечение поддержки многоязычности через правильную реализацию i18n (internationalization). В этой статье мы подробно рассмотрим, как грамотно подключить и использовать функции интернационализации WordPress, чтобы ваша тема или плагин были готовы к переводу на любой язык.

Что такое i18n и зачем она нужна в WordPress

Термин i18n — это сокращение от слова internationalization, где 18 — количество букв между первой и последней. В контексте WordPress это означает подготовку кода темы или плагина к переводу: все строки должны быть вынесены в отдельные файлы переводов, чтобы их можно было легко локализовать и менять язык без правки исходников.

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

Основные функции WordPress для i18n

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

• __() — возвращает переведённую строку.
• _e() — сразу выводит переведённую строку.
• _x() — добавляет контекст к переводу, чтобы избежать неоднозначностей.
• esc_html__() и esc_html_e() — для безопасного вывода HTML.
• _n() — для множественного числа (pluralization).

Пример использования в теме:

<?php echo wplangs__myplugin__('Hello, world!', 'myplugin-textdomain'); ?>

Здесь важно заменить myplugin-textdomain на ваш текстовый домен.

Регистрация текстового домена и загрузка переводов

Чтобы WordPress понимал, откуда брать переводы, нужно зарегистрировать текстовый домен и загрузить файлы .mo и .po.

Для темы в файле functions.php добавьте:

function wplangs_load_theme_textdomain() {
    load_theme_textdomain('wplangs-theme', get_template_directory() . '/languages');
}
add_action('after_setup_theme', 'wplangs_load_theme_textdomain');

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

function wplangs_load_plugin_textdomain() {
    load_plugin_textdomain('wplangs-plugin', false, dirname(plugin_basename(__FILE__)) . '/languages');
}
add_action('plugins_loaded', 'wplangs_load_plugin_textdomain');

Папка languages должна содержать файлы переводов в формате ru_RU.mo и ru_RU.po.

Создание файлов перевода .po и .mo

Для генерации файлов перевода удобно использовать программу Poedit или плагин Loco Translate. Процесс:

1. Соберите все строки, обёрнутые функциями i18n, в файл POT.
2. Откройте POT в Poedit, переведите строки.
3. Сохраните .po и сгенерируйте .mo.

Эти файлы загружаются в папку /languages темы или плагина.

Как сделать динамический выбор языка на сайте

Для фронтенда часто нужно дать пользователю возможность переключать язык. Если тема уже поддерживает i18n, то переключение языка обычно делается через плагин многоязычности (например, Polylang или WPML), но можно реализовать и самостоятельно.

Пример простой функции для смены языка в URL и установки локали:

function wplangs_set_locale_by_url() {
    if (isset($_GET['lang'])) {
        $lang = sanitize_text_field($_GET['lang']);
        switch ($lang) {
            case 'ru_RU':
            case 'en_US':
                switch_to_locale($lang);
                break;
        }
    }
}
add_action('init', 'wplangs_set_locale_by_url');

Этот код переключит локаль в зависимости от параметра ?lang=ru_RU. Однако для полноценной работы потребуется интеграция с переводами и кэшированием.

Практический пример: интернационализация функции в плагине

Рассмотрим пример оформления строки с динамическим числом и правильной формой множественного числа:

function wplangs__myplugin_get_items_count_message($count) {
    return sprintf(
        _n('%s товар', '%s товара', $count, 'wplangs-plugin'),
        number_format_i18n($count)
    );
}

Здесь _n() выберет правильную форму слова в зависимости от числа, а number_format_i18n() отформатирует число под локаль.

Советы по отладке и проверке переводов

Чтобы проверить, что переводы работают, можно:

• Поменять язык сайта в админке WordPress (Настройки > Общие).
• Использовать плагин Loco Translate для редактирования и проверки переводов прямо в админке.
• Убедиться, что функции загрузки текстового домена вызываются в нужное время (after_setup_theme для тем и plugins_loaded для плагинов).

Использование плагина Clearfy Pro для оптимизации i18n

Плагин Clearfy Pro помогает оптимизировать работу сайта, в том числе улучшая загрузку языковых файлов и отключая ненужные локализации, что ускоряет работу и уменьшает нагрузку. Рекомендуется использовать его вместе с грамотной организацией i18n.

Заключение

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