Как правильно переводить строки с HTML в WordPress (без поломки разметки)

Работа с i18n в WordPress чаще всего ломается в одном месте — когда в строке перевода появляется HTML. Сначала «вроде работает», потом подключается другой язык — и разметка начинает вести себя непредсказуемо. Разберёмся, как делать правильно.

<h2><b><?php _e('<b>Calculator</b> storage cost', 'storage-calculator'); ?></b></h2>

Вариант 1 — простой и безопасный

Если порядок слов не критичен:

<h2>
    <b><?php esc_html_e('Calculator', 'storage-calculator'); ?></b>
    <?php esc_html_e('storage cost', 'storage-calculator'); ?>
</h2>

Минус: в некоторых языках нельзя поменять порядок слов.

Вариант 2 — универсальный и гибкий (через printf)

Если нужен один перевод и возможность менять порядок слов:

<h2>
<?php
printf(
    __('%1$sCalculator%2$s storage cost', 'storage-calculator'),
    '<b>',
    '</b>'
);
?>
</h2>

В .pot попадёт строка:

msgid "%1$sCalculator%2$s storage cost"
msgstr ""

В ru.po:

msgid "%1$sCalculator%2$s storage cost"
msgstr "%1$sКалькулятор%2$s стоимости хранения"

Как это работает технически

1. __() возвращает переведённую строку
2. printf() заменяет плейсхолдеры на <b> и </b>
3. Формируется корректный HTML

Итоговый результат:

<b>Калькулятор</b> стоимости хранения

Никакой магии. Только позиционная подстановка аргументов.

Дополнительная защита

Если проект крупный и есть риск, что в перевод добавят лишний HTML:

<h2>
<?php
printf(
    wp_kses_post(__('%1$sCalculator%2$s storage cost', 'storage-calculator')),
    '<b>',
    '</b>'
);
?>
</h2>

Чего делать не стоит

<?php _e('<b>Calculator</b> storage cost', 'storage-calculator'); ?>

• HTML внутри переводов
• Высокий риск поломки вложенности
• Невозможно контролировать структуру разметки
• Проблемы масштабирования проекта

Как безопасно работать с HTML в контенте WordPress

Проблемы с разметкой возникают не только при переводе интерфейсных строк. Похожие ошибки появляются при переносе статей, описаний товаров WooCommerce, блоков Elementor, Gutenberg-разметки и SEO-текстов. Один лишний тег или неправильно обработанная кавычка могут сломать ссылку, список, кнопку или форму.

Где чаще всего возникают ошибки

• HTML внутри переводимой строки. Если переводить текст вместе с тегами, легко изменить структуру ссылки или кнопки.
• Атрибуты и кавычки. Ошибка в кавычках может сломать весь фрагмент, даже если визуально текст кажется правильным.
• Скопированные стили. В описания товаров и статьи часто попадают лишние классы, inline-стили и невидимые символы.
• Elementor и Gutenberg. Их данные нельзя редактировать как обычный текст без понимания структуры блока.
• Кодировка. При массовых правках важно сохранять UTF-8 и проверять результат чтением обратно из WordPress.

Надёжный порядок работы

1. Сохранить исходный HTML или JSON блока перед изменениями.
2. Отделить переводимый текст от тегов, ссылок, shortcode и переменных.
3. После вставки проверить страницу визуально, а не только в редакторе.
4. Проверить ссылки, списки, кнопки, изображения, мобильную версию и микроразметку.
5. Для массовых правок использовать файлы в UTF-8 и read-back проверку, чтобы не получить битую кириллицу.

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