eng-to-ru 0.1.1
Библиотека для перевода текста с английского на русский с использованием Google Translate API.
Requires Python: >=3.8

# Eng to Ru: инструмент для перевода текста с английского на русский

**Eng to Ru** — это Python-библиотека для перевода текста с английского на русский с использованием Google Translate API. Библиотека поддерживает пакетную обработку, обработку ошибок и логирование.

---

## Оглавление

- [Описание](#описание)
- [Установка](#установка)
- [Использование](#использование)
- [Примеры](#примеры)
- [Логирование](#логирование)
- [API](#api)
- [Лицензия](#лицензия)

---

## Описание

Библиотека предназначена для перевода больших текстов с английского на русский. Он разбивает текст на блоки не больше 5000 символов, обрабатывает их параллельно пакетами с заданным количеством блоков текстов и поддерживает повторные попытки при ошибках.

---

## Установка

Установите библиотеку с помощью pip:

```bash
pip install eng_to_ru
```

---

## Использование

### Импорт и инициализация

```python
from eng_to_ru import Translator

translator = Translator()
```

### Перевод текста

```python
text = "Your English text here..."
translated_text = translator.run(text)
print(translated_text)
```

---

## Примеры

### Пример 1: Простой перевод

```python
from eng_to_ru import Translator

translator = Translator()
text = "Hello, world!"
translated = translator.run(text)
print(translated)  # Привет, мир!
```

### Пример 2: Перевод большого текста

```python
from eng_to_ru import Translator

translator = Translator(batch_size=10)
with open("large_text.txt", "r", encoding="utf-8") as f:
    text = f.read()
translated = translator.run(text, description="Перевод большой статьи...")
with open("translated.txt", "w", encoding="utf-8") as f:
    f.write(translated)
```

### Пример 3: Перевод с обработкой ошибок

```python
from my_translator import Translator

translator = Translator()
try:
    translated_text = translator.run("Hello, world!")
    if translated_text is None:
        print("Ошибка перевода.")
    else:
        print(translated_text)
except Exception as e:
    print(f"Произошла ошибка: {e}")
```

---

## Логирование

Библиотека использует модуль logging для вывода информации о процессе перевода.

Пример настройки логирования:

```python
import logging
logging.basicConfig(level=logging.INFO)
```

Пример вывода:

```bash
---
INFO > Перевод документа...
INFO >> Длина текста: 20000 символов.
INFO >> Переведено: 25%.
INFO >> Переведено: 50%.
INFO >> Переведено: 75%.
INFO >> Переведено: 100%.
```

---

## API

### Класс Translator

#### Инициализация

```python
translator = Translator(batch_size: int = 5, log_prefix: str = ">", max_retries: int = 2)
```

| Параметр     | Тип | Описание                                                                                         | Значение по умолчанию |
|--------------|-----|--------------------------------------------------------------------------------------------------|-----------------------|
| `batch_size` | int | Максимальное количество одновременно переводимых блоков текста (блок <= 5k символов). Больше - быстрее. | 5              |
| `log_prefix` | str | Префикс для сообщений логов.                                                                     | ">"                   |
| `max_retries`| int | Максимальное число попыток перевода участка текста.                                              | 2                     |

#### Метод run

```python
translated_text = translator.run(text: str, description: str = "Перевод...") -> str | None
```

| Параметр      | Тип | Описание                                                                 | Значение по умолчанию     |
|---------------|-----|--------------------------------------------------------------------------|---------------------------|
| `text`        | str | Текст, который нужно перевести.                                          |                           |
| `description` | str | Краткое текстовое приветствие-описание для системы логирования (на логику не влияет). | "Перевод..." |

Возвращает:
Переведённый текст (str) или None, если произошла ошибка.

Логика работы:

- Если текст состоит только из цифр, знаков препинания и пробелов, он возвращается без изменений.
- При ошибках перевода выполняется до `max_retries` попыток с интервалом в 10 секунд.
- Если все попытки неудачны, возвращается `None`.

---

## Лицензия

Проект распространяется под лицензией MIT. Подробности см. в файле [LICENSE](LICENSE).