Tłumaczenie (Translation)

Moduł Translation integruje DeepL API do tłumaczenia wiadomości tekstowych oraz Groq Whisper do transkrypcji wiadomości głosowych. Działa przez menu kontekstowe (prawy klik na wiadomość).

Włączanie modułu

1. Dashboard → Twój serwer → toggle Translation
2. Kliknij Edit i wprowadź klucz API DeepL
3. Opcjonalnie: wprowadź klucz API Groq (dla transkrypcji audio)
4. Zapisz zmiany

Wymagany klucz API

Moduł Translation wymaga klucza API DeepL do działania. Bez niego tłumaczenie nie będzie możliwe. Klucze są szyfrowane (Fernet) przed zapisaniem w bazie danych.

Uzyskaj darmowy klucz na: https://www.deepl.com/pro-api

Konfiguracja

Klucze API są przechowywane na poziomie guild config (nie w cog_settings):

Opcja	Typ	Opis
deepl_api_key_encrypted	string	Zaszyfrowany klucz API DeepL
groq_api_key_encrypted	string	Zaszyfrowany klucz API Groq (opcjonalny)

Dashboard

Panel edycji zawiera:

• DeepL API Key — pole hasła (masked)
• Groq API Key — pole hasła (opcjonalne, do transkrypcji audio)
• Informacja o statusie klucza (skonfigurowany / brak)

Menu kontekstowe

Po włączeniu modułu, w menu kontekstowym wiadomości (prawy klik → Apps) pojawiają się:

Translate Message

Tłumaczy tekst wiadomości na preferowany język użytkownika.

Flow:

1. Wyodrębnia tekst z wiadomości (content + embed title/description/fields/footer)
2. Sprawdza preferencje językowe użytkownika
3. Jeśli brak preferencji — wyświetla modal z prośbą o wybór języka
4. Tłumaczy przez DeepL API
5. Wyświetla tłumaczenie efemeralnie

Transcribe & Translate

Transkrybuje wiadomość głosową/audio i tłumaczy transkrypcję.

Flow:

1. Szuka załącznika audio w wiadomości
2. Sprawdza rozmiar (max 25 MB)
3. Sprawdza preferencje językowe użytkownika
4. Transkrybuje przez Groq Whisper API
5. Tłumaczy transkrypcję przez DeepL API
6. Wyświetla oba (oryginał + tłumaczenie) w embedzie efemeralnym

Obsługiwane formaty audio

.ogg, .mp3, .wav, .m4a, .flac, .webm, .mp4 oraz wszelkie pliki z content-type audio/* lub video/* (voice messages).

Komendy

/setlang

Ustawia preferowany język tłumaczenia użytkownika (globalny, cross-server).

Wyświetla menu rozwijane z paginacją (25 języków na stronę) — po wyborze zapisuje preferencję w bazie danych.

/languages

Wyświetla listę wszystkich obsługiwanych języków DeepL (efemeralnie).

Obsługiwane języki

DeepL obsługuje 31 języków docelowych:

Kod	Język
BG	Bulgarian
CS	Czech
DA	Danish
DE	German
EL	Greek
EN-GB	English (British)
EN-US	English (American)
ES	Spanish
ET	Estonian
FI	Finnish
FR	French
HU	Hungarian
ID	Indonesian
IT	Italian
JA	Japanese
KO	Korean
LT	Lithuanian
LV	Latvian
NB	Norwegian
NL	Dutch
PL	Polish
PT-BR	Portuguese (Brazilian)
PT-PT	Portuguese (European)
RO	Romanian
RU	Russian
SK	Slovak
SL	Slovenian
SV	Swedish
TR	Turkish
UK	Ukrainian
ZH	Chinese (simplified)

Preferencje językowe

Kolejność rozwiązywania języka docelowego:

1. translator_lang w tabeli user_language_prefs (ustawiony przez /setlang)
2. Język interfejsu użytkownika (z LanguageManager)
3. Modal z prośbą o ręczny wybór

Preferencja jest globalna — raz ustawiona działa na wszystkich serwerach z ArcBotem.

Limity

Limit	Wartość
Tekst do tłumaczenia	5000 znaków
Plik audio	25 MB
Cache klucza API	30 minut
Timeout API	30s (DeepL), 120s (Groq)

Obsługa błędów

Kod HTTP	Akcja
403	Nieprawidłowy klucz API — cache unieważniony
456	Wyczerpany limit DeepL — informacja dla użytkownika
Inne	Generyczny błąd "API error"

Nasłuchiwane zdarzenia

Moduł nie nasłuchuje zdarzeń — działa wyłącznie przez menu kontekstowe i komendy slash.

Wskazówki

Best practices

• Użyj /setlang raz — bot zapamięta Twój język na stałe
• DeepL Free pozwala na 500,000 znaków/miesiąc — wystarczające dla większości serwerów
• Groq API jest opcjonalne — bez niego "Transcribe & Translate" nie będzie dostępne
• Klucze API DeepL kończące się na :fx to klucze darmowe

Prywatność

Tłumaczenia są wyświetlane efemeralnie (widoczne tylko dla użytkownika). Treść wiadomości jest wysyłana do DeepL/Groq API w celu przetworzenia.