deep-translator library

Warnings

• gotcha Many commercial or advanced translators (e.g., DeepL, ChatGPT, Baidu) require an API key from the respective service provider. Without a valid key, translation requests will fail or be severely rate-limited.
  Fix: Obtain an API key from the service provider (e.g., DeepL, OpenAI). Pass it during translator initialization (`DeepLTranslator(api_key='YOUR_KEY', ...)`) or configure via environment variables (e.g., `OPENAI_API_KEY` for ChatGPT).
• breaking As `deep-translator` relies on external, third-party translation APIs, changes in these APIs (e.g., endpoint alterations, rate limit policy changes) can cause specific translators to break without warning. This often necessitates updates to the `deep-translator` library.
  Fix: If a translator unexpectedly stops working, check the `deep-translator` GitHub repository for reported issues or new releases addressing the problem. Update the library to the latest version to get fixes.
• gotcha To use certain translators (e.g., DeepL, ChatGPT, document translation), you must install `deep-translator` with specific optional dependencies using `pip install "deep-translator[translator_name]"` or `"deep-translator[all]"`. Forgetting this step will lead to `ImportError` or `ModuleNotFoundError`.
  Fix: Install the necessary extras. For example, `pip install "deep-translator[deepl]"` for `DeepLTranslator`, `"deep-translator[chatgpt]"` for `ChatGptTranslator`, or `"deep-translator[document]"` for document processing.
• gotcha Translators have underlying `max_chars` limits imposed by the external services. While `deep-translator` fixed an internal `max_chars` bug in v1.11.2, extremely long texts might still be rejected or truncated by the API, even if the local bug is resolved.
  Fix: For very long texts, split the input into smaller, manageable chunks before translating. Consider using `batch_translation` if the chosen translator supports it efficiently.
• gotcha Document translation (introduced in v1.10.0 for PDF and DOCX) has additional requirements. PDF translation relies on OCR via Tesseract, which needs to be installed as a system dependency and available in your PATH, alongside `pytesseract` and `PyPDF2` Python packages.
  Fix: Install `pip install "deep-translator[document]"`. For PDFs, ensure Tesseract OCR is installed on your operating system and its executable is accessible in your system's PATH.

Install

• pip install deep-translator Base installation
• pip install "deep-translator[all]" With all optional dependencies
• pip install "deep-translator[chatgpt]" For ChatGPTTranslator (requires OpenAI)

Imports

• GoogleTranslator

  from deep_translator import GoogleTranslator

• DeepLTranslator

  from deep_translator import DeepLTranslator

• ChatGptTranslator

  from deep_translator import ChatGptTranslator

• single_translation

  from deep_translator import single_translation

• batch_translation

  from deep_translator import batch_translation

• document_translation

  from deep_translator import document_translation

  As of v1.10.0, document_translation is directly importable from the top-level package.

Quickstart

This quickstart demonstrates translating text using `GoogleTranslator` and `DeepLTranslator`. `GoogleTranslator` typically works out-of-the-box, while `DeepLTranslator` requires an API key (preferably set as an environment variable) and the optional `deepl` dependency to be installed (`pip install "deep-translator[deepl]"`).

import os
from deep_translator import GoogleTranslator, DeepLTranslator

# Example 1: Google Translator (no API key typically required for basic use)
translated_text_google = GoogleTranslator(source='auto', target='fr').translate(text='Hello world!')
print(f"Google Translation: {translated_text_google}")

# Example 2: DeepL Translator (API key usually required for production/higher usage)
# Ensure deep-translator[deepl] is installed (pip install "deep-translator[deepl]")
deep_l_api_key = os.environ.get('DEEPL_API_KEY', '') # Load from environment variable

if deep_l_api_key:
    try:
        # use_free_api=True for DeepL Free API tier
        translator = DeepLTranslator(api_key=deep_l_api_key, source='en', target='de', use_free_api=True)
        translated_text_deepl = translator.translate(text='Hello world!')
        print(f"DeepL Translation: {translated_text_deepl}")
    except Exception as e:
        print(f"DeepL translation failed: {e}. Check API key and installation.")
else:
    print("DeepL API key not found (DEEPL_API_KEY). Skipping DeepL translation.")