.po, .mo, .pot: Объяснение файлов перевода WordPress

Вы открываете папку languages темы WordPress и находите три почти одинаковых файла: twentytwentyfour.pot, twentytwentyfour-de_DE.po и twentytwentyfour-de_DE.mo. Одна и та же тема, один и тот же язык, три разных расширения. Какой из них редактировать? Какой из них WordPress фактически загружает? И почему редактирование неправильного файла приводит к тому, что ваши переводы незаметно исчезают?

Если вы когда-либо задавались вопросом, какой файл имеет значение в споре po vs mo file, вы не одиноки. Эти три расширения являются основой каждого переведенного сайта WordPress, но при этом разница между ними сбивает с толку как новичков, так и опытных разработчиков. Отредактируйте неправильный файл, и ваши немецкие посетители по-прежнему будут видеть английский. Отредактируйте правильный, но пропустите шаг, и ничего также не изменится.

В этом руководстве точно объясняется, что такое файлы .pot, .po и .mo, как они связаны в рабочем процессе GNU Gettext, где они находятся в WordPress и почему вы никогда не должны открывать файл .mo в текстовом редакторе. К концу вы будете знать, какой файл трогать, а какой оставлять в покое.

Что такое файлы .pot, .po и .mo?

Короче говоря: файл .pot — это пустой шаблон, файл .po — это ваш редактируемый перевод, а файл .mo — это скомпилированный бинарный файл, который WordPress читает во время выполнения. Они образуют цепочку, и каждое звено имеет ровно одну задачу.

Все эти три формата происходят от GNU Gettext — системы локализации, на которую полагаются WordPress, Drupal и тысячи проектов на PHP и C. Gettext отделяет исходные строки, написанные разработчиком, от переводов, предоставленных переводчиком, чтобы одна и та же кодовая база могла говорить на десятках языков, не затрагивая ни единой строки PHP.

Представьте себе это как карточку с рецептом. .pot — это пустая карточка с полями для ингредиентов, но без указания количества. .po — это карточка, заполненная для конкретного блюда. .mo — это заламинированная, машиночитаемая копия, которую кухня фактически использует во время обслуживания. Вы пишете на бумажной карточке; вы никогда не пишете на заламинированной.

Файл .pot: Основной шаблон

Файл .pot (Portable Object Template) содержит каждую переводимую строку в теме или плагине с пустыми переводами. Это основной список, который разработчики поставляют, чтобы переводчики точно знали, что нужно переводить. Строки msgstr пустые, потому что язык еще не выбран.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr ""

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr ""

Обратите внимание на пустую строку msgstr "". .pot — это шаблон, а не перевод. Вы копируете его один раз для каждого языка и заполняете пробелы. Вы редко редактируете .pot вручную; он регенерируется из исходного кода при изменении строк.

Файл .po: Ваш редактируемый человеком перевод

Файл .po (Portable Object) — это копия .pot с заполненными строками msgstr для одного языка. Это файл, который фактически редактируют переводчики и разработчики. Это обычный текстовый файл, читаемый человеком и удобный для систем контроля версий.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr "In den Warenkorb"

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr "Ihre Bestellung wurde an %s versandt"

msgid — это исходная английская строка и никогда не должна изменяться. msgstr — это ваш перевод. %s — это заполнитель, который должен оставаться нетронутым в переводе — удаление или изменение порядка является наиболее частой причиной нарушения макетов, что мы подробно рассматриваем в как переводить PO-файлы, не нарушая кодовые переменные.

Файл .mo: Скомпилированный бинарный файл

Файл .mo (Machine Object) — это скомпилированная, бинарная версия вашего .po. WordPress не может эффективно читать файлы .po во время выполнения, поэтому вместо них он загружает предварительно скомпилированный .mo. Открытие .mo в текстовом редакторе покажет нечитаемые байты — он предназначен для машин, а не для людей.

Когда WordPress вызывает load_textdomain() или load_theme_textdomain(), он ищет файл .mo, анализирует его бинарную хеш-таблицу и заменяет каждый msgid соответствующим msgstr на лету. Этот бинарный формат обеспечивает быстрый поиск даже на сайтах с тысячами строк.

Как эти три файла связаны в рабочем процессе Gettext?

Они образуют однонаправленный конвейер: исходный код становится .pot, .pot становится .po для каждого языка, а каждый .po компилируется в .mo. Переводы всегда текут «вниз по течению».

Вот полный жизненный цикл по порядку:

1. Разработчик оборачивает строки, предназначенные для пользователя, в функции Gettext, такие как __() и _e(), внутри исходного кода PHP.
2. Инструмент сканирования читает исходный код и генерирует шаблон .pot, содержащий каждую обернутую строку.
3. Переводчик копирует .pot в .po для конкретного языка (например, de_DE.po) и заполняет каждый msgstr.
4. Завершенный .po компилируется в бинарный .mo.
5. WordPress загружает .mo во время выполнения и отображает переведенный сайт.

