Як перекласти плагін 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 або мова сайту, встановлена на неправильну локаль. Наш посібник з усунення несправностей, коли переклади не відображаються розглядає кожен із цих збоїв.

Плагіни, які зберігають рядки в базі даних

Ось важливе обмеження. Підхід Gettext перекладає лише рядки, що знаходяться в коді плагіна. Деякі плагіни, особливо конструктори форм, конструктори сторінок та розширення для електронної комерції, дозволяють створювати контент (мітки форм, атрибути продуктів, власні повідомлення), який зберігається в базі даних WordPress. Ці рядки є даними, створеними користувачем, і не є частиною .pot, тому файл .po не може до них дістатися. Для контенту бази даних вам потрібен багатомовний плагін, як-от WPML або Polylang, або власна функція перекладу рядків плагіна. Завжди перевіряйте, чи знаходиться даний рядок у коді, чи в базі даних, перш ніж припускати, що файл .po може це виправити.

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

Масштабний переклад без рутинної роботи вручну

Переклад одного плагіна однією мовою вручну є керованим. Переклад його на десять мов або переклад цілого набору плагінів для клієнтського сайту перетворюється на дні повторюваної роботи, і кожне ручне редагування ризикує переплутати заповнювач, як-от %s або %1$s, і зламати вихідні дані.

Ось де хмарний робочий процес змінює ситуацію. Завантажте файл .po або .pot плагіна до SimplePoTranslate, виберіть цільові мови, і контекстно-орієнтований ШІ перекладе весь каталог, тоді як Syntax Locking заморозить кожен заповнювач, HTML-тег і кодовий токен, щоб нічого не зламалося. Smart Batching обробляє великі каталоги за один прохід, і ви завантажуєте ZIP-архів, що містить .po, .mo, .json, .php та .xliff разом, правильно відформатовані та готові до розміщення в wp-content/languages/plugins/. Він повністю працює в хмарі, тому немає встановлення на робочий стіл і жодного навантаження на ваш сайт.

Зверніть увагу, що переклад плагіна відрізняється від перекладу теми, яка використовує дещо іншу конвенцію папок та функцію завантаження. Якщо ваша мета — тема, замість цього скористайтеся нашим спеціальним посібником про локалізацію будь-якої теми WordPress, навіть якщо ви не розробник.

Використовуйте ручний шлях, коли у вас один плагін і одна мова. Використовуйте хмару, коли вам потрібно багато мов, швидко, без компромісів щодо безпеки заповнювачів.

Готові перекласти свій плагін WordPress на кожну мову, якою розмовляє ваша аудиторія, не порушуючи жодної змінної? Спробуйте SimplePoTranslate безкоштовно — кредитна картка не потрібна. Безкоштовний рівень дозволяє перекласти ваш перший файл .po плагіна за лічені хвилини, з Syntax Locking на кожному рядку.