muhammadGagah · George-br · Jun 7, 2026
diff --git a/addon/doc/uk/readme.md b/addon/doc/uk/readme.md
@@ -0,0 +1,229 @@
+# Генерація природного мовлення для NVDA
+
+**Автор:** Мухаммад Гага [muha.aku@gmail.com](mailto:muha.aku@gmail.com)
+
+Генерація природного мовлення — це додаток NVDA, який інтегрує **Google Gemini AI** для створення високоякісного природного мовлення безпосередньо в NVDA.
+Він надає чистий, повністю доступний інтерфейс для перетворення тексту в аудіо, підтримуючи як **озвучення одним голосом**, так і **динамічні діалоги з кількома голосами**.
+
+Цей додаток розроблено для забезпечення безперебійної роботи, зручного керування з урахуванням вимог доступності та гнучкого голосового керування, що ідеально підходить для озвучування, діалогів та створення аудіоконтенту.
+
+---
+
+## Особливості
+
+### Генерація високоякісного мовлення
+
+* Виберіть між:
+
+  * **Gemini Flash 3.1 (preview)** Потужна генерація мовлення з низькою затримкою, ідеально підходить для коротких аудіозаписів.
+  * **Gemini Flash 2.5** Стандартна якість, швидка генерація, низька затримка.
+  * **Gemini Pro 2.5** Преміум-версія, більш реалістичні голоси (платна модель).
+
+### Режими роботи з одним та декількома голосами
+
+* **Озвучування одним голосом** для стандартного перетворення тексту в мовлення.
+* **Режим з декількома голосами (2 голоси)** для діалогів з різними голосами.
+
+### Розширене голосове керування
+
+* **Назви голосів**
+  Призначайте власні назви (наприклад, *Іван*, *Марія*) у режимі кількох голосів.
+  ШІ автоматично призначає голоси відповідно до назв голосів у сценарії.
+* **Інструкції зі стилю**
+  Надайте такі підказки, як *«Говоріть веселим тоном»* або *«Розповідайте спокійно»*, щоб допомогти у виконанні завдання.
+* **Контроль температури**
+  Налаштування варіативності і креативності виводу:
+
+  * Нижчі значення → більш стабільне та передбачуване мовлення.
+  * Вищі значення → більш виразне та різноманітне мовлення.
+
+### Зручний та зрозумілий інтерфейс
+
+* Повністю сумісний із програмами для читання з екрану.
+* Розширені параметри розміщено у спливаючій панелі, щоб основний діалог додатка залишався простим і зрозумілим.
+
+### Безперебійний робочий процес
+
+* Аудіофайл відтворюється автоматично після створення.
+* Створений аудіофайл можна прослухати ще раз або зберегти у форматі `.wav` високої якості.
+* Розроблено для максимальної зручності під час багаторазового створення та відтворення.
+
+### Розумне голосове завантаження та кешування
+
+* Доступні голоси завантажуються динамічно з API Gemini.
+* Дані голосів зберігаються в кеші протягом **24 годин**, щоб зменшити кількість звернень до API та пришвидшити запуск.
+
+### Спілкування з ШІ (Розмова в режимі реального часу)
+
+* **Голосовий чат у реальному часі**: ведіть природну розмову з Gemini з мінімальною затримкою.
+* **Підкріплення результатами за допомогою Google Пошуку**: надайте ШІ доступ до інформації з Інтернету в режимі реального часу під час чату.
+* **Можливість переривання**: ви можете перервати роботу ШІ в будь-який момент, сказавши щось або натиснувши «Припинити розмову».
+* **Налаштування**: Використовує вибрані вами інструкції щодо голосу та стилю.
+* **Регулювання рівня міркування**: Виберіть «Без міркування», «Низький», «Середній» або «Високий» залежно від бажаної глибини міркування.
+* **Безперервність після повторного підключення**: Контекст останніх розмов відновлюється автоматично після повторного підключення без окремого перемикання пам'яті.
+* **Більш стабільна передача даних**: Покращено поведінку при повторному підключенні (відступ + повторна спроба) та адаптивне буферизування аудіо для кращої стійкості в нестабільних мережах.
+
+---
+
+## Вимоги
+
+* NVDA 2024.1 або новіша версія; перевірено до версії NVDA 2026.1.
+* Активне підключення до Інтернету.
+* Чинний **ключ API Google Gemini**.
+
+---
+
+## Встановлення
+
+1. Завантажте найновіший пакет додаткових компонентів із
+   **Сторінки релізів:**
+   [https://github.com/MuhammadGagah/native-speech-generation/releases](https://github.com/MuhammadGagah/native-speech-generation/releases)
+2. Встановіть його як будь-який стандартний додаток NVDA.
+3. Перезапустіть NVDA, коли буде запропоновано.
+
+---
+
+## Налаштування ключа API (обов’язково)
+
+1. Створіть ключ API в **Google AI Studio**:
+   [https://aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+2. Відкрийте NVDA та перейдіть до:
+   **NVDA Меню → Інструменти → Генерація природного мовлення**
+3. Натисніть **«Налаштування API-ключа»**.
+4. Відкриються налаштування NVDA безпосередньо в категорії *Генерація природного мовлення*.
+5. Вставте свій **API-ключ Gemini** у поле *API-ключ GEMINI*.
+6. Натисніть **«OK»**, щоб зберегти.
+
+Збережені ключі надійно зберігаються за допомогою **Windows DPAPI**, тому зашифроване значення неможливо
+розшифрувати на іншому комп’ютері з ОС Windows або в іншому обліковому записі користувача.
+
+Для розширених сценаріїв розгортання ви також можете надати ключ через змінну середовища **`GEMINI_API_KEY`**.
+Додаток використовуватиме цей ключ автоматично, якщо збережений ключ відсутній.
+
+---
+
+## Як використовувати
+
+Відкрийте діалог за допомогою:
+
+* **NVDA+Control+Shift+G**, або
+* **NVDA Меню → Інструменти → Генерація природного мовлення**
+
+### Основні елементи інтерфейсу
+
+* **Текст для перетворення**
+  Введіть або вставте текст, який потрібно перетворити на мовлення.
+* **Інструкції щодо стилю (необов’язково)**
+  Надайте вказівки щодо тону, емоцій або подачі.
+* **Виберіть модель**
+
+  * Flash 3.1 Preview
+  * Flash 2.5
+  * Pro 2.5 (Висока якість)
+* **Режим мовлення**
+
+  * Один голос
+  * Декілька голосів (2)
+
+---
+
+## Генерація Мовлення
+
+### Режим одного голосу
+
+1. Виберіть **Один голос**.
+2. Виберіть голос із комбінованого списку *Вибрати голос*.
+3. Введіть текст.
+4. За бажанням додайте вказівки щодо стилю.
+5. Натисніть **Генерувати аудіо**.
+6. Аудіофайл почне відтворюватися автоматично після генерації.
+
+---
+
+### Режим декількох голосів
+
+1. Виберіть **Декілька голосів (2)**.
+2. Для кожного голосу:
+
+   * Введіть унікальну **Назву голосу**.
+   * Виберіть окремий **Голос**.
+3. Оформіть текст так, щоб кожен рядок починався з назви голосу, за яким слідує двокрапка.
+
+**Приклад:**
+
+```
+Аліса: Привіт, Бобе, як твої справи?
+Боб: У мене все чудово, Алісо! Погода просто чудова.
+```
+
+4. Натисніть **Згенерувати мовлення**.
+   Голоси буде призначено автоматично на основі назв голосів.
+
+---
+
+## Розмова з ШІ (режим реального часу)
+
+Спілкуйтеся з Gemini у природній формі, використовуючи двосторонній голосовий діалог.
+
+1. Налаштуйте бажаний **голос** та **стиль** у головному діалозі додатка.
+   *(Примітка: наразі Розмова з ШІ підтримує лише режим одного голосу)*
+2. Натисніть **Розмова з ШІ**.
+3. У новому діалозі:
+   * **Почати розмову**: розпочинає сеанс. Говоріть у мікрофон.
+   * **Припинити розмову**: завершує сеанс.
+   * **Підкріплення результатами пошуку Google**: встановіть цей прапорець, щоб дозволити Gemini шукати відповіді в Інтернеті (наприклад, актуальні новини, прогноз погоди).
+     * *Примітка: Цей прапорець прихований, поки триває розмова. Припиніть розмову, щоб змінити налаштування.*
+   * **Рівень міркування**: Оберіть `Без міркування`, `Низький`, `Середній` або `Високий`.
+   * **Перемикач мікрофона**: Увімкніть/вимкніть звук мікрофона.
+   * **Гучність**: Налаштуйте гучність відтворення ШІ.
+
+---
+
+## Розширені налаштування
+
+* Увімкніть **Розширені налаштування (Температура)**, щоб показати повзунок.
+* **Діапазон температур**:
+
+  * `0.0` → Найбільш передбачуваний і стабільний.
+  * `1.0` → Початковий баланс.
+  * `2.0` → Найбільш креативний і різноманітний.
+
+---
+
+## Огляд кнопок
+
+* **Генерувати мовлення** — розпочати генерацію мовлення.
+* **Відтворити** — відтворити останній згенерований аудіофайл.
+* **Розмова з ШІ** — відкрити діалог голосового спілкування в режимі реального часу.
+* **Зберегти аудіо** — зберегти останній аудіофайл у форматі `.wav`.
+* **Налаштування ключа API** — відкрити налаштування додатка в налаштуваннях NVDA.
+* **Переглянути голоси в AI Studio** — відкриває Google AI Studio у браузері.
+* **Закрити** — закрити діалогове вікно (або натиснути клавішу `Escape`).
+
+---
+
+## Жести вводу
+
+Налаштовується за допомогою:
+**NVDA Меню → Параметри → Жести вводу → Генерація природного мовлення**
+
+Початковий жест:
+
+* **NVDA+Control+Shift+G** – Відкрити головний діалог додатка.
+
+---
+
+## Сприяння
+
+Внески, пропозиції та звіти про помилки дуже вітаються.
+
+* Створіть **запит** щодо виявлених помилок або пропозицій щодо нових функцій.
+* Надішліть **запит на злиття**, щоб поділитися своїм кодом.
+
+**Контакти**
+
+* Email: `muha.aku@gmail.com`
+* GitHub: [https://github.com/MuhammadGagah](https://github.com/MuhammadGagah)
+
+---
+- Переклад: Георгій Галас.