Когда разработчик позднее добавляет новые строки, .pot регенерируется, новые записи объединяются с каждым существующим .po (сохраняя старые переводы), переводчик заполняет пробелы, а .po перекомпилируется в .mo. Цикл повторяется на протяжении всего срока службы проекта.

Главный вывод: вы редактируете .po, затем компилируете в .mo. Вы никогда не редактируете .mo напрямую и никогда не переводите внутри .pot. Если вы хотите получить более глубокое сквозное представление, полное руководство по локализации WordPress проводит вас через весь конвейер с примерами.

Соглашения об именовании и расположение файлов

WordPress строго относится к именам файлов. Ошибитесь в названии, и ваш прекрасно переведенный .mo будет просто проигнорирован, потому что WordPress ищет точное совпадение на основе текстового домена и локали.

Шаблон именования для переводов тем и плагинов:

# Pattern: textdomain-locale.po / .mo
twentytwentyfour-de_DE.po      # German (Germany) translation
twentytwentyfour-de_DE.mo      # compiled binary WordPress loads
twentytwentyfour-fr_FR.po      # French (France)
twentytwentyfour.pot           # template, no locale suffix

textdomain соответствует строке, переданной в качестве второго аргумента функциям Gettext, таким как __( 'Add to Cart', 'twentytwentyfour' ). locale — это код локали WordPress, такой как de_DE, fr_FR или pt_BR. Шаблон .pot не имеет суффикса локали, потому что он языконезависим.

Расположение имеет такое же значение, как и именование. WordPress ищет по нескольким предсказуемым путям:

• Переводы тем поставляются в собственной папке темы wp-content/themes/your-theme/languages/.
• Переводы плагинов поставляются в wp-content/plugins/your-plugin/languages/.
• Переводы с translate.wordpress.org и пользовательские переопределения попадают в глобальные каталоги wp-content/languages/themes/ и wp-content/languages/plugins/, которые имеют приоритет и сохраняются при обновлениях.

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

Почему никогда не следует редактировать файл .mo напрямую

Поскольку .mo является скомпилированным бинарным файлом, нет безопасного способа редактировать его вручную — и любое принудительное изменение будет перезаписано при следующей перекомпиляции .po. .po — это источник истины; .mo — это временный артефакт сборки.

Это единственное правило объясняет огромную долю обращений в службу поддержки типа «мой перевод изменился, но сайт не обновился». Кто-то подправляет строку, сохраняет .po и забывает перекомпилировать .mo. WordPress продолжает загружать старый бинарный файл, поэтому новая формулировка никогда не появляется. Решение всегда одно: редактировать .po, перекомпилировать в .mo, перезагрузить.

Есть вторая причина, по которой это правило важно: файлы .mo не подходят для сравнения (diff) в системах контроля версий. Поскольку они бинарные, небольшое изменение формулировки создает непрозрачный «ком» в вашей истории Git, который ни один рецензент не сможет прочитать. Сохранение .po в качестве отслеживаемого источника истины и рассмотрение .mo как сгенерированного артефакта делает ваш репозиторий пригодным для просмотра, а ваши переводы — для аудита.

Выполнение этого вручную для десятков языков утомительно и подвержено ошибкам. Именно здесь облачный рабочий процесс экономит реальное время. Такие инструменты, как SimplePoTranslate, переводят ваши строки .po и возвращают один ZIP-архив, содержащий соответствующие .po и .mo вместе — уже скомпилированные, правильно названные, готовые для размещения в wp-content/languages/. Не нужно ничего компилировать вручную, и нет шансов на устаревший .mo.

Он также применяет Syntax Locking, который замораживает каждый заполнитель, такой как %s, %1$s и {name}, а также HTML-теги, перед переводом. Ваши переменные остаются нетронутыми, поэтому вы никогда не выпустите .mo, который нарушает макет. И поскольку он работает полностью в облаке, нет дополнительного плагина, который бы замедлял ваш сайт — вы загружаете файл и скачиваете готовые, скомпилированные переводы.

Объединяем все вместе

Как только различие между файлами po vs mo file становится понятным, вся система перевода WordPress перестает казаться загадочной. .pot — это шаблон разработчика, .po — это редактируемая рабочая копия переводчика, а .mo — это скомпилированный бинарный файл, который WordPress фактически предоставляет посетителям. Переводы текут в одном направлении — от шаблона к .po и далее к .mo — и вы всегда редактируете только средний файл вручную.

Помните три правила, которые предотвращают девяносто процентов проблем с переводом: никогда не переводите внутри .pot, всегда перекомпилируйте .mo после редактирования .po и точно соблюдайте именование textdomain-locale. Следуйте этим правилам, и ваши переведенные строки будут появляться каждый раз.

Готовы прекратить мучиться с ручной компиляцией и именованием файлов перевода? Попробуйте SimplePoTranslate бесплатно — кредитная карта не требуется. Загрузите свой .po или .pot и получите готовый к использованию пакет .po + .mo на бесплатном тарифе за считанные минуты.