Перевод темы и плагина

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

Функции перевода

<?php
// content.php
?>
<a href="<?php the_permalink(); ?>"><?php esc_html_e('Read more', 'mytheme'); ?></a>
 
<p><?php echo esc_html__('No posts found.', 'mytheme'); ?></p>

Функция	Что делает
`__('Text', 'domain')`	Возвращает перевод
`_e('Text', 'domain')`	Выводит перевод
`esc_html__()`, `esc_html_e()`	То же с экранированием для HTML
`esc_attr__()`, `esc_attr_e()`	То же для атрибутов

Строки в коде принято писать по-английски: английский текст служит и ключом, и значением по умолчанию.

Текстовый домен

Второй аргумент — текстовый домен: уникальное имя, по которому WordPress находит файл перевода. Он совпадает с именем папки темы или плагина и указывается в заголовке:

/*
Theme Name: My Theme
Text Domain: mytheme
Domain Path: /languages
*/

Подключение перевода

// functions.php
 
add_action('after_setup_theme', function () {
    load_theme_textdomain('mytheme', get_template_directory() . '/languages');
});

Для плагина используют load_plugin_textdomain() на хуке init.

Подстановка значений

Переменную нельзя вставлять в строку перевода. Значение подставляют через sprintf():

printf(
    /* translators: %s: имя автора */
    esc_html__('Posted by %s', 'mytheme'),
    esc_html(get_the_author()),
);

Комментарий translators увидит переводчик — он объясняет, что скрывается за меткой.

Множественное число

$count = get_comments_number();
 
printf(
    esc_html(_n('%s comment', '%s comments', $count, 'mytheme')),
    number_format_i18n($count),
);

_n() выбирает форму по числу. В английском форм две, в русском три — «комментарий», «комментария», «комментариев»: их все задают в файле перевода.

Контекст

Одно английское слово может переводиться по-разному. Контекст помогает их различить:

$verb = _x('Post', 'verb: publish a comment', 'mytheme');
$noun = _x('Post', 'noun: a blog article', 'mytheme');

Файлы перевода

Файл	Что это
`mytheme.pot`	Шаблон: все строки без перевода
`ru_RU.po`	Перевод на русский в текстовом виде
`ru_RU.mo`	Тот же перевод в двоичном виде — его читает WordPress

Шаблон собирает WP-CLI:

wp i18n make-pot . languages/mytheme.pot

Затем файл .pot открывают в программе Poedit, переводят строки и сохраняют — получаются .po и .mo. Для плагина файлы называют с доменом: reading-time-ru_RU.mo.

Строки в JavaScript

wp_set_script_translations('mytheme-app', 'mytheme', get_template_directory() . '/languages');

В скрипте после этого доступна функция wp.i18n.__('Text', 'mytheme').

Частая ошибка

В функции перевода передают только строки, записанные прямо в коде. Вызов __($message, 'mytheme') или __('Hello ' . $name, 'mytheme') не попадёт в шаблон .pot: программа, которая собирает строки, не выполняет код и значение переменной не знает. Фразу переводят целиком с меткой %s, а значение подставляют потом.

Спасибо, что читаете!