Metadata-Version: 2.4
Name: auto-i18n-lib
Version: 1.0.7
Summary: Post-render HTML and frontend UI dictionary translation for Python projects with OpenAI-backed caching
Author-email: Andrey Bondarenko <bona.plus2030@gmail.com>
License: MIT
Project-URL: Homepage, https://bona-plus.ru
Project-URL: Source, https://github.com/Aalam2000/autoi18n
Project-URL: Issues, https://github.com/Aalam2000/autoi18n/issues
Keywords: i18n,l10n,translation,html,fastapi,flask,jinja2,openai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Dynamic: license-file

# auto-i18n-lib

**Автоматическая библиотека для перевода интерфейсов без ручного сбора строк.**

---

## Что содержит библиотека

- **Класс `Translator`** – публичное API для рендеринга и управления переводом.
- **Воркер** – фоновый процесс, который:
  - сканирует указанные файлы и папки (HTML, JS/JSX/TSX, UI-словари),
  - извлекает все тексты интерфейса,
  - переводит их через OpenAI,
  - сохраняет в JSON-кэш,
  - обновляет переводы при изменении кода.
- **Парсеры** для HTML, JSX/TSX, UI-словарей (рекурсивный обход).
- **Клиентский рантайм** – готовый JavaScript с функциями `translateKey()` и `setLanguage()` для динамического перевода DOM.
- **Storage** – атомарное управление кэшем и очередями.

---

## Что выполняет библиотека

- **В фоне** – автоматически находит все строки в проекте, переводит на целевые языки, поддерживает кэш актуальным.
- **При рендеринге** – методы `translate_html`, `translate_dict`, `translate_key` мгновенно отдают готовые переводы из локального кэша (без синхронных вызовов OpenAI).
- **На клиенте** – смена языка подгружает новый JSON и перерисовывает интерфейс без перезагрузки страницы.

---

## Быстрый старт

```python
from autoi18n import Translator

t = Translator(
    api_key="YOUR_OPENAI_API_KEY",
    source_lang="ru",
    target_langs=["en", "uk", "az", "tr"],
    # Пути для сканирования
    js_globs=["frontend/src/**/*.{js,jsx,tsx}"],
    html_globs=["templates/**/*.html"],
)

# Запустить воркер (один раз или в фоновом потоке)
t.run_translation_loop(interval=300)  # каждые 5 минут
```

---

## Методы рендеринга

| Метод | Назначение |
|-------|------------|
| `translate_html(html, target_lang, page_name)` | Переводит готовый HTML (текст и атрибуты). |
| `translate_dict(page_name, dict_name, source_dict, target_lang)` | Переводит вложенный словарь (UI). |
| `translate_key(key, lang, default, dict_name)` | Возвращает перевод бэкенд-фразы по ключу. |
| `register_keys(items, dict_name)` | Регистрирует исходные бэкенд-фразы. |
| `build_frontend_runtime(lang)` | Генерирует JS-рантайм для клиента. |

---

## Пример интеграции с React

1. **Настройте `Translator` с путями к вашему фронтенду.**
2. **Запустите воркер** – он сам найдёт все строки в компонентах (включая JSX-тексты, атрибуты, вызовы `t()`).
3. **Вставьте сгенерированный рантайм** в `index.html`:
   ```html
   <script>
   // Результат t.build_frontend_runtime('ru')
   </script>
   ```
4. **В компонентах используйте**:
   ```jsx
   // Любой текст, обёрнутый в translateKey, будет автоматически переведён
   <h1>{window.autoI18n.translateKey('dashboard_welcome', 'Добро пожаловать')}</h1>
   ```
   Или атрибут `data-i18n="dashboard_welcome"` на любом элементе.

5. **Переключение языка**:
   ```js
   window.autoI18n.setLanguage('en');
   ```

---

## Переменные окружения

| Переменная | Описание |
|------------|----------|
| `OPENAI_API_KEY` | Обязательный API‑ключ |
| `SOURCE_LANG` | Исходный язык (по умолчанию `ru`) |
| `AUTO_I18N_TARGET_LANGS` | Целевые языки через запятую |
| `AUTO_I18N_JS_GLOBS` | Glob-паттерны для JS/JSX (JSON-массив) |
| `AUTO_I18N_HTML_GLOBS` | Glob-паттерны для HTML |
| `AUTO_I18N_CACHE_DIR` | Папка для кэша (по умолчанию `./cache`) |
| `AUTO_I18N_DYNAMIC_DOM_ENABLED` | Включить MutationObserver |

---

## Требования к доработке (ТЗ)

Чтобы библиотека работала **полностью автоматически**, необходимо:

1. **Улучшенный JSX-парсер** – должен находить все текстовые узлы в JSX, атрибуты (`label`, `placeholder`, `title`, `aria-label`), вызовы `t()` и `translateKey()` в любом синтаксисе (включая шаблонные строки и переменные).
2. **Автоматическое обновление переводов** – воркер должен пересканивать файлы при их изменении (watch mode) и переводить только новые/изменённые строки.
3. **Клиентский рантайм** – должен уметь подгружать переводы по требованию (lazy loading) и работать с React без дополнительных обёрток.
4. **Поддержка динамических атрибутов** – `data-i18n` должен работать для любых атрибутов, а не только для текста.

---

## Лицензия

MIT
