Instrukcja instalacji

Niniejsza instrukcja zawiera szczegółowe informacje dotyczące instalacji i konfiguracji programu Game-Changing Translator.

Spis treści

Wymagania systemowe
Metoda instalacji 1: wersja skompilowana (zalecana dla większości użytkowników)
Metoda instalacji 2: wersja źródłowa Python (dla programistów)
Konfiguracja usług tłumaczenia (obie metody instalacji)
Porównanie wersji
Rozwiązywanie problemów
Którą wersję wybrać?

Wymagania systemowe

Windows 10 lub nowszy (64-bitowy)
Minimum 4 GB RAM (zalecane 8 GB)
Wersja skompilowana: 1–4 GB wolnego miejsca na dysku (w zależności od wybranej wersji)
Wersja Python: 500 MB wolnego miejsca na dysku
Dodatkowe miejsce na modele MarianMT w przypadku korzystania z tłumaczenia offline (ok. 500 MB na parę językową)
Dostęp do Internetu (do usług tłumaczenia opartych na API oraz początkowego pobierania modeli MarianMT)

Metoda instalacji 1: wersja skompilowana (zalecana dla większości użytkowników)

Wersja skompilowana jest najprostsza w instalacji, nie wymaga instalowania Pythona ani zależności. Wystarczy ją pobrać, rozpakować i uruchomić.

Wybór wersji

Game-Changing Translator dostępny jest w kilku wersjach dopasowanych do różnych potrzeb i konfiguracji sprzętowych:

Wersja 3.5.6 - wyłącznie CPU (ok. 240 MB) [Najnowsza wersja]

Najlepsza dla: wszystkich użytkowników poszukujących najnowszych funkcji z zaawansowanym systemem Gemini Translation + Gemini OCR
Wymagania: dowolny nowoczesny procesor
Rozmiar pliku do pobrania: ok. 240 MB (1 plik)
Uwaga: Tłumaczenia offline MarianMT pozostają dostępne jako niezawodna opcja zapasowa, choć zaawansowany system Gemini zapewnia lepsze rezultaty w większości zastosowań

Wersja 2 - wersje starsze

Wersja 2 pozostaje dostępna dla użytkowników preferujących poprzednią generację aplikacji:

Wersja 2 - z obsługą GPU (ok. 1,35 GB)

Najlepsza dla: użytkowników z kartami graficznymi NVIDIA, którym zależy na szybszym tłumaczeniu za pomocą modeli MarianMT
Wymagania: karta graficzna NVIDIA z obsługą CUDA
Zalety: znacznie szybsze działanie tłumaczeń neuronowych offline
Rozmiar pliku do pobrania: ok. 1,35 GB (3 pliki)

Wersja 2 - wyłącznie CPU (ok. 188 MB)

Najlepsza dla: użytkowników bez dedykowanych kart graficznych lub preferujących mniejszy plik do pobierania
Wymagania: dowolny nowoczesny procesor
Zalety: mniejszy plik do pobrania, działa na wszystkich systemach
Rozmiar pliku do pobrania: ok. 188 MB (2 pliki)

Kroki instalacji

Pobierz wymagane pliki wybranej wersji:
- Wersja 3.5.6 (najnowsza): pobierz plik:
  - GameChangingTranslator_CPU-only_v3.5.6.exe
- Wersja 2 GPU: pobierz WSZYSTKIE 3 pliki:
  - GameChangingTranslator_GPU-enabled_v2.7z.001
  - GameChangingTranslator_GPU-enabled_v2.7z.002
  - GameChangingTranslator_GPU-enabled_v2.exe
- Wersja 2 CPU: pobierz OBA pliki:
  - GameChangingTranslator_CPU-only_v2.7z.001
  - GameChangingTranslator_CPU-only_v2.exe
Uruchom instalator:
- Kliknij dwukrotnie pobrany plik .exe.
- Wybierz katalog instalacji.
- Instalator automatycznie wypakuje wszystkie niezbędne pliki.
Zainstaluj Tesseract OCR (wymagane do rozpoznawania tekstu):
- Pobierz z repozytorium UB-Mannheim.
- Wybierz najnowszą wersję 64-bitową.
- Zainstaluj w domyślnej lokalizacji: C:\Program Files\Tesseract-OCR\.
- Zaznacz wszystkie opcjonalne składniki instalacji, łącznie z obsługą wszystkich języków.
Uruchom aplikację:
- Przejdź do rozpakowanego folderu.
- Kliknij dwukrotnie GameChangingTranslator.exe.
- Aplikacja uruchomi się po chwili.
Konfiguracja przy pierwszym uruchomieniu:
- Sprawdź ścieżkę Tesseract w zakładce Ustawienia (powinna zostać wykryta automatycznie).
- Wybierz obszar źródłowy i obszar tłumaczenia.
- Skonfiguruj preferowaną metodę tłumaczenia.
- Gotowe!

