130 lines
8.7 KiB
Markdown
130 lines
8.7 KiB
Markdown
# 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> string | array \$text,
|
||
> <br> string \$targetLanguageCode,
|
||
> <br> ?string \$sourceLanguageCode = null
|
||
> <br>): string | array
|
||
|
||
**\$text** - текст который нужно перевести.
|
||
<br>**\$targetLanguageCode** - язык на который надо перевести.
|
||
<br>**\$sourceLanguageCode** - язык с которого надо перевести. Если **null**, то сервис сам пытается определить язык.
|
||
|
||
<br>
|
||
|
||
### Перевести текст в формате HTML
|
||
> \KorElf\TranslateLaravel\Facades\Translate::translateHtml(
|
||
> <br> string | array \$text,
|
||
> <br> string \$targetLanguageCode,
|
||
> <br> ?string \$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> \KorElf\TranslateLaravel\DTO\RunTranslateDto \$params,
|
||
> <br> \KorElf\TranslateLaravel\DTO\AfterTranslateDto \$afterTranslateDto
|
||
<br>): \Illuminate\Foundation\Bus\PendingDispatch
|
||
|
||
**\$params** - параметры перевода.
|
||
<br>**\$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');
|
||
> }
|