Instrukcja instalacji

Copyright © 2025 Tomasz Kamiński
Ostatnia aktualizacja: 9 czerwca 2025

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

Spis treści

1. Wymagania systemowe
2. Metoda instalacji 1: wersja skompilowana (zalecana dla większości użytkowników)
   • Wybór wersji
   • Kroki instalacji
   • Zawartość pakietu
   • Brak dodatkowej konfiguracji
3. Metoda instalacji 2: wersja źródłowa Python (dla programistów)
   • Wymagania wstępne
   • Krok 1: Instalacja Tesseract OCR
   • Krok 2: Instalacja Pythona i zależności
   • Krok 3: Uruchamianie aplikacji
4. Konfiguracja usług tłumaczenia (obie metody instalacji)
5. Porównanie wersji
6. Rozwiązywanie problemów
7. 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

OCR Translator dostępny jest w dwóch wariantach skompilowanych:

Wersja z obsługą GPU (ok. 1,34 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,34 GB (3 pliki)

Wersja wyłącznie CPU (ok. 182 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. 182 MB (2 pliki)

Kroki instalacji

1. Pobierz wymagane pliki wybranej wersji:

   • Wersja GPU: pobierz WSZYSTKIE 3 pliki:
     • OCRTranslator_GPU-enabled.7z.001
     • OCRTranslator_GPU-enabled.7z.002
     • OCRTranslator_GPU-enabled.exe
   • Wersja CPU: pobierz OBA pliki:
     • OCRTranslator_CPU-only.7z.001
     • OCRTranslator_CPU-only.exe

2. Uruchom instalator:

   • Kliknij dwukrotnie pobrany plik .exe.
   • Wybierz katalog instalacji.
   • Instalator automatycznie wypakuje wszystkie niezbędne pliki.

3. 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.

4. Uruchom aplikację:

   • Przejdź do rozpakowanego folderu.
   • Kliknij dwukrotnie OCRTranslator.exe.
   • Aplikacja uruchomi się po chwili.

5. 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 OCRTranslator.
• 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

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

1. 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.

2. 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.

3. 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

1. Jeśli nie masz zainstalowanego Pythona:

   • Pobierz Pythona ze strony python.org.
   • Pamiętaj, aby zaznaczyć opcję Add Python to PATH podczas instalacji.

2. Sklonuj lub pobierz to repozytorium:

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

3. 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

1. Z katalogu projektu uruchom:

   python main.py

2. Aplikacja uruchomi się i wyświetli główny interfejs.

3. 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):

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

DeepL API (opcjonalnie):

1. Utwórz konto DeepL na deepl.com/pro-api.
2. Wybierz plan (włącznie z planem darmowym).
3. Pobierz klucz API z panelu konta.
4. Skopiuj klucz API do użycia w ustawieniach OCR 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

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ę skompilowaną GPU, jeśli:

• masz kartę graficzną NVIDIA z obsługą CUDA,
• często używasz tłumaczenia offline MarianMT,
• zależy ci na jak najszybszym tłumaczeniu offline,
• nie przeszkadza ci większy plik do pobrania.

Wybierz wersję skompilowaną CPU, jeśli:

• nie masz dedykowanej karty graficznej,
• preferujesz mniejsze pliki do pobrania,
• głównie używasz usług tłumaczenia opartych na API,
• zależy ci na maksymalnej kompatybilności.

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 skompilowana CPU zapewnia najlepszy kompromis między prostotą obsługi, wydajnością a rozmiarem pliku do pobrania.