Zawartość pakietu

Wersja skompilowana zawiera wszystko, czego potrzebujesz:

Plik wykonywalny GameChangingTranslator.
Wszystkie biblioteki Pythona i zależności.
Wstępnie skonfigurowane ustawienia.
Dokumentacja i instrukcja obsługi.
Pliki zasobów dla wszystkich obsługiwanych języków.

Brak dodatkowej konfiguracji

W przeciwieństwie do wersji Python wersja skompilowana nie wymaga instalacji dodatkowego oprogramowania poza Tesseract OCR. Wszystkie zależności Pythona, biblioteki tłumaczeń i biblioteki sieci neuronowych są dołączone i gotowe do użycia.

Metoda instalacji 2: wersja źródłowa Python (dla programistów)

Ta metoda zalecana jest dla programistów, którzy chcą modyfikować aplikację lub preferują uruchamianie z kodu źródłowego.

Wymagania wstępne

Python 3.7 lub nowszy
Git (opcjonalnie, do klonowania repozytorium)

Krok 1: Instalacja Tesseract OCR

Game-Changing Translator opiera się na programie Tesseract do optycznego rozpoznawania znaków. Wykonaj następujące kroki, aby go zainstalować:

Pobierz instalator Tesseract z repozytorium UB-Mannheim.
- Wybierz najnowszą wersję 64-bitową.
- Zaznacz wszystkie opcjonalne składniki instalacji, łącznie z obsługą wszystkich języków.
Zainstaluj Tesseract w domyślnej lokalizacji: C:\Program Files\Tesseract-OCR\
- Jeśli instalujesz w innej lokalizacji, trzeba będzie zaktualizować ścieżkę w ustawieniach aplikacji.
Sprawdź instalację, otwierając wiersz poleceń i wpisując:
```
"C:\Program Files\Tesseract-OCR\tesseract.exe" --version
```

Krok 2: Instalacja Pythona i zależności

Jeśli nie masz zainstalowanego Pythona:
- Pobierz Pythona ze strony python.org.
- Pamiętaj, aby zaznaczyć opcję Add Python to PATH podczas instalacji.

Sklonuj lub pobierz to repozytorium:

git clone https://github.com/tomkam1702/OCR-Translator.git
cd OCR-Translator

Zainstaluj wymagane pakiety Pythona:
```
pip install -r requirements.txt
```
Zainstalowane zostaną:
- podstawowe zależności (numpy, opencv, pytesseract, Pillow, pyautogui);
- klienty API tłumaczeń (Google Cloud Translate, DeepL);
- opcjonalne biblioteki tłumaczenia offline MarianMT (transformers, torch, sentencepiece);
- obsługa skrótów klawiszowych.

Krok 3: Uruchamianie aplikacji

Z katalogu projektu uruchom:
```
python main.py
```
Aplikacja uruchomi się i wyświetli główny interfejs.
Przy pierwszym uruchomieniu trzeba będzie:
- sprawdzić ścieżkę Tesseract w zakładce Ustawienia,
- wybrać obszary źródłowy i obszar tłumaczenia,
- skonfigurować preferowaną metodę tłumaczenia.

Konfiguracja usług tłumaczenia (obie metody instalacji)

Google Cloud Translation API (opcjonalnie):

Utwórz konto Google Cloud i projekt.
Włącz Cloud Translation API.
Utwórz klucz API:
- Przejdź do Google Cloud Console → APIs & Services → Credentials.
- Kliknij Create credentials → API key.
Skopiuj klucz API do użycia w ustawieniach Game-Changing Translator.

DeepL API (opcjonalnie):

Utwórz konto DeepL na deepl.com/pro-api.
Wybierz plan (włącznie z planem darmowym).
Pobierz klucz API z panelu konta.
Skopiuj klucz API do użycia w ustawieniach Game-Changing Translator.

MarianMT (tłumaczenie offline):

Ta opcja nie wymaga konfiguracji, ponieważ modele pobierane są automatycznie przy pierwszym użyciu. Należy jednak pamiętać o następujących kwestiach:

Każdy model ma około 500 MB.
Pierwsze tłumaczenie w nowej parze językowej potrwa trochę dłużej z uwagi na pobieranie modelu.
Zaleca się szybkie połączenie internetowe do początkowego pobierania.
Wersja GPU tłumaczy szybciej, jeśli dostępna jest kompatybilna karta graficzna NVIDIA.

Porównanie wersji

