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 и перерисовывает интерфейс без перезагрузки страницы.

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

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 минут

Поиск файлов для перевода (scan_paths)

Библиотека сама решает, какие файлы сканировать. Список путей собирается из трёх источников, в порядке приоритета:

1. Аргумент scan_paths в конструкторе:

   t = Translator(scan_paths=[
       {"path": "frontend/src/**/*.{js,jsx,tsx}", "type": "js"},
       {"path": "backend/templates/**/*.html",     "type": "html"},
       {"path": "content/**/*",                    "type": "auto"},
   ])
   

2. Env-переменная AUTO_I18N_SCAN_PATHS (JSON-массив) — если аргумент не задан:

   AUTO_I18N_SCAN_PATHS=[{"path":"/app/frontend_src/**/*.js","type":"js"},{"path":"/app/templates/**/*.html","type":"html"}]
   

3. Стандартный набор путей (DEFAULT_SCAN_PATHS) — если ни аргумент, ни env не заданы:

   [
       {"path": "frontend/src/**/*.{js,jsx,tsx}",  "type": "js"},
       {"path": "src/**/*.{js,jsx,tsx}",           "type": "js"},
       {"path": "app/**/*.{js,jsx,tsx}",           "type": "js"},
       {"path": "templates/**/*.html",             "type": "html"},
       {"path": "app/templates/**/*.html",         "type": "html"},
       {"path": "backend/templates/**/*.html",     "type": "html"},
   ]
   

Типы файлов

Когда что использовать

• 0 конфига — если у вас стандартный проект (React в frontend/, Jinja в templates/), ничего указывать не надо.
• Через .env — если на dev и prod пути разные (например, внутри контейнера /app/frontend_src вместо frontend/src). Env полностью заменяет дефолт.
• Через аргумент — если пути нестандартные (content/, docs/, внешние папки).

Метод extract_keys()

Единая точка входа для обхода всех путей:

report = t.extract_keys()
# {'files': 28, 'extracted': 142, 'queued': 568}

Старый extract_js_keys(js_globs=[...]) сохранён для обратной совместимости.

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

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

1. Настройте Translator с путями к вашему фронтенду.

2. Запустите воркер – он сам найдёт все строки в компонентах (включая JSX-тексты, атрибуты, вызовы t()).

3. Вставьте сгенерированный рантайм в index.html:

   <script>
   // Результат t.build_frontend_runtime('ru')
   </script>
   

4. В компонентах используйте:

   // Любой текст, обёрнутый в translateKey, будет автоматически переведён
   <h1>{window.autoI18n.translateKey('dashboard_welcome', 'Добро пожаловать')}</h1>
   

   Или атрибут data-i18n="dashboard_welcome" на любом элементе.

5. Переключение языка:

   window.autoI18n.setLanguage('en');
   

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

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

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

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

Лицензия

MIT