LinguistPro работает по модели BYOK — Bring Your Own Key. Ключи вы создаёте сами в своём аккаунте Google и вводите в этом браузере. Сервер LinguistPro не хранит ваши ключи и не использует общие ключи владельца — это защищает квоты и даёт вам полный контроль над расходами.
Эта инструкция — на трёх языках. EN: /docs/BYOK_SETUP.en.md. HE: /docs/BYOK_SETUP.he.md.
#Что работает БЕЗ ключей
Часть функций доступна сразу, без настройки:
- TTS через браузер (system_fallback) — встроенный голос ОС. Качество ниже Google Cloud TTS, но работает офлайн и бесплатно. Поддержка иврита зависит от платформы.
- Перевод через Google Translate (free) — провайдер "Google Translate" в настройках перевода. Бесплатный, но имеет жёсткие лимиты Google и иногда возвращает ошибку 429.
- MADLAD (local) — если у вас запущен Python sidecar
ai-localна 127.0.0.1:8765, локальный перевод работает без интернета и без квоты. - Транслитерация и огласовка (никкуд) — локальные библиотеки, ключ не нужен.
- Библиотека, SRS-карточки, заметки, экспорт ZIP — целиком в браузере, никаких ключей.
Если вам этого достаточно, остальное можно не настраивать.
#Какие ключи нужны для полной функциональности
| Что включает ключ | Ключ | Сервис Google | Где ввести в UI |
|---|---|---|---|
| AI-перевод Gemini (умная сегментация) | Gemini API Key | Google AI Studio | Настройки перевода → "🔑 Gemini API Key" |
| Премиум TTS (Google Cloud, голоса WaveNet) | GCP TTS API Key | Google Cloud Text-to-Speech | Настройки озвучки → "🔑 GCP TTS API Key" |
| Премиум перевод (Cloud Translation) | GCP Translate Key | Google Cloud Translation | Настройки перевода → "🔑 GCP Translate API Key" |
Все три ключа имеют формат AIzaSy… и создаются за 5–10 минут.
Один ключ на все три сервиса можно? Технически — да, если разрешить ему все три API. Но это плохая практика безопасности. Лучше создавать отдельный ключ для каждого сервиса и ограничивать его одним API — тогда утечка одного ключа не повлияет на остальные.
Стоимость: у Google есть бесплатные квоты:
- Gemini: ~50 запросов в день на flash-модели.
- Cloud Text-to-Speech: 1 миллион символов в месяц (Standard) / 4 миллиона (WaveNet).
- Cloud Translation: 500 000 символов в месяц.
Для индивидуального изучения языка этого обычно хватает с большим запасом. Превышение квоты — это сообщение об ошибке, а не автоматический счёт.
#Шаг 1: Gemini API Key
Этот ключ нужен для AI-перевода с сегментацией и пояснениями.
- Откройте
https://aistudio.google.com/app/apikeyи войдите в свой Google-аккаунт. - Нажмите "Create API key" (или "Создать ключ API").
- Выберите Google-проект из списка, либо нажмите "Create new project" — это создаст новый проект бесплатно.
- Скопируйте показанный ключ. Он выглядит как
AIzaSy...(около 40 символов). - В LinguistPro: разверните раздел "Настройки перевода" → провайдер "Gemini (legacy)" → появится поле "🔑 Gemini API Key" → вставьте ключ → "💾 Сохранить".
Готово. Ключ хранится только в этом браузере (localStorage), на сервер передаётся только при запросах перевода через HTTPS.
#Шаг 2: GCP TTS API Key (Google Cloud Text-to-Speech)
Этот ключ нужен для премиум-озвучки (WaveNet, Standard voices). Без него TTS работает через встроенный голос браузера.
- Откройте
https://console.cloud.google.com/и войдите в свой Google-аккаунт. - Создайте новый проект (если его ещё нет): сверху рядом с логотипом — выпадающий список проектов → "New Project" → дайте любое имя → "Create".
- Слева в меню найдите "APIs & Services" → "Library". Найдите "Cloud Text-to-Speech API" → откройте → "Enable".
- Слева в меню: "APIs & Services" → "Credentials".
- Сверху: "+ Create credentials" → "API key".
- Появится модальное окно с ключом
AIzaSy...— скопируйте его. - Сразу нажмите "Edit API key" (карандаш у строки ключа в списке) → раздел "API restrictions" → выберите "Restrict key" → отметьте только "Cloud Text-to-Speech API" → "Save". Это критически важно: незаограниченный ключ можно использовать для всех ваших Google Cloud сервисов, что опасно при утечке.
- В LinguistPro: разверните "Настройки озвучки" → провайдер "Online TTS" → появится поле "🔑 GCP TTS API Key" → вставьте → "💾 Сохранить".
Если вы новый пользователь Google Cloud — Google потребует подтвердить платёжный аккаунт. Внутри бесплатной квоты счёт всё равно не будет выставлен; платёжный аккаунт нужен для "доверия".
#Шаг 3: GCP Translate API Key (Google Cloud Translation)
Этот ключ нужен для провайдера "GCP Translate (API)" в настройках перевода. Если вам достаточно бесплатного "Google Translate" или локального MADLAD, этот ключ можно пропустить.
- Откройте
https://console.cloud.google.com/(тот же проект, что для TTS). - "APIs & Services" → "Library" → найдите "Cloud Translation API" → "Enable".
- "APIs & Services" → "Credentials" → "+ Create credentials" → "API key".
- Скопируйте новый ключ.
- "Edit API key" → "API restrictions" → "Restrict key" → отметьте только "Cloud Translation API" → "Save".
- В LinguistPro: "Настройки перевода" → провайдер "GCP Translate (API)" → поле "🔑 GCP Translate API Key" → вставьте → "💾 Сохранить".
#Безопасность ключей: рекомендации
- Ограничивайте каждый ключ одним API. В разделе "Edit API key" → "API restrictions" → "Restrict key". Если ключ ограничен только Cloud TTS, его кража не даст доступа к другим сервисам.
- Не публикуйте ключ. Не вставляйте в скриншоты, не пересылайте в открытых чатах, не коммитьте в git.
- Один ключ — одно устройство. localStorage хранит ключ только в этом браузере. На другом устройстве или в другом браузере ключ нужно ввести заново. Это не баг — это нормальная BYOK-модель, она защищает вас от ситуации, когда один украденный сеанс компрометирует все устройства.
- Мониторинг расхода. В Google Cloud Console: "APIs & Services" → "Dashboard" → выбрать API → видна реальная статистика запросов и оставшаяся квота.
- Ротация при подозрении. Если думаете, что ключ утёк, в Credentials удалите его и создайте новый. Старый сразу перестанет работать.
#Что произойдёт, если ключ не введён
- TTS без ключа → онлайн-озвучка автоматически переключается на встроенный голос браузера (
speechSynthesis). Один раз за сессию показывается подсказка "Add a GCP TTS key for premium quality". Качество ниже, но работает. - Gemini-перевод без ключа → видна ошибка "Gemini API Key required" и подсветка панели ввода ключа. Перевод через "Google Translate (free)" или "MADLAD" работает независимо.
- GCP Translate без ключа → выбран провайдер "GCP Translate (API)", но ключа нет → ошибка "GCP Translate API key required". Переключитесь на другой провайдер или введите ключ.
#Troubleshooting
"Неверный формат ключа. Ключ должен начинаться с AIza…"
Скопирован не тот ключ. Google API Key всегда начинается с AIza и имеет длину около 39 символов. Если у вас длинный многострочный JSON — это service account, он сейчас не поддерживается, используйте API Key из раздела Credentials.
"Quota exceeded" / 429 Превышена бесплатная квота Google. Подождите до конца суток (Gemini) или начала следующего месяца (GCP). В Google Cloud Console можно посмотреть точную квоту и расход.
Ключ ввели, но переводы не работают
- Убедитесь, что нужный API включён в проекте (Library → проверить, что напротив API написано "API Enabled").
- Проверьте, что в "Edit API key" → "API restrictions" нужный API отмечен (или выбрано "Don't restrict key" для теста).
- Очистите кеш браузера и обновите страницу — иногда service worker отдаёт старый код.
Иврит звучит странно через браузерный TTS На некоторых платформах (iOS, старые Android) нет хорошего голоса для иврита. Подключите GCP TTS Key — голоса he-IL-Wavenet-* звучат естественно.
Library/SRS/заметки не сохранились между устройствами Это ожидаемо: ваши тексты, карточки и заметки хранятся в браузере (OPFS), не на сервере. Используйте ZIP-экспорт/импорт для переноса между устройствами.
#Связанные документы
- Приватность и обработка данных:
/docs/PRIVACY.md - Хранение данных в браузере (OPFS):
/docs/OPFS_USER_GUIDE.md
Если что-то не работает или непонятно — откройте issue в репозитории проекта или напишите автору.