Як створити файл .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 безпосередньо, перекладає його за допомогою AI, що враховує контекст (Context-Aware AI), який розуміє значення кожного рядка у вашому інтерфейсі, і повертає єдиний ZIP-архів з вже побудованими та названими файлами .po, .mo та іншими. Його Syntax Locking заморожує заповнювачі, такі як %s та %1$s, щоб ваші змінні ніколи не пошкоджувалися під час перекладу.
Підсумок
Щоб створити файл POT правильно, спочатку зробіть свій код доступним для виявлення — обгорніть кожен видимий рядок у __(), _e(), _x() або варіант з екрануванням, усі вони повинні використовувати один текстовий домен, і оголосіть цей домен плюс Domain Path у своєму заголовку. Потім згенеруйте шаблон за допомогою WP-CLI для нових проєктів, Poedit, якщо ви віддаєте перевагу графічному інтерфейсу, або makepot лише при підтримці застарілого коду.
Генеруйте рано, регенеруйте часто і ніколи не дозволяйте вашому шаблону відставати від коду. Актуальний .pot — це різниця між плагіном, який дійсно готовий до світу, і тим, який лише заявляє про це.
Готові перетворити свій шаблон
.potна готові переклади без ручного процесу компіляції? Спробуйте SimplePoTranslate безкоштовно — кредитна картка не потрібна. Завантажте свій шаблон на безкоштовний рівень і завантажте готові до відправлення файли перекладу за лічені хвилини.