rd0

Описание модуля LangPO — модуль для OpenCart, который предназначен для автоматизации процесса локализации. Он выгружает переводимые элементы сайта (языковые файлы интерфейса, товары, категории, статьи) в текстовый формат PO (Portable Object) — стандарт, используемый во всех профессиональных системах перевода. Полученный PO-файл можно: - Перевести вручную в программе Poedit - Отправить в облачный сервис Lokalise, Crowdin для автоматизации процессов перевода - Перевести автоматически через DeepL или ChatGPT Ключевые преимущества модуля: Централизованное управление — вся локализация в одном модуле, без необходимости редактировать каждый товар по отдельности в административной части сайта. Локализация выгружается в набор файлов, переводится и импортируется обратно на сайт. Индустриальный стандарт — PO-формат понятен переводчикам и поддерживается всеми CAT-инструментами (Computer-Assisted Translation — системы автоматизированного перевода). PO-файл - это текстовый файл, поэтому процесс перевода легко контролировать с помощью Git-систем, особенно при работе с большой командой переводчиков. Совместимость с ИИ — формат стандартизирован и подходит для работы с нейросетями, что позволяет быстро получить черновой перевод. Установка (OpenCart 3.x) Важно! При установке модуля вы можете получить ошибку «Директория admin/controller/tool не доступна для записи!», в таком случае необходимо сначала установить бесплатный плагин-модификатор Localcopy OCMOD. Почему это нужно? OpenCart 3.x разрешает установку контроллеров только в папку`admin/controller/extension/`. Если поместить LangPO туда, он появится в списке модулей с кнопками «Включить/Отключить», которые для инструментального модуля не имеют смысла и могут вводить в заблуждение. Localcopy OCMOD позволяет обойти это ограничение. Как установить Localcopy OCMOD: 1. Перейдите в раздел «Модули / расширения» → «Установка расширений». 2. Нажмите кнопку «Загрузить» и выберите ZIP-архив с модулем Localcopy. После установки Localcopy OCMOD, вернитесь к установке LangPO. 1. В панели управления OpenCart перейдите в раздел «Модули / расширения» → «Установка расширений». 2. Нажмите кнопку «Загрузить» и выберите ZIP-архив с модулем LangPO. Дождитесь завершения установки. 3. После установки необходимо обновить кеш модификаторов, чтобы модуль отобразился в меню. - Перейдите в раздел «Модули / расширения» → «Модификаторы». - Нажмите кнопку «Очистить» (в правом верхнем углу), а затем — «Обновить». 4. В меню «Система» → «Обслуживание» появится новый пункт — LangPO. Использование экспорт/импорт Экспорт 1. В панели управления откройте меню «Система» → «Обслуживание» → «LangPO» и перейдите на вкладку «Экспорт». 2. Выберите данные для экспорта. Доступны два типа источников: - Файлы интерфейса — переводы административной панели (admin) и витрины магазина (catalog). - Таблицы базы данных — товары, категории, статьи. 3. Для каждого выбранного в форме элемента локализации, будет создан отдельный PO-файл, содержащий строки выбранного языка источника. 4. Укажите язык-источник — тот язык, с которого будут переводиться строки. Обычно это язык сайта по умолчанию. Если в вашей системе несколько языков, выберите тот, который имеет больший охват локализации на момент экспорта и для которого будет проще найти переводчиков. 5. Нажмите кнопку «Экспорт». Модуль соберёт все строки локализации в файлы и упакует их в ZIP-архив, который автоматически скачается на ваш компьютер. Важные предупреждения: - Не переименовывайте файлы внутри архива. Это нарушит связь с исходными данными и импорт станет невозможным. - Для каталогов более 1 000 товаров, рекомендуется выгружать таблицы по одной — это снижает нагрузку на сервер и позволяет избежать ошибок, связанных с лимитами памяти или временем выполнения скрипта. Особенности экспорта: - Некоторые языковые файлы могут содержать PHP-код для формирования динамических значений. Например: `$_['entry_copyright'] = '© ' . date('Y') . ' My Store';` При экспорте такой код выполняется, и в PO-файл попадает уже готовое значение (например, © 2026 My Store). При обратном импорте модуль сохраняет значение как статическую строку. Восстановление исходного PHP-кода невозможно по соображениям безопасности — модуль не может и не должен вставлять произвольный PHP-код из внешних файлов. Импорт Перед началом импорта настоятельно рекомендуется сделать резервную копию базы данных и файлов интерфейса. Почему резервная копия так важна При импорте файлов интерфейса модуль обновляет только те строки, которые нашёл в PO-файле. Если в процессе импорта произойдёт сбой (например, ошибка чтения файла или превышение времени выполнения), файлы могут остаться в промежуточном состоянии — часть строк обновлена, часть нет. В отличие от базы данных, где изменения можно откатить через транзакцию, файлы интерфейса сохраняются напрямую. Поэтому перед началом импорта рекомендуется создать резервную копию файлов интерфейса — это позволит быстро восстановить исходное состояние в случае непредвиденной ситуации. 1. В панели управления откройте меню «Система» → «Обслуживание» → «LangPO» и перейдите на вкладку «Импорт». 2. Выберите файл для импорта. Требования к файлу: - Это может быть один PO-файл или ZIP-архив, содержащий несколько PO-файлов. - Внутри архива не должно быть вложенных папок — только PO-файлы на первом уровне. - PO-файлы должны соответствовать спецификации GNU gettext. - Максимальный размер импортируемого файла — 5 МБ. - Кодировка файла — UTF-8. - В заголовке PO-файла, в поле Language, должен быть указан язык назначения в формате, соответствующем спецификации. 3. Выберите язык импорта в форме. Он должен совпадать с языком, указанным в поле Language заголовка PO-файла. Если язык не указан в заголовке или не совпадает с выбранным в форме, импорт будет остановлен. Это предотвращает случайное замещение данных на другом языке. Модуль не добавляет заголовок `Language` при экспорте, так как при экспорте не указывается целевой язык. Заголовок должен быть добавлен перед импортом. Многие редакторы PO-файлов (например, Poedit) добавляют заголовок `Language` при сохранении файла. Если редакторы не добавили его автоматически, вы можете добавить заголовок самостоятельно, вручную в любом текстовом редакторе. Заголовок имеет формат `"Language: ru\n"` и должен соответствовать спецификации GNU gettext (например, ru, uk, en). 4. Нажмите кнопку «Импорт». Модуль автоматически распакует архив (если файлы упакованы), импортирует переводы в базу данных и обновит файлы интерфейса. Важные предупреждения - Нагрузка на сервер. Для каталогов с более чем 1 000 товаров рекомендуется импортировать таблицы по одной. Это снижает нагрузку на сервер и помогает избежать ошибок, связанных с лимитами памяти или временем выполнения скрипта. - Безопасность. Модуль не защищает от XSS-атак. Данные импортируются как есть. Во время перевода в PO-файлы могут быть добавлены вредоносные скрипты. Отличить их от легитимных (например, счётчиков или интерактивных элементов) автоматически невозможно. Передавайте PO-файлы только проверенным переводчикам и всегда проверяйте файлы перед импортом. Для проверки, необходимо проанализировать PO-файлы на наличие тегов `<script>, onerror=, javascript:` и других подозрительных конструкций. Для автоматической проверки можно использовать команду grep и регулярные выражения. Например `grep -n "<script" filename.po`. Для пользователей Windows можно использовать поиск в Notepad++ по маске `<script`. Либо другие доступные инструменты. Если у вас нет опыта работы с синтаксисом PO-файлов или регулярными выражениями, безопаснее привлечь к проверке технического специалиста. Это мера предосторожности предотвратит попадание вредоносных фрагментов кода на сайт. Особенности импорта: - В файлах интерфейса модуль заменяет только значение конкретного ключа. Структура файла и комментарии сохраняются. Если ключа или файла нет в системе, импорт пропустит их без ошибок. Новые ключи или файлы не добавятся. - В некоторых языковых файлах OpenCart встречаются случаи, когда один и тот же ключ используется несколько раз с разными значениями. Это допустимо в PHP, но может вводить в заблуждение. При экспорте модуль сохраняет только последнее значение такого ключа, поскольку именно оно используется системой во время работы сайта. При импорте модуль заменяет все вхождения ключа на новое значение, полученное из PO-файла. Это означает, что файл будет приведён к единому состоянию, а неоднозначность будет устранена. - Пустые переводы. В отличие от стандартного поведения gettext, модуль LangPO не перезаписывает существующие переводы пустыми строками. Если в PO-файле для поля указан пустой перевод (msgstr ""), то значение в базе данных не изменится — останется прежним. Это предотвращает случайную потерю данных при неполном переводе. Ошибки Все ошибки, возникающие при работе модуля, записываются в стандартный журнал ошибок OpenCart. Это позволяет быстро находить и исправлять проблемы без необходимости изучать код. Где искать логи 1. В панели управления OpenCart откройте меню «Система» → «Обслуживание» → «Журнал ошибок». 2. Найдите записи, начинающиеся с префикса: LangPO module. 3. Ознакомьтесь с текстом ошибки. В большинстве случаев он содержит достаточно информации для понимания причины. Типичные ошибки и их причины Сообщение в логе: `Wrong file format ...` Вероятная причина: Загружен файл не соответствующий спецификации Что делать: Проверьте файл и повторите попытку Сообщение в логе: `Cannot open/write to file: ...` Вероятная причина: Нет прав на запись в папку Что делать: Проверьте права доступа к директориям admin/language/, catalog/language/, system/storage/download/, system/storage/upload/ Если ошибка не описана выше 1. Проверьте, что ваш сервер соответствует требованиям модуля (PHP 7.2+, MySQL InnoDB, расширение mbstring. Подробнее в разделе "Требования"). 2. Убедитесь, что PO-файл соответствует спецификации и не содержит синтаксических ошибок. Требования - OpenCart 3.x - PHP >=7.2 - MySql <8.0 (Важно: таблицы должны использовать движок InnoDB. Требуется для поддержки транзакций). Версии 8.0 и выше не поддерживаются. - Расширения PHP mbstring, zip, json. Обычно включены по умолчанию в большинстве сборок PHP. Важное примечание о MySQL - Модуль использует транзакции для безопасного импорта данных. Если ваши таблицы используют движок MyISAM, транзакции работать не будут. - Убедитесь, что таблицы product_description, category_description, information_description используют InnoDB. Проверка перед установкой Если вы не уверены, что сервер соответствует требованиям: - Проверьте версию PHP через файл phpinfo(). - Проверьте версию MySql и движок таблиц через phpMyAdmin или аналогичный инструмент. Для InnoDB в колонке Engine должно быть указано InnoDB. Лицензия LangPO распространяется под лицензией GNU GPL v3.