{"id":3454,"library":"deep-translator","title":"deep-translator library","description":"deep-translator is a versatile Python library designed for translating text between various languages using a multitude of free and commercial online translation services. It is currently at version 1.11.4 and maintains an active development pace with frequent updates, bug fixes, and additions of new translator support.","status":"active","version":"1.11.4","language":"en","source_language":"en","source_url":"https://github.com/nidhaloff/deep_translator","tags":["translation","multilingual","NLP","API","AI","document-translation"],"install":[{"cmd":"pip install deep-translator","lang":"bash","label":"Base installation"},{"cmd":"pip install \"deep-translator[all]\"","lang":"bash","label":"With all optional dependencies"},{"cmd":"pip install \"deep-translator[chatgpt]\"","lang":"bash","label":"For ChatGPTTranslator (requires OpenAI)"}],"dependencies":[{"reason":"Core dependency for making HTTP requests to various translation services.","package":"httpx","optional":false},{"reason":"Core dependency for parsing HTML responses from some translators.","package":"beautifulsoup4","optional":false},{"reason":"Core dependency for GoogleTranslator.","package":"googletrans==4.0.0rc1","optional":false},{"reason":"Optional dependency for DeepLTranslator, installed with the 'deepl' extra.","package":"deepl","optional":true},{"reason":"Optional dependency for ChatGptTranslator, installed with the 'chatgpt' extra.","package":"openai","optional":true},{"reason":"Optional dependency for MyMemory, Pons, Linguee, Yandex, Microsoft, Papago, and QCRI translators.","package":"requests_html","optional":true},{"reason":"Optional dependency for translating .docx files, part of the 'document' extra.","package":"python-docx","optional":true},{"reason":"Optional dependency for reading .pdf files for translation, part of the 'document' extra.","package":"PyPDF2","optional":true},{"reason":"Optional dependency for OCR capabilities when translating PDFs/images, part of the 'document' extra.","package":"pytesseract","optional":true},{"reason":"Optional dependency for BaiduTranslator, installed with the 'baidu' extra.","package":"baidu-aip","optional":true}],"imports":[{"symbol":"GoogleTranslator","correct":"from deep_translator import GoogleTranslator"},{"symbol":"DeepLTranslator","correct":"from deep_translator import DeepLTranslator"},{"symbol":"ChatGptTranslator","correct":"from deep_translator import ChatGptTranslator"},{"symbol":"single_translation","correct":"from deep_translator import single_translation"},{"symbol":"batch_translation","correct":"from deep_translator import batch_translation"},{"note":"As of v1.10.0, document_translation is directly importable from the top-level package.","wrong":"from deep_translator.document import document_translation","symbol":"document_translation","correct":"from deep_translator import document_translation"}],"quickstart":{"code":"import os\nfrom deep_translator import GoogleTranslator, DeepLTranslator\n\n# Example 1: Google Translator (no API key typically required for basic use)\ntranslated_text_google = GoogleTranslator(source='auto', target='fr').translate(text='Hello world!')\nprint(f\"Google Translation: {translated_text_google}\")\n\n# Example 2: DeepL Translator (API key usually required for production/higher usage)\n# Ensure deep-translator[deepl] is installed (pip install \"deep-translator[deepl]\")\ndeep_l_api_key = os.environ.get('DEEPL_API_KEY', '') # Load from environment variable\n\nif deep_l_api_key:\n    try:\n        # use_free_api=True for DeepL Free API tier\n        translator = DeepLTranslator(api_key=deep_l_api_key, source='en', target='de', use_free_api=True)\n        translated_text_deepl = translator.translate(text='Hello world!')\n        print(f\"DeepL Translation: {translated_text_deepl}\")\n    except Exception as e:\n        print(f\"DeepL translation failed: {e}. Check API key and installation.\")\nelse:\n    print(\"DeepL API key not found (DEEPL_API_KEY). Skipping DeepL translation.\")\n","lang":"python","description":"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]\"`)."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions (impacts specific translators dynamically)"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (internal bug fixed in >=1.11.2, but external limits persist)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.10.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}