Чому ваші переклади не відображаються у WordPress (Інструкція з усунення несправностей)

У WordPress розробці немає нічого більш неприємного, ніж «Тиха помилка».

Ви все зробили правильно. Ви переклали .po файл. Ви скомпілювали його у .mo файл. Ви завантажили його на свій сервер через FTP. Ви очистили кеш.

Ви оновлюєте сторінку, очікуючи побачити іспанську, французьку чи німецьку. Замість цього ви бачите... англійську.

Жодного повідомлення про помилку, жодного білого екрану — лише впертий, неперекладений текст. Перш ніж ви почнете рвати на собі волосся, прочитайте цей посібник. Ось 5 найпоширеніших причин, чому переклади не завантажуються у WordPress, і як їх виправити.

1. Ви неправильно називаєте файл

WordPress надзвичайно суворий до іменування файлів. Якщо ви пропустите символ, він не завантажить файл.

Стандартний формат: {text-domain}-{locale}.mo

• Текстовий домен: Це унікальний ідентифікатор теми або плагіна (наприклад, woocommerce, twentytwentyfour, my-custom-plugin).
• Локаль: Код локалі WP (наприклад, es_ES для іспанської (Іспанія), fr_FR для французької (Франція)).

Поширені помилки:

• Назва файлу просто es_ES.mo (Це працює лише для глобальних основних файлів WordPress, а не для плагінів).
• Використання неправильного дефісу: my_plugin_es_ES.mo (Підкреслення) замість my-plugin-es_ES.mo (Дефіс).
• Вгадування текстового домену. Ви повинні перевірити код плагіна (заголовок style.css або функцію load_plugin_textdomain), щоб знайти точний слаг.

2. Ви розмістили файл у неправильній папці

Місце, куди ви завантажуєте файл, має таке ж значення, як і його назва. WordPress шукає у певних каталогах у певному порядку.

• "Безпечна" системна папка: /wp-content/languages/plugins/ або /wp-content/languages/themes/.
  • Плюси: Це захищено від оновлень плагінів.
  • Мінуси: Ви повинні назвати файл textdomain-locale.mo.
• Папка автора: /wp-content/plugins/plugin-name/languages/.
  • Плюси: Легко знайти.
  • Мінуси: НЕБЕЗПЕЧНО. Коли ви оновлюєте плагін, ця папка повністю очищається. Ваші переклади зникнуть.

Найкраща практика: Завжди розміщуйте свої власні файли .mo у глобальному каталозі /wp-content/languages/, щоб запобігти втраті даних під час оновлень.

3. "Тихий вбивця": Пошкоджений синтаксис у .po файлі

Це найскладніша проблема для налагодження, і вона часто трапляється з інструментами автоматичного перекладу на основі штучного інтелекту.

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

Як це відбувається? Якщо перекладач (людина чи ШІ) псує форматування Gettext, рядок стає недійсним.

• Приклад: Відсутня закриваюча лапка ".
• Приклад: Порушення змінної (зміна %s на % s).
• Приклад: Порушення лічильника msgid_plural.

Коли WordPress стикається зі зламаним записом у файлі .mo, він часто пропускає його або припиняє читання файлу взагалі, повертаючись до оригінальної англійської мови.

4. Ви забули скомпілювати (.po vs .mo)

WordPress не може читати файли .po безпосередньо. Це поширене помилкове уявлення.

• .po = Читабельний для людей (Portable Object).
• .mo = Читабельний для машин (Machine Object).

Якщо ви завантажуєте файл my-theme-es_ES.po, але забуваєте створити відповідний файл .mo, нічого не станеться. Ви повинні його скомпілювати.

5. Кешування (Звичайний підозрюваний)

Якщо ви використовуєте плагіни кешування (WP Rocket, LiteSpeed) або кешування на стороні сервера (Varnish, Redis), ваш сайт може показувати кешовану HTML-версію до того, як ви завантажили переклад.

Виправлення: очистіть усі кеші, включаючи кеш браузера та об'єктний кеш.

Найкраще рішення: Дійсні файли від початку

Усунення несправностей шляхів до файлів і імен файлів – це легко. Усунення несправностей пошкодженого синтаксису (Причина №3) – це кошмар.

Якщо ви використовуєте інструмент, який ламає ваші кодові змінні або пошкоджує структуру Gettext, ви витратите години, гадаючи, чому файл не працює, не усвідомлюючи, що сам файл «отруєний».

Ось чому ми створили SimplePoTranslate.

• Блокування синтаксису: Ми гарантуємо, що кожен рядок є синтаксично дійсним, перш ніж ви його завантажите. Ми блокуємо змінні, такі як %s, щоб їх не можна було зламати.
• Ідеальне форматування: Ми генеруємо чисті, стандартні файли .po, які компілюються в робочі файли .mo у 100% випадків.
• Не потрібні плагіни: Ви завантажуєте файл і знаєте, що він працює. Вам просто потрібно завантажити його у правильну папку.
• WordPress Plugin: Бажаєте взагалі пропустити ручне завантаження? Наш офіційний SimplePoTranslate WordPress plugin автоматично визначає .pot файли вашої теми та плагіна, перекладає їх у хмарі та розгортає результат у правильний каталог із правильною назвою файлу. Більше ніяких неправильно названих файлів, ніяких неправильних шляхів до папок — дві найпоширеніші причини, чому переклади не з'являються.

Припиніть гадати, чому ваші переклади невидимі. Почніть з файлу, якому ви можете довіряти.

Готові перекладати без головного болю? Почніть безкоштовно на SimplePoTranslate.com