{"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":"python","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,"search_vec":"'1.11.4':35 'activ':39 'addit':48 'ai':57 'api':56 'bug':45 'commerci':26 'current':32 'deep':2,6 'deep-transl':1,5 'design':13 'develop':40 'document':59 'document-transl':58 'fix':46 'free':24 'frequent':43 'languag':19 'librari':4,12 'maintain':37 'multilingu':54 'multitud':22 'new':50 'nlp':55 'onlin':27 'pace':41 'python':11 'servic':29 'support':52 'text':16 'translat':3,7,15,28,51,53,60 'updat':44 'use':20 'various':18 'versatil':10 'version':34","created_at":"2026-04-11T17:29:48.450230+00:00","updated_at":"2026-04-16T06:01:09.213330+00:00","problems":[{"fix":"Ensure the library is correctly installed using `pip install deep-translator`. If using a bundling tool like PyInstaller, you might need to add `--hidden-import=deep_translator` to your build command. The correct import statement is `from deep_translator import ...`.","cause":"The Python interpreter cannot find the 'deep_translator' module. This often happens if the library is not installed, or if there's a mismatch between the installed package name (`deep-translator`) and the import statement (`deep_translator`), or if a bundling tool like PyInstaller fails to include it.","error":"ModuleNotFoundError: No module named 'deep_translator'"},{"fix":"Verify that the `text` argument is a string and its length does not exceed the translator's limit. For longer texts, implement logic to split the text into smaller chunks and translate them individually.","cause":"The text provided for translation is either not a valid string, or its length exceeds the maximum character limit imposed by the underlying translation service (e.g., Google Translate often has a 5000-character limit per request).","error":"NotValidPayload: ... text must be a valid text with maximum 5000 character, otherwise it cannot be translated"},{"fix":"Implement error handling to catch `TranslationNotFound`. Consider retrying the translation after a short delay, trying a different translator available in `deep-translator`, or checking the input text for unusual formatting or content that might cause issues for the service.","cause":"The specific translator instance used (e.g., `GoogleTranslator`, `DeeplTranslator`) could not provide a translation for the given text. This can be due to various reasons, such as temporary network issues, rate limiting by the service, or the text content being unprocessable by that particular translator.","error":"TranslationNotFound: No translation was found using the current translator. Try another translator?"},{"fix":"Consult the `deep-translator` documentation or use the `get_supported_languages()` method on the specific translator class (e.g., `GoogleTranslator.get_supported_languages()`) to get a list of valid language codes. Ensure the codes match the required format (e.g., 'en' for English, 'fr' for French).","cause":"The language code provided for the `source` or `target` language parameter is not recognized or supported by the specific translation service being used within `deep-translator`.","error":"InvalidSourceOrTargetLanguage: Invalid source or target language!"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.11.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/nidhaloff/deep_translator","docs":"https://deep-translator.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/deep-translator/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}