README

Библиотека для Laravel, что бы общаться с сервисом перевода от yandex. В будущем (скорей всего в далёком будущем) планирую расширить поддержку разных сервисов перевода. Что бы можно было общаться через один интерфейс с разными сервисами.

Параметры в .env:

TRANSLATE_SERVICE

По умолчанию через какой сервис обращаться за переводом. На данный момент доступен только сервисы - yandex, log.

yandex - https://aistudio.yandex.ru/docs/ru/translate/concepts/
log - для проверки и внедрения в свой продукт.

TRANSLATE_YANDEX_FOLDER_ID

ID folder. Код можно увидеть в адресе console.yandex.cloud/folders/{тут будет код}.

TRANSLATE_YANDEX_AUTHORIZED_KEY_PATH

Абсолютный путь в рамках приложения Laravel к файлу authorized_key.json. Например: положили файл в корень Laravel. Тогда будет путь такой: /authorized_key.json.

TRANSLATE_YANDEX_LIMIT_MAX_REQUEST

Максимальное количество запросов в период, который указан в TRANSLATE_YANDEX_LIMIT_RATE_SECONDS. По умолчанию 20 запросов в секунду. На данный момент работает только перевод через систему очередей.

TRANSLATE_YANDEX_LIMIT_RATE_SECONDS

Период в котором считается максимальное количество запросов. По умолчанию стоит секунда. На данный момент работает только перевод через систему очередей.

TRANSLATE_YANDEX_LIMIT_MAX_SYMBOLS

Максимальное количество символов за один запрос. Если превышает, то делится на две части и делает по очереди два запроса. По умолчанию стоит 9000 символов. На данный момент работает только перевод через систему очередей.

TRANSLATE_LOG_LIMIT_MAX_REQUEST

Максимальное количество запросов в период, который указан в TRANSLATE_YANDEX_LIMIT_RATE_SECONDS. По умолчанию 20 запросов в секунду. На данный момент работает только перевод через систему очередей.

TRANSLATE_LOG_LIMIT_RATE_SECONDS

Период в котором считается максимальное количество запросов. По умолчанию стоит секунда. На данный момент работает только перевод через систему очередей.

TRANSLATE_LOG_LIMIT_MAX_SYMBOLS

Максимальное количество символов за один запрос. Если превышает, то делится на две части и делает по очереди два запроса. По умолчанию стоит 9000 символов. На данный момент работает только перевод через систему очередей.

Методы

Перевести обычный текст

\KorElf\TranslateLaravel\Facades\Translate::translateText(
      string | array \$text,
      string            \$targetLanguageCode,
      ?string          \$sourceLanguageCode = null
): string | array

\$text - текст который нужно перевести.
\$targetLanguageCode - язык на который надо перевести.
\$sourceLanguageCode - язык с которого надо перевести. Если null, то сервис сам пытается определить язык.

Перевести текст в формате HTML

\KorElf\TranslateLaravel\Facades\Translate::translateHtml(
      string | array \$text,
      string            \$targetLanguageCode,
      ?string          \$sourceLanguageCode = null
): string | array

\$text - текст который нужно перевести.
\$targetLanguageCode - язык на который надо перевести.
\$sourceLanguageCode - язык с которого надо перевести. Если null, то сервис сам пытается определить язык.

Получить список языков, который сервис поддерживает

\KorElf\TranslateLaravel\Facades\Translate::listLanguages(): \KorElf\TranslateLaravel\DTO\Languages

Перевести с помощью очередей (Queues)

\KorElf\TranslateLaravel\Facades\Translate::runJob(
      \KorElf\TranslateLaravel\DTO\RunTranslateDto   \$params,
      \KorElf\TranslateLaravel\DTO\AfterTranslateDto  \$afterTranslateDto
): \Illuminate\Foundation\Bus\PendingDispatch

\$params - параметры перевода.
\$afterTranslateDto - после завершения перевода отправляет результат в объект \$afterTranslateDto->\$className. Объект должен соблюдать контракт \KorElf\TranslateLaravel\Contracts\TranslationCompletedListener.

Пример:

Создаём файл TranslationListener например в папке app/Services

  <?php declare(strict_types=1);

  namespace App\Services;

  use Illuminate\Support\Facades\Log;
  use KorElf\TranslateLaravel\Contracts\TranslationCompletedListener;

  final class TranslationListener implements TranslationCompletedListener
  {
      /**
       * Объекты создаются и пробрасываются автоматически через контейнер `$application->make`,
       * благодаря механизму автоматического внедрения зависимостей (Dependency Injection).
       * Вы можете передавать свои собственные классы, поместив их в качестве параметров конструктора.
       * Контейнер создаст эти объекты автоматически, основываясь на разрешении типа (type-hint).
       */ 
      // public function __construct(
      //     private readonly SaveContentCommand $saveContentCommand
      // ) { }

      public function onTranslationCompleted(array $translatedText, array $data = []): void
      {
          Log::info($data);
          foreach ($translatedText as $translatedTextKey => $translatedTextValue) {
              Log::info($translatedTextKey . ': ' . $translatedTextValue);
          }
          // $this->saveContentCommand->execute($data['contentId'], $translatedText);
      }
  }

Потом например в каком-то контроллере (а лучше конечно в сервисе) пишем такой метод

public function sendingForTranslation(): View
{
     // Вначале создаём объект с параметрами
    $params = (new \KorElf\TranslateLaravel\DTO\RunTranslateDto)
       ->addParamText('title', 'Заголовок', 'en', 'ru')
       ->addParamHtml('content', '<p>Привет, Мир!</p>', 'en', 'ru');

     $translationCompletedListener = \App\Services\TranslationListener::class;
     $data = ['contentId' => 1];
     $afterTranslateDto = new \KorElf\TranslateLaravel\DTO\AfterTranslateDto($translationCompletedListener, $data);

    // Отправляем на очередь
    \KorElf\TranslateLaravel\Facades\Translate::runJob($params, $afterTranslateDto);
    
    return view('success');
}