Как перевести плагин WordPress (Пошаговое руководство)

Вы нашли идеальный плагин WordPress для своего проекта. Он делает именно то, что вам нужно, отзывы восторженные, а затем вы активируете его и понимаете, что каждая кнопка, метка и сообщение об ошибке на английском языке. Ваши посетители из Германии, Франции или Японии вот-вот столкнутся со стеной текста, который они не смогут прочитать.

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

Это руководство покажет вам, как перевести плагин WordPress от начала до конца: найти текстовый домен и папку языков, получить или сгенерировать шаблон .pot, создать правильно названные файлы .po и .mo и разместить их там, где WordPress будет надежно их загружать. Мы также рассмотрим один тип плагинов, который этот подход не может полностью перевести, чтобы вы не тратили часы на борьбу с невозможным случаем.

Как найти файлы перевода плагина?

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

Определение папки языков и текстового домена

Откройте каталог плагина по адресу wp-content/plugins/your-plugin/ и найдите подпапку /languages. Внутри вы обычно найдете файл .pot — пустой шаблон, содержащий все переводимые строки.

Чтобы подтвердить текстовый домен, откройте основной PHP-файл плагина и посмотрите на его блок заголовка:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Здесь текстовый домен — awesome-plugin. Это значение критически важно, потому что ваши файлы перевода должны включать его в свои имена, иначе WordPress никогда не сопоставит их с плагином. Вы также увидите его в каждом вызове строки по всему коду:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Этот второй аргумент, awesome-plugin, снова является текстовым доменом. Каждая строка, использующая его, может быть переведена вашим каталогом. Если строка в интерфейсе плагина отсутствует в этой обертке, например, разработчик жестко закодировал echo 'Save' без __(), то эта строка вообще не подлежит переводу, и никакой файл .po не сможет до нее добраться. Большинство авторитетных плагинов правильно оборачивают все, но если вы заметили одну или две упрямые строки, которые отказываются переводиться, то отсутствующая обертка Gettext в исходном коде является вероятной причиной.

Быстрый способ оценить, действительно ли плагин готов к переводу, — это проверить его список в каталоге WordPress.org, который показывает процент перевода и ссылки на шаблон /languages. Плагин с активным проектом перевода гораздо чаще имеет чистые, полностью обернутые строки, чем заброшенный.

Что делать, если у плагина нет файла POT?

Некоторые плагины поставляются без шаблона .pot. Если папка /languages пуста или отсутствует, вам нужно сгенерировать шаблон самостоятельно, просканировав исходный код на предмет переводимых строк.

Стандартным инструментом для этого является WP-CLI, который извлекает каждый вызов Gettext в новый .pot.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Эта команда обходит PHP- и JavaScript-файлы плагина, находит все вызовы __(), _e(), _n() и связанные с ними, и записывает полный шаблон. Если вы предпочитаете графический путь, Poedit Pro может сканировать исходный код таким же образом. В любом случае, результатом является файл .pot, содержащий все исходные строки с пустыми переводами, готовый к превращению в настоящий языковой файл.

Создание собственного шаблона имеет скрытое преимущество: оно захватывает строки, которые оригинальный разработчик мог забыть включить в поставляемый .pot. Плагины быстро развиваются, и шаблон, поставляемый с версией 2.1, может не содержать строк, добавленных в 2.4. Повторное генерирование из текущего исходного кода гарантирует, что ваш каталог отражает то, что плагин фактически отображает сегодня, а не то, что он отображал два выпуска назад. Если вы поддерживаете переводы для плагина в течение длительного времени, повторный запуск make-pot после каждого крупного обновления является надежной привычкой.

Создание файлов PO и MO с правильным именем

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

Формула имени файла

Для переводов плагинов шаблон такой: text-domain-locale. Так, для текстового домена awesome-plugin, переведенного на немецкий, файлы должны быть названы:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

Код локали — это код языка сайта WordPress: de_DE для немецкого, fr_FR для французского, es_ES для испанского, pt_BR для бразильского португальского. Ошибитесь в локали, и WordPress молча пропустит ваш файл. Вы создаете их из шаблона .pot в редакторе вроде Poedit, который автоматически компилирует бинарный .mo при сохранении. Если вы новичок в этом редакторе, полное руководство по Poedit пошагово объясняет создание перевода из шаблона.

Куда поместить файлы, чтобы обновления их не стерли

Есть два возможных местоположения, и выбор правильного имеет значение.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Всегда используйте wp-content/languages/plugins/. WordPress сначала проверяет этот каталог переопределений, и поскольку он находится вне папки плагина, обновление плагина никогда не затрагивает ваши переводы. Файлы, помещенные в собственную папку плагина, будут перезаписаны в момент установки новой версии.

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

Как WordPress загружает ваш перевод

Плагин, готовый к переводу, сообщает WordPress загрузить свой каталог, вызывая load_plugin_textdomain() во время инициализации:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Для большинства современных плагинов на WordPress 4.6 и более поздних версий вам не нужно этого касаться. WordPress автоматически загружает переводы из wp-content/languages/plugins/, если имя вашего файла и локаль сайта совпадают. Если ваш готовый перевод все еще не появляется, причина почти всегда заключается в несоответствии имени файла, устаревшем .mo или языке сайта, установленном с неправильной локалью. Наше руководство по устранению неполадок, из-за которых переводы не отображаются в WordPress, разбирает каждую из этих точек отказа.

Плагины, которые хранят строки в базе данных

Вот важное ограничение. Подход Gettext переводит только строки, которые находятся в коде плагина. Некоторые плагины, особенно конструкторы форм, конструкторы страниц и расширения для электронной коммерции, позволяют создавать контент (метки форм, атрибуты продуктов, пользовательские сообщения), который сохраняется в базе данных WordPress. Эти строки являются данными, сгенерированными пользователем, и не являются частью .pot, поэтому файл .po не может до них добраться. Для контента базы данных вам нужен многоязычный плагин, такой как WPML или Polylang, или собственная функция перевода строк плагина. Всегда проверяйте, находится ли данная строка в коде или в базе данных, прежде чем предполагать, что файл .po может ее исправить.

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

Масштабный перевод без рутины

Перевести один плагин на один язык вручную — это выполнимо. Перевод его на десять языков или перевод целого набора плагинов для клиентского сайта превращается в дни повторяющейся работы, и каждое ручное редактирование рискует испортить заполнитель, такой как %s или %1$s, и нарушить вывод.

Именно здесь облачный рабочий процесс меняет дело. Загрузите файл .po или .pot плагина в SimplePoTranslate, выберите целевые языки, и ИИ, учитывающий контекст, переведет весь каталог, а Блокировка синтаксиса зафиксирует каждый заполнитель, HTML-тег и токен кода, чтобы ничто не сломалось. Умная пакетная обработка обрабатывает большие каталоги за один проход, и вы загружаете ZIP-архив, содержащий файлы .po, .mo, .json, .php и .xliff вместе, правильно отформатированные и готовые к размещению в wp-content/languages/plugins/. Он работает полностью в облаке, поэтому нет установки на рабочий стол и нет раздувания на вашем сайте.

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

Используйте ручной путь, когда у вас есть один плагин и один язык. Используйте облако, когда вам нужно много языков, быстро, без ущерба для безопасности заполнителей.

Готовы перевести свой плагин WordPress на все языки, на которых говорит ваша аудитория, не нарушая ни одной переменной? Попробуйте SimplePoTranslate бесплатно — кредитная карта не требуется. Бесплатный тариф позволяет перевести ваш первый файл .po плагина за считанные минуты, с включенной блокировкой синтаксиса для каждой строки.