EN
RUЛёгкий, но производительный мультиязычный фреймворк для WordPress 6.8+, использующий префиксы URL (/en/, /de/…) и не требующий сторонних модулей.
Оглавление
- 1. Обзор
- 2. Системные требования
- 3. Быстрый старт
- 4. Установка
- 5. Панель настроек
- 6. Механизм определения языка
- 7. Схема URL и маршрутизация
- 8. Создание и управление контентом
- 9. REST API и внешние рабочие процессы
- 10. Виджеты, шорткоды и шаблоны
- 11. SEO‑интеграция (hreflang)
- 12. Отладка и журналирование
- 13. Обслуживание
- 14. Деактивация и удаление
- 15. Устранение неполадок
- 16. Приложение A — CLI, хуки и фильтры
- Глоссарий | Сноски
1. Обзор
Multilingual Engine (далее — ME) — минималистичный плагин для организации многоязычного контента. Он добавляет к ссылкам языковой префикс, ускоряет выборку записей с помощью таксономии ml_language, генерирует черновики переводов, предоставляет REST‑метаданные для работы внешних сервисов и автоматически вставляет метатеги hreflang для поисковых систем.
См. также раздел SEO‑интеграция, где описан вывод hreflang. Для терминологии обращайтесь к глоссарию.
2. Системные требования
| Компонент | Минимум | Рекомендовано |
|---|---|---|
| WordPress | 6.8 | Актуальная LTS |
| PHP | 8.3 | 8.3.x |
| Веб‑сервер | Apache/Nginx (mod_rewrite) | Текущий stable |
| База данных | MySQL 5.7 / MariaDB 10.3 | Новые версии InnoDB |
ME рассчитан на одиночную установку WordPress, не поддерживает Multisite[1].
3. Быстрый старт
- Загрузите папку
multilingual-engineв/wp-content/plugins/. - Активируйте плагин в Плагины → Установленные.
- Перейдите в Настройки → Общие и настройте:
- Доступные языки — напр.
en,de,fr - Язык по умолчанию —
en
- Доступные языки — напр.
- Откройте главную страницу: ME перенаправит на
/en/(либо на другой код языка). - Добавьте шорткод
или виджет, чтобы пользователи могли менять язык.
4. Установка
4.1 Структура каталогов
wp-content/
└── plugins/
└── multilingual-engine/
├── multilingual-engine.php
└── languages/ # .mo/.po для локализации самого плагина4.2 Что происходит при активации
- Создаётся непубличная таксономия
ml_language. - Регистрируются метаполя
_ml_group_idи_ml_language(доступны в REST). - Добавляются опции со значениями по умолчанию (см. раздел 5).
Плагин не изменяет схему БД.
5. Панель настроек
Все параметры расположены в Настройки → Общие (внизу страницы).
| Поле | Назначение | Валидация | Примечание |
|---|---|---|---|
| Доступные языки | Список ISO‑639‑1 через запятую | trim, lowercase, unique | Мин. одно значение. |
| Язык по умолчанию | Фолбэк при ошибке автоопределения | должен быть в списке | Определяет язык бэкенда. |
| Создавать черновики | Автогенерация пустых переводов | bool | 0 — нет, 1 — да. |
6. Механизм определения языка
ME выбирает язык в порядке приоритетов:
| Приоритет | Источник | Условие | Пример |
|---|---|---|---|
| 1 | Префикс URL | Путь начинается с кода | /de/about/ |
| 2 | Кука ml_lang | Выбрана ранее пользователем | ml_lang=fr |
| 3 | Заголовок Accept‑Language | Первичный тег входит в список | ru-RU,ru;q=0.9 |
| 4 | Язык по умолчанию | en |
Результат сохраняется в куку на 1 год (только если язык не передан в URL) и используется на всех последующих страницах.
7. Схема URL и маршрутизация
- Все фронтовые запросы должны содержать префикс языка. Иначе ME выдаёт 302 и дописывает префикс.
- Панель администратора и AJAX‑запросы не затрагиваются.
- Постоянные ссылки переводов отличаются только первым сегментом URL.
См. §12, чтобы включить трассировку редиректов.
8. Создание и управление контентом
8.1 Оригинальная запись
- При публикации задаётся таксономия
ml_language= текущий язык. - Генерируется
_ml_group_id. - Черновики других языков создаются, если включена опция.
8.2 Редактирование переводов
В списке записей рядом с каждой статьёй отображаются ссылки Edit {CODE}. Они открывают перевод в соответствующем языке.
8.3 Создание черновика вручную
Выключите автогенерацию, затем:
- Создайте новый пост.
- В мета‑полях установите:
_ml_language— целевой код;_ml_group_id— значение оригинала.
Эти же поля можно передать через REST API (см. §9).
9. REST API и внешние рабочие процессы
9.1 Метаполя в REST
_ml_language— код языка (строка)._ml_group_id— идентификатор группы.
Пример запроса POST:
{
"title" : "Hallo Welt!",
"content": "<p>…deutsche Version…</p>",
"status" : "publish",
"meta" : {
"_ml_language": "de",
"_ml_group_id": "mlg_64b034b4b7e44.18830524"
}
}10. Виджеты, шорткоды и шаблоны
- Шорткод:
— выпадающий список языков. - Виджет: «Language Switcher» в Внешний вид → Виджеты.
- PHP‑хелпер:
Plugin::translateUrl( $url, 'fr', $plugin->langs ).
11. SEO‑интеграция (hreflang)
Для каждой опубликованной статьи ME выводит в <head> ссылки hreflang на доступные переводы. Никаких настроек не требуется.
12. Отладка и журналирование
- В
wp-config.phpдобавьте
define('MULTILINGUALENGINE_DEBUG', true); - Логи пишутся в
wp-content/debug.log(требуетсяWP_DEBUG_LOG). - Фиксируются: источник определения языка, редиректы, создание черновиков, ошибки REST.
13. Обслуживание
13.1 Изменение списка языков
Отредактируйте поле Доступные языки и сохраните. Новые коды создадутся при первом использовании.
13.2 Генерация черновиков для нового языка
- Включите «Создавать черновики».
- Выделите все записи, выберите массовое действие «Изменить → Обновить».
- Отключите опцию при желании.
13.3 Очистка пустых черновиков
Используйте WP‑CLI:
wp post list --post_status=draft --meta_key=_ml_group_id --format=ids |
xargs -n1 -I{} wp post delete {} --force14. Деактивация и удаление
- Деактивация — URL с префиксами станут 404; настройте редиректы заранее.
- Удаление — удаляются только файлы плагина; данные остаются[2].
Чтобы полностью очистить БД, вручную удалите опции и метаполя (см. §13).
15. Устранение неполадок
| Симптом | Причина | Решение |
|---|---|---|
| Циклический 302 | Кука с неподдерживаемым кодом | Очистить куки или исправить список языков |
| Дублирование черновиков | Старая версия плагина (<1.01) | Обновить, удалить лишние черновики |
| Перевод скрыт | Не задано _ml_language | PATCH через REST или отредактировать запись |
16. Приложение A — CLI, хуки и фильтры
16.1 CLI‑пример: поиск неполных переводов
wp eval '
$pl = MultilingualEngine\Plugin::instance();
foreach (get_posts([
"meta_key" => "_ml_group_id",
"posts_per_page" => -1,
"fields" => "ids"
]) as $id) {
$g = get_post_meta($id, "_ml_group_id", true);
$langs = wp_get_post_terms($id, "ml_language", ["fields" => "slugs"]);
if (count($langs) < count($pl->langs)) {
echo "$id $g missing\n";
}
}'16.2 Основные хуки/фильтры
pre_get_posts— фильтрация записей по языку.save_post— присвоение языка и группы, создание черновиков.ml_translatable_post_types— фильтр списка CPT, обрабатываемых ME.- Шорткод
и виджет Language Switcher.
Глоссарий
- Префикс URL
- Двухсимвольный код языка в начале пути (например,
/en/). - Группа переводов (
_ml_group_id) - Общее поле для всех версий одной статьи.
- Таксономия
ml_language - Служебный тег WP, ускоряющий выборку записей конкретного языка.
Сноски
[1] Поддержка Multisite требует иного подхода (отдельные сайты под языки). Для этого существует Polylang Pro или WPML.
[2] Политика WordPress: удаление данных при удалении плагина оставляется на усмотрение администратора; во избежание потери контента ME не чистит БД автоматически.