translate-laravel/README.md

# translate-laravel

Библиотека для Laravel, что бы общаться с сервисом перевода от <a href="https://yandex.cloud/ru/docs/translate/" target="_blank">yandex</a>. В будущем (скорей всего в далёком будущем) планирую расширить поддержку разных сервисов перевода. Что бы можно было общаться через один интерфейс с разными сервисами.

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

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

**yandex** - https://yandex.cloud/ru/services/translate<br>
**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(
> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string | array \$text, 
> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\$targetLanguageCode, 
> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;?string &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\$sourceLanguageCode = null
> <br>): string | array

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

<br>

### Перевести текст в формате HTML
> \KorElf\TranslateLaravel\Facades\Translate::translateHtml(
> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string | array \$text,
> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\$targetLanguageCode,
> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;?string &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\$sourceLanguageCode = null
> <br>): string | array

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

<br>

### Получить список языков, который сервис поддерживает
> \KorElf\TranslateLaravel\Facades\Translate::listLanguages(): \KorElf\TranslateLaravel\DTO\Languages

<br>

### Перевести с помощью очередей (Queues)
> \KorElf\TranslateLaravel\Facades\Translate::runJob(
> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\KorElf\TranslateLaravel\DTO\RunTranslateDto &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\$params,
> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\KorElf\TranslateLaravel\Contracts\TranslationCompletedListener \$completedListener
<br>): \Illuminate\Foundation\Bus\PendingDispatch

**\$params** - параметры перевода.
<br>**\$completedListener** - после завершения перевода отправляет результат в этот объект. Объект должен соблюдать контракт **\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
>       {
>           public function onTranslationCompleted(array $translatedText): void
>           {
>               foreach ($translatedText as $translatedTextKey => $translatedTextValue) {
>                   Log::info($translatedTextKey . ': ' . $translatedTextValue);
>               }
>           }
>       }
> 
> Потом например в каком-то контроллере (а лучше конечно в сервисе) пишем такой метод
>
>     public function sendingForTranslation(\App\Services\TranslationListener $translationListener): View
>     {
>          // Вначале создаём объект с параметрами
>         $params = (new \KorElf\TranslateLaravel\DTO\RunTranslateDto)
>            ->addParamText('title', 'Заголовок', 'en', 'ru')
>            ->addParamHtml('content', '<p>Привет, Мир!</p>', 'en', 'ru');
> 
>         // Отправляем на очередь
>         \KorElf\TranslateLaravel\Facades\Translate::runJob($params, $translationListener);
>         
>         return view('success');
>     }