Как создать файл .pot для темы или плагина
Вы только что закончили плагин WordPress, которым хотите поделиться со всем миром. Код работает, функции надежны, и кто-то из Германии присылает письмо с вопросом, как перевести его на немецкий. Вы указываете им на папку languages и понимаете, что там ничего нет. Ни шаблона, ни строк, ни возможности для переводчика даже узнать, что нужно переводить. Ваш плагин технически «готов к переводу» только по названию.
Каждый переводимый проект WordPress начинается с одного файла: шаблона .pot. Прежде чем кто-либо сможет создать немецкую, французскую или японскую версию, вы должны создать POT-файл, который перечисляет каждую видимую для пользователя строку в вашем коде. Пропустите этот шаг, и переводчики будут вынуждены читать ваш исходный код построчно, гадая, какие строки вообще предназначены для отображения.
Это руководство описывает две части работы: подготовку исходного кода, чтобы строки были обнаруживаемы, а затем генерацию самого .pot с помощью трех различных инструментов. Мы будем использовать WP-CLI, Poedit и устаревший подход makepot/grunt, с реальными командами, которые вы можете скопировать. К концу вы получите чистый шаблон, готовый для любого переводчика.
Шаг первый: Отметьте свои строки как переводимые
Прежде чем вы сможете создать POT-файл, каждая строка, которую пользователь может увидеть, должна быть обернута в функцию Gettext. Сканер может извлекать только те строки, которые он распознает, и он распознает их по этим вызовам функций — простые строковые литералы для него невидимы.
WordPress предоставляет семейство функций локализации, каждая для немного отличающегося контекста:
// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );
// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );
// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );
// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );
Второй аргумент в каждом вызове — 'my-plugin' — это текстовый домен. Он группирует все строки плагина или темы под одним пространством имен, чтобы WordPress знал, какой файл .mo для них загружать. Каждая переводимая строка в вашем проекте должна иметь один и тот же текстовый домен, иначе некоторые строки никогда не будут переведены.
Используйте _x() всякий раз, когда слово неоднозначно. Английское «Post» может быть существительным или глаголом, и многие языки переводят их по-разному. Контекстные строки позволяют переводчикам различать их. И используйте варианты esc_html__() и esc_attr__() всякий раз, когда переведенная строка выводится в HTML, чтобы вы оставались в безопасности и были локализованы одновременно.
Есть несколько привычек, которые позволяют вашим строкам быть извлекаемыми. Всегда передавайте простой строковый литерал в качестве первого аргумента — никогда переменную или конкатенацию вроде __( 'Hello ' . $name, 'my-plugin' ), потому что сканер читает исходный текст статически и не может разрешать значения во время выполнения. Для предложений с числом используйте _n(), чтобы формы множественного числа были правильно захвачены, а для предложений с динамическим значением используйте sprintf() вокруг заполнителя, такого как %s, а не склеивайте строки. Последовательность здесь — это то, что делает следующий шаг — генерацию шаблона — дающим полный, пригодный для использования результат.
Шаг второй: Объявите текстовый домен в вашем заголовке
WordPress нужны два поля заголовка, чтобы знать, где находятся ваши переводы: Text Domain и Domain Path. Установите их в главном файле вашего плагина или в style.css вашей темы, и WordPress автоматически загрузит правильный .mo во время выполнения.
<?php
/**
* Plugin Name: My Plugin
* Description: A perfectly localized WordPress plugin.
* Version: 1.0.0
* Requires at least: 6.4
* Text Domain: my-plugin
* Domain Path: /languages
*/
Text Domain должен соответствовать строке, которую вы передали каждому вызову __() и _e() — здесь my-plugin. Domain Path сообщает WordPress, какая подпапка содержит файлы перевода, относительно корня плагина или темы. По соглашению это /languages, и именно там должен находиться ваш сгенерированный .pot.
Когда строки обернуты и заголовок объявлен, ваш код готов к сканированию. Более широкая картина подготовки проекта к переводу — включая темы, которые не являются вашими собственными — рассматривается в статье Как локализовать любую тему WordPress, даже если вы не разработчик.
Как сгенерировать файл .pot? Три метода
Вы генерируете .pot, запуская сканер по вашему исходному коду, который находит каждый вызов Gettext и записывает строки в шаблон. Вот три надежных способа сделать это, от современного стандартного до устаревшего подхода.
Метод 1: WP-CLI (рекомендуется)
Официальный, современный способ создания POT-файла — это WP-CLI с командой i18n. Он поставляется как часть основного набора инструментов WordPress, понимает строки PHP и JavaScript и создает соответствующий стандартам шаблон в одной строке.
# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot
# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules
Первый аргумент — это исходный каталог (. для текущей папки), а второй — путь вывода. WP-CLI проходит по вашим файлам, извлекает каждую обернутую строку, записывает исходный файл и номер строки в качестве комментария и записывает .pot. Это быстро, поддается скриптам и является правильным выбором для любого серьезного проекта.
Сгенерированный шаблон включает полезные метаданные, которые вы можете настроить с помощью дополнительных флагов. Передайте --headers, чтобы установить имя проекта, версию и контактный адрес переводчиков, чтобы заголовочный блок .pot был заполнен правильно, а не оставался в виде заполнителей. WP-CLI также автоматически извлекает строки JavaScript из вызовов wp_set_script_translations(), что важно для современных блочных тем и плагинов Gutenberg, где половина видимого пользователю текста находится в JavaScript, а не в PHP. Одна команда охватывает оба мира.
Метод 2: Poedit (графический)
Если вы предпочитаете настольное приложение, Poedit может сканировать ваш исходный код и генерировать шаблон через свой интерфейс. Откройте Poedit, выберите создание нового перевода из POT или прямое сканирование источников, укажите папку вашего проекта и настройте ключевые слова источника (__, _e, _x, esc_html__) в свойствах каталога.
Функции сканирования исходного кода и генерации .pot в Poedit доступны в его Pro-версии, но рабочий процесс удобен для разработчиков, которые предпочитают кликать, а не вводить команды. Это также надежный редактор для последующего этапа перевода. Poedit и несколько других настольных вариантов сравниваются в статье Топ-5 бесплатных инструментов для редактирования и перевода PO-файлов на Mac и Windows.
Метод 3: makepot / grunt (устаревший)
До появления WP-CLI стандартным инструментом был скрипт makepot.php из репозитория WordPress i18n-tools, часто интегрированный в задачу сборки Grunt с помощью grunt-wp-i18n. Вы все еще можете встретить его в старых плагинах и темах.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Он работает, но не поддерживается по сравнению с WP-CLI и медленнее в настройке. Используйте его только в том случае, если вы поддерживаете устаревший проект, который уже зависит от него; для всего нового отдавайте предпочтение wp i18n make-pot.
Обновляйте шаблон по мере изменения кода
Файл .pot — это снимок ваших строк в определенный момент. Каждый раз, когда вы добавляете новую функцию, меняете метку или исправляете опечатку в видимой строке, шаблон устаревает, и переводчики упускают новые формулировки.
Включите перегенерацию в свой процесс выпуска. Повторно запускайте wp i18n make-pot перед каждым изменением версии, затем объединяйте обновленный шаблон с существующими переводами с помощью wp i18n update-po или msgmerge, чтобы переводчики сохраняли свою готовую работу и видели только новые пробелы. Относитесь к .pot как к артефакту сборки, который вы перегенерируете, а не как к файлу, который вы редактируете вручную.
Устаревший шаблон приводит к незаметному, но досадному сбою: новые строки появляются на английском языке даже на «полностью переведенном» сайте, потому что их никогда не было в .pot, с которым работал переводчик. Обнаружить это так же просто, как включить перегенерацию в ваш процесс сборки, чтобы шаблон никогда не отставал от кода. Некоторые команды добавляют проверку CI, которая прерывает сборку, если перегенерация .pot приводит к различиям, гарантируя, что зафиксированный шаблон всегда соответствует текущему исходному коду.
Как только переводчики возвращают готовые файлы .po, их все равно необходимо скомпилировать в бинарные .mo, которые фактически загружает WordPress — и если вы предпочтете пропустить весь цикл скачивания-перевода-перекомпиляции, облачный инструмент может справиться с этим от начала до конца. SimplePoTranslate принимает ваш .pot напрямую, переводит его с помощью контекстно-зависимого ИИ, который понимает значение каждой строки в вашем интерфейсе, и возвращает один ZIP-архив с уже созданными и названными .po, .mo и другими файлами. Его блокировка синтаксиса замораживает заполнители, такие как %s и %1$s, так что ваши переменные никогда не нарушатся при переводе.
Подведение итогов
Чтобы правильно создать POT-файл, сначала сделайте ваш код обнаруживаемым — оберните каждую видимую строку в __(), _e(), _x() или вариант с экранированием, все они должны использовать один текстовый домен, и объявите этот домен, а также Domain Path в вашем заголовке. Затем сгенерируйте шаблон с помощью WP-CLI для новых проектов, Poedit, если вы предпочитаете графический интерфейс, или makepot только при поддержке устаревшего кода.
Генерируйте рано, перегенерируйте часто и никогда не позволяйте вашему шаблону отставать от кода. Актуальный .pot — это разница между плагином, который действительно готов для мира, и тем, который только претендует на это.
Готовы превратить ваш шаблон
.potв готовые переводы без ручной компиляции? Попробуйте SimplePoTranslate бесплатно — кредитная карта не требуется. Загрузите свой шаблон на бесплатном уровне и скачайте готовые к отправке файлы перевода за считанные минуты.