Funkcja	Wersja 3.5.6 (CPU)	Wersja 2 (GPU)	Wersja 2 (CPU)	Źródłowa Python
Złożoność instalacji	Najłatwiejsza	Najłatwiejsza	Najłatwiejsza	Umiarkowana
Pliki do pobrania	~240 MB	~1,35 GB	~188 MB	~50 MB
Wymagany Python	Nie	Nie	Nie	Tak
Zależności	Wszystkie dołączone	Wszystkie dołączone	Wszystkie dołączone	Instalacja ręczna
Integracja Gemini API	Zaawansowana (najnowsza)	Podstawowa	Podstawowa	Zaawansowana (po aktualizacji)
Działanie MarianMT	Standardowe (CPU)	Najszybsze (GPU)	Standardowe (CPU)	Zależy od konfiguracji
Monitorowanie kosztów API	Kompleksowe	Podstawowe	Podstawowe	Kompleksowe (po aktualizacji)
Personalizacja	Ograniczona	Ograniczona	Ograniczona	Pełny dostęp
Aktualizacje	Ręczne pobieranie	Ręczne pobieranie	Ręczne pobieranie	Git pull

Rozwiązywanie problemów

W przypadku problemów podczas instalacji:

Wersje skompilowane:

Aplikacja się nie uruchamia: sprawdź, czy masz zainstalowane Visual C++ Redistributable.
Nie znaleziono Tesseract: sprawdź, czy ścieżka w Ustawieniach pasuje do lokalizacji instalacji.
Wersja GPU działa wolno: sprawdź, czy sterowniki NVIDIA są aktualne i czy CUDA działa.
Ostrzeżenia antywirusowe: dodaj folder aplikacji do wykluczeń programu antywirusowego.

Wersja źródłowa Python:

Błędy zależności Python: upewnij się, że używasz Pythona 3.7+ i spróbuj ponownie zainstalować zależności.
Błędy importu: sprawdź, czy wszystkie pakiety zostały poprawnie zainstalowane poleceniem pip list.

Typowe problemy (wszystkie wersje):

Błędy API tłumaczenia: sprawdź klucze API i połączenie internetowe.
Błędy MarianMT: sprawdź, czy masz wystarczająco miejsca na dysku i stabilne połączenie internetowe do pobierania modeli.
OCR nie działa: sprawdź instalację Tesseract i konfigurację ścieżki.

Więcej pomocy znajdziesz w Instrukcji rozwiązywania problemów.

Którą wersję wybrać?

Wybierz wersję 3.5.6 – tylko CPU, jeśli:

chcesz mieć najnowsze funkcje i usprawnienia,
preferujesz zaawansowaną integrację z Gemini API zapewniającą wyższą jakość tłumaczeń,
potrzebujesz kompleksowego śledzenia i monitorowania kosztów API,
zależy ci na najmniejszym rozmiarze pliku do pobrania i nowoczesnym zestawie funkcji,
głównie korzystasz z internetowych usług tłumaczenia (Gemini, DeepL, Google Translate),
nie przeszkadza ci używanie MarianMT jako niezawodnej opcji zapasowej zamiast głównej metody tłumaczenia.

Wybierz wersję 2 – z obsługą GPU, jeśli:

masz kartę graficzną NVIDIA z obsługą CUDA,
często używasz tłumaczenia offline MarianMT jako głównej metody,
zależy ci na absolutnie najszybszym działaniu tłumaczeń neuronowych,
nie przeszkadza ci większy plik do pobrania w zamian za maksymalną wydajność MarianMT.

Wybierz wersję 2 – tylko CPU, jeśli:

preferujesz interfejs poprzedniej generacji;
nie masz dedykowanej karty graficznej, ale chcesz mieć funkcje wersji 2;
głównie używasz usług tłumaczenia opartych na API, ale preferujesz wersję 2;
zależy ci na maksymalnej kompatybilności z działaniem wersji 2.

Wybierz wersję źródłową Python, jeśli:

jesteś programistą i chcesz modyfikować aplikację,
preferujesz pełną kontrolę nad zależnościami,
chcesz przyczynić się do rozwoju projektu,
czujesz się swobodnie w środowiskach programistycznych Python.

Dla większości użytkowników Wersja 3.5.6 - wyłącznie CPU zapewnia najlepszy kompromis między nowoczesnymi funkcjami, jakością tłumaczeń, prostotą obsługi i rozmiarem pliku do pobrania. Użytkownicy, którzy intensywnie korzystają z tłumaczeń offline MarianMT i posiadają kompatybilny sprzęt NVIDIA, mogą preferować Wersję 2 - z obsługą GPU dla maksymalnej wydajności offline.