AI Translate¶

Важно

Для премиальных продуктов требуется бесплатный плагин License Manager. Установите его и добавьте лицензию продукта перед установкой этого продукта.

Требования¶

AI Translate рассчитан на Grav 1.7+ вместе с последней версией плагина Grav Admin. При использовании провайдеров AI Pro убедитесь, что плагин AI Pro установлен, включён и может обращаться к эндпоинтам API ИИ, которые вы используете.

Установка¶

Установите или обновите плагин, как любой другой пакет Grav Premium. Примеры ниже предполагают, что лицензия уже привязана к сайту.

$ bin/gpm install ai-translate

Вы также можете установить AI Translate через Admin → Plugins. После включения плагин загружает ресурсы только для авторизованных пользователей админки, не затрагивая фронтенд.

Быстрый старт¶

Откройте Admin → Plugins → AI Translate.
Выберите основного провайдера (deepl или любой ai-pro:<name>).
Вставьте учётные данные (ключ API DeepL или ключи API AI Pro).
Сохраните конфигурацию и используйте Test Provider на панели AI Pro (если это применимо).
Отредактируйте любую страницу — значок перевода сразу появится рядом с подходящими полями.

Провайдеры и учётные данные¶

DeepL¶

DeepL доступен из коробки. Укажите ключ API, выберите Free или Pro и при желании настройте формальность и правила форматирования. Плагин удерживает запросы в пределах лимита DeepL в 128 КБ, автоматически разбивая большие тексты на части.

Google Translate¶

Чтобы использовать Google Translate, нужно создать проект в Google Cloud Platform (GCP) и включить соответствующий сервис API.

Создайте проект: перейдите в Google Cloud Console и создайте новый проект (или выберите существующий).
Включите выставление счетов: убедитесь, что к проекту привязан платёжный аккаунт. Для Cloud Translation API требуется включённое выставление счетов, даже если вы остаётесь в пределах бесплатного тарифа.
Включите API:
Перейдите в APIs & Services > Library.
Найдите «Cloud Translation API».
Нажмите на результат (убедитесь, что там указано «Cloud Translation API», а не просто «Translation API» или «AutoML»).
Нажмите Enable.
Создайте учётные данные:
Перейдите в APIs & Services > Credentials.
Нажмите + CREATE CREDENTIALS и выберите API key.
Скопируйте созданный ключ API.
Ограничьте ключ (рекомендуется):
Отредактируйте только что созданный ключ API.
В разделе API restrictions выберите Restrict key.
В выпадающем списке выберите Cloud Translation API.
Нажмите Save.

google:
  api_key: 'your-google-api-key'
  format: text  # или 'html'

Провайдеры AI Pro¶

Если AI Pro установлен, AI Translate может использовать любого зарегистрированного провайдера (OpenAI, Claude, Gemini, DeepSeek или собственные драйверы). Выберите ai-pro:<provider> в качестве провайдера, при необходимости задайте переопределение модели, и AI Translate будет передавать промпты перевода через конвейер chat AI Pro, наследуя потоковую передачу, повторные попытки и фоновую обработку.

Переключение провайдеров в админке¶

Авторизованные пользователи видят выдвижную панель Translation Tuner. Она обращается к /admin/ai-translate-ajax, чтобы получить список DeepL и всех провайдеров AI Pro, и может запросить у AI Pro актуальные списки моделей через задачу ai-pro.getModels. Изменения сразу сохраняются в user/config/plugins/ai-translate.yaml.

Рабочий процесс в админке¶

Встроенные кнопки — элементы управления переводом появляются в полях text, textarea и editor, заданных в ui.enabled_field_types.
Ручной режим — установите ui.manual_mode: true, чтобы требовать translatable: true в схемах.
Режим предпросмотра — включите ui.show_preview, чтобы видеть перевод рядом с оригиналом перед сохранением.
Правила исключения — укажите CSS-селекторы в ui.exclusion_rules, чтобы автоматически пропускать метаданные или маршруты.
Учёт прав доступа — кнопки и AJAX-маршруты видят только пользователи с admin.super или admin.ai-translate.

Переводы запускаются через AJAX POST на /admin/ai-translate-ajax. Безопасность обеспечивается nonce админки и явными проверками прав в AiTranslatePlugin::handleAjaxTranslate().

Разбиение на части и большие страницы¶

Оба типа провайдеров используют общий TranslationChunker:

