Локализация WordPress плагина: пошаговое руководство по переводу с Text Domain, Poedit и load_plugin_textdomain

Создавая плагин для WordPress, важно позаботиться о его локализации — то есть возможности перевести интерфейс на разные языки. Без этого даже качественный функционал будет выглядеть «сыровато»: кнопки, метки и текстовые элементы останутся на английском, тогда как сайт и админка уже переведены. В этой статье разберём, как добавить поддержку перевода в ваш WordPress плагин с помощью функций __(), _e(), программы Poedit и функции load_plugin_textdomain().

1. Подготовка строк к переводу

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

• __() — возвращает переведённую строку;
• _e() — выводит переведённую строку сразу в HTML.

Например:

echo __( 'Price', 'ale-property' );
_e( 'For sale', 'ale-property' );

Вторым параметром всегда указывается Text Domain — уникальный идентификатор вашего плагина. Он должен совпадать с названием папки плагина (например, ale-property).

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

'labels' => array(
    'name'          => __( 'Properties', 'ale-property' ),
    'singular_name' => __( 'Property', 'ale-property' ),
)

2. Создание папки для языковых файлов

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

/wp-content/plugins/ale-property/languages/

Создайте папку languages (или lang, если предпочитаете короткое имя). Именно сюда будут сохраняться .po и .mo файлы.

3. Настройка Poedit и генерация файлов перевода

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

1. Откройте Poedit и выберите «Создать новый перевод».
2. Укажите язык по умолчанию (например, английский — English (en_US)).
3. Сохраните файл в папку languages под именем, соответствующим вашему домену:
   ale-property.pot
4. В настройках проекта укажите путь до исходников (например, ../ — чтобы сканировать весь плагин).
5. В разделе «Ключевые слова» добавьте функции перевода: __ _e
6. Нажмите «Извлечь из исходного кода» — Poedit найдёт все строки, заключённые в эти функции, и создаст базовый шаблон перевода.

4. Создание перевода для конкретного языка

Теперь, имея .pot файл, можно создать конкретный перевод.

1. В Poedit выберите «Создать перевод» и выберите язык, например Русский (ru_RU).
2. Переведите найденные строки.
3. Сохраните файл как
   ale-property-ru_RU.po
   Poedit автоматически создаст бинарный файл ale-property-ru_RU.mo — именно его WordPress будет использовать при загрузке перевода.

Важно: имя файла должно соответствовать шаблону
text-domain–locale.po
например:
ale-property-ru_RU.po

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

WordPress должен знать, где искать ваши языковые файлы. Для этого добавляется функция load_plugin_textdomain() — обычно в основном файле плагина.

function ale_property_load_textdomain() {
    load_plugin_textdomain(
        'ale-property',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages/'
    );
}
add_action( 'plugins_loaded', 'ale_property_load_textdomain' );

Рекомендуется использовать хук plugins_loaded, так как он вызывается после инициализации всех плагинов и до загрузки переводов.

6. Проверка перевода

Теперь можно активировать плагин и сменить язык сайта в админке на Русский (Settings → General → Site Language).

Если всё настроено правильно, все строки, переведённые в Poedit, автоматически подставятся.
При возврате языка обратно на английский интерфейс снова станет оригинальным.

7. Частые ошибки при локализации

1. ❌ Неправильный текст-домен — должен совпадать с папкой плагина и именем файлов перевода.
2. ❌ Неверное имя файла перевода — порядок должен быть textdomain-locale.po.
3. ❌ Функция загружает переводы слишком рано — используйте plugins_loaded, а не init.
4. ❌ Нет кодировки UTF-8 в Poedit — обязательно проверьте параметр в настройках проекта.

8. Дополнительная настройка для WordPress.org

Если вы публикуете плагин в официальном репозитории, укажите путь к переводам в заголовке плагина:

/*
Plugin Name: Ale Property
Text Domain: Ale -property
Domain Path: /languages
*/

Это нужно, чтобы WordPress.org мог автоматически синхронизировать переводы через GlotPress.

Заключение

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

Кратко алгоритм:

1. Оберните все строки в __() и _e().
2. Создайте папку /languages/.
3. Сгенерируйте .pot файл через Poedit.
4. Создайте переводы .po и .mo.
5. Подключите load_plugin_textdomain() на хук plugins_loaded.

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

Автор: Александр Сокирка

Занимаюсь веб разработкой с 2007 года. Имею большой опыт в веб-дизайне и разработке сайтов. Являюсь автором YouTube канала Быть Программистом. Основатель бренда Aletheme и автор тем для WordPress на маркетплэйсе Envato. С 2017 года занимаюсь обучением людей желающим стать программистами. Мои обучающие программы можно найти на этом сайте или на Udemy.