Автоматизация перевода пользовательских шорткодов в WordPress: пошаговое руководство

Диагностика проблемы с переводом шорткодов в WordPress

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

Основные признаки проблемы:

• Текст, выводимый шорткодом, не переводится при переключении языка.
• Плагины мультиязычности (например, WPML, Polylang) не видят строк из шорткода для перевода.
• Автоматический автоперевод через API не охватывает содержимое шорткода.

Пошаговое решение: как сделать шорткод переводимым

1. Используйте функцию __() или _e() для оборачивания строк

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

function my_shortcode_func() {
    return __('Привет, мир!', 'my-text-domain');
}
add_shortcode('myshort', 'my_shortcode_func');

Без этого WordPress не сможет распознать строку для перевода.

2. Зарегистрируйте домен текста в плагине или теме

Для работы переводов нужно, чтобы домен текста был зарегистрирован. В плагинах обычно это делается через load_plugin_textdomain(), в темах — через load_theme_textdomain(). Например:

function my_plugin_load_textdomain() {
    load_plugin_textdomain('my-text-domain', false, dirname(plugin_basename(__FILE__)) . '/languages');
}
add_action('plugins_loaded', 'my_plugin_load_textdomain');

3. Добавьте строки шорткода в POT-файл для перевода

Чтобы переводы работали, строки должны быть добавлены в файл переводов (POT). Для этого используйте инструменты, например Poedit или WP-CLI:

wp i18n make-pot ./path-to-plugin languages/my-plugin.pot

В POT-файл попадут все строки, обернутые в функции локализации.

4. Используйте фильтры автоперевода для динамических параметров шорткода

Если ваш шорткод принимает параметры с текстом, который нужно перевести (например, атрибут title), добавьте фильтр, который позволит автопереводу обработать эти значения. Например, для WPML это может быть:

function my_shortcode_atts_translation($atts) {
    if (isset($atts['title'])) {
        $atts['title'] = apply_filters('wpml_translate_single_string', $atts['title'], 'Shortcode', 'Title Attribute');
    }
    return $atts;
}
add_filter('shortcode_atts_myshort', 'my_shortcode_atts_translation');

5. Используйте хуки автоперевода для интеграции с автопереводчиками

Для автоматизации перевода через API (DeepL, Google Translate) используйте хуки плагинов автоперевода, чтобы передавать текст шорткода на перевод. Пример для WPML:

add_filter('wpml_auto_translate', function($translation, $original, $lang) {
    // Проверка, что текст из шорткода
    if (strpos($original, '[myshort') !== false) {
        // Логика автоперевода
    }
    return $translation;
}, 10, 3);

Проверка результата после внедрения

Чтобы убедиться, что шорткод корректно переводится, выполните следующие проверки:

• Переключите язык на сайте и проверьте, что текст шорткода меняется.
• Посмотрите в интерфейсе перевода (WPML String Translation или аналог) — строки из шорткода должны появиться.
• Если используется автоперевод, проверьте, что текст шорткода автоматически переводится при добавлении нового языка.

Для быстрого теста можно временно заменить текст шорткода на уникальную строку и проверить ее наличие в переводах.

Частые ошибки и как их исправить

• Текст не обернут в функции локализации
  Исправление: обязательно использовать __(), _e(), _x() для всех текстов.
• Не зарегистрирован текстовый домен
  Исправление: вызвать load_plugin_textdomain() или load_theme_textdomain() в нужное время.
• Строки не попадают в POT-файл
  Исправление: обновить POT-файл через WP-CLI или Poedit, убедиться, что сканируются все файлы.
• Перевод параметров шорткода не настроен
  Исправление: применить фильтры для атрибутов шорткода, чтобы их переводить через мультиязычные плагины.
• Автоперевод не работает для шорткода
  Исправление: добавить интеграцию с автопереводчиком через соответствующие хуки.

Практические советы по безопасности и производительности

• По возможности избегайте вывода больших объемов текста напрямую в шорткоде — используйте идентификаторы и загружайте переводы из базы.
• Кэшируйте результаты шорткода с переведенным текстом, чтобы снизить нагрузку.
• Внимательно проверяйте входящие параметры шорткода на безопасность (например, экранирование вывода), особенно если они проходят через автоперевод.
• Не храните переводы в опциях или transient без необходимости — лучше полагаться на стандартные механизмы локализации WordPress.

Сравнение вариантов перевода шорткодов