Leonid Nikitin
55b04f0eab
Introduced new Data Transfer Objects (DTOs), exceptions, and jobs to enhance the translation service functionality. Updated namespaces for consistency and added rate limiting to the translation provider. Expanded the README with detailed usage instructions.
101 lines
6.5 KiB
Markdown
101 lines
6.5 KiB
Markdown
# translate-laravel
|
||
|
||
Библиотека для Laravel, что бы общаться с сервисом перевода от <a href="https://yandex.cloud/ru/docs/translate/" target="_blank">yandex</a>. В будущем (скорей всего в далёком будущем) планирую расширить поддержку разных сервисов перевода. Что бы можно было общаться через один интерфейс с разными сервисами.
|
||
|
||
# Параметры в **.env**:
|
||
|
||
### TRANSLATE_SERVICE
|
||
По умолчанию через какой сервис обращаться за переводом. На данный момент доступен только один сервис - **yandex**.
|
||
|
||
### 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 символов. **На данный момент работает только перевод через систему очередей.**
|
||
|
||
# Методы
|
||
### Перевести обычный текст
|
||
> \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\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');
|
||
> }
|