Разбивает текст по границам предложений с необязательным перекрытием (chunking.overlap_size), чтобы сохранить контекст.
Сохраняет форматирование, если chunking.preserve_formatting имеет значение true.
Применяет консервативный лимит 50 КБ для моделей ИИ, чтобы не выходить за пределы бюджета токенов.
Собирает результат обратно, допуская небольшое перекрытие для сохранения связности.

Настройте размеры частей в plugins.ai-translate.chunking. Слишком большой контент автоматически переводится по частям; короткие фрагменты обрабатываются одним запросом.

Стратегия кэширования¶

classes/Providers/AbstractProvider реализует двухуровневый кэш:

Кэш в памяти избавляет от повторного перевода одного и того же поля в рамках одного запроса.
Кэш Grav сохраняет переводы с ключом по тексту, языкам и провайдеру.
Настройте время жизни кэша через cache.lifetime; полностью отключите его с помощью cache.enabled: false.

Кэширование заметно снижает затраты на API, когда редакторы снова открывают черновики или когда пакетные задания запускаются повторно.

Определение языка¶

Вызовите задачу detect-language или AJAX-эндпоинт, чтобы определить исходный язык. - DeepL использует собственный API определения языка. - AI Pro формирует минимальный промпт (Detect the language…) и проверяет ответ на соответствие ISO 639-1.

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

CLI и автоматизация¶

AI Translate использует систему задач админки Grav. Запускайте переводы, обновление провайдеров или определение языка из собственных контроллеров или CLI-скриптов, отправляя запрос на /admin с task=ai-translate.translate или task=ai-translate.detect-language. Сочетайте это с Scheduler или собственными плагинами, чтобы переводить целые коллекции после развёртывания.

Для более глубокой автоматизации создайте экземпляр TranslationManager в своём плагине или задаче:

use Grav\Plugin\AiTranslate\TranslationManager;

/** @var \Grav\Common\Grav $grav */
$translator = new TranslationManager($grav, $grav['config']);
$translated = $translator->translate($original, 'fr');

Менеджер автоматически выбирает настроенного провайдера, проверяет права и выбрасывает информативные исключения, если у провайдеров нет учётных данных.

Справочник по конфигурации¶

Скопируйте user/plugins/ai-translate/ai-translate.yaml в user/config/plugins/ai-translate.yaml и редактируйте только копию. Основные параметры:

provider — deepl или ai-pro:<name>.
deepl.* — ключ API, формальность и параметры форматирования.
ai_pro.model — необязательное переопределение модели; оставьте пустым, чтобы использовать значения провайдера по умолчанию.
ai_pro.custom_prompt — шаблон с подстановками {text}, {target_lang}, {source_lang}.
ui.* — типы полей, ручной режим, предпросмотр, иконки, всплывающие подсказки, правила исключения.
languages.auto_detect — включение автоматического определения и резервного исходного языка.
cache.* и chunking.* — параметры тонкой настройки производительности.

Схемы используют вызовы data-options@, чтобы получать актуальные списки провайдеров AI Pro, массивы моделей и выбор языков, поддерживая синхронизацию интерфейса админки с возможностями времени выполнения.

Работа с AI Pro¶

AI Translate проверяет доступность AI Pro при инициализации плагина и устанавливает ai_translate.ai_pro_available в контейнере Grav.
Регистрация провайдеров использует реестр на основе событий AI Pro, поэтому сторонние пакеты (например, AI Pro – DeepSeek) появляются автоматически.
Если AI Pro отсутствует или отключён, AI Translate корректно переключается на DeepL, не показывая элементы интерфейса, связанные с ИИ.

Права доступа¶

permissions.yaml регистрирует admin.ai-translate. Выдайте это право редакторам, которые должны переводить контент без полных прав супер-администратора. Обработчики AJAX и ресурсы проверяют право перед рендерингом элементов управления или обработкой запросов.

Решение проблем¶

Кнопки отсутствуют → Проверьте права, убедитесь, что плагин включён, очистите кэш (bin/grav clear-cache).
AJAX не авторизован → Отсутствует или истёк nonce админки; откройте страницу админки заново.
Пустые переводы → Проверьте учётные данные провайдера. Для AI Pro убедитесь, что выбранная модель поддерживает перевод, и просмотрите журналы в logs/grav.log.
Большая страница не обрабатывается → Настройте chunking.max_chunk_size, убедитесь, что целевой провайдер поддерживает длинные промпты, или включите DeepL для документов.
Список моделей пуст → Убедитесь, что у AI Pro есть права на получение списка моделей провайдера; используйте bin/plugin ai-pro models --provider=<name>.