Почему ваши переводы не отображаются в WordPress (Руководство по устранению неполадок)

В разработке для WordPress нет ничего более неприятного, чем "Тихая ошибка".

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

Вы обновляете страницу, ожидая увидеть испанский, французский или немецкий. Вместо этого вы видите... английский.

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

1. Неправильное имя файла

WordPress невероятно строг в отношении именования файлов. Если вы пропустите символ, он не загрузит файл.

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

• Text Domain: Это уникальный идентификатор темы или плагина (например, woocommerce, twentytwentyfour, my-custom-plugin).
• Locale: Код локали WP (например, es_ES для испанского языка в Испании, fr_FR для французского).

Распространенные ошибки:

• Именование файла просто es_ES.mo (Это работает только для глобальных файлов ядра WordPress, а не для плагинов).
• Использование неправильного дефиса: my_plugin_es_ES.mo (подчеркивание) вместо my-plugin-es_ES.mo (дефис).
• Угадывание text domain. Вы должны проверить код плагина (заголовок 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

Эту проблему сложнее всего отлаживать, и она часто возникает при использовании общих инструментов AI-перевода.

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