{"id":2053,"library":"googletrans","title":"Googletrans","description":"Googletrans is a free and unlimited Python library that implements the Google Translate API. It leverages the Google Translate Ajax API for language detection and text translation. As of version 4.0.2, the library features a modern async-only API, support for bulk translations, automatic language detection, and proxy configurations. It is compatible with Python 3.8+ and is actively maintained.","status":"active","version":"4.0.2","language":"python","source_language":"en","source_url":"https://github.com/ssut/py-googletrans","tags":["translation","google translate","api client","natural language processing"],"install":[{"cmd":"pip install googletrans","lang":"bash","label":"Latest stable release"}],"dependencies":[{"reason":"Core HTTP client for making requests to the Google Translate API.","package":"httpx","optional":false},{"reason":"Optional dependency for improved performance via HTTP/2 support.","package":"hyper","optional":true}],"imports":[{"symbol":"Translator","correct":"from googletrans import Translator"}],"quickstart":{"code":"import asyncio\nfrom googletrans import Translator\n\nasync def translate_text():\n    translator = Translator()\n    text_to_translate = \"Hello, how are you?\"\n    \n    # Translate a single text\n    translation = await translator.translate(text_to_translate, dest='es')\n    print(f\"Original: {translation.origin}, Translated (ES): {translation.text}\")\n\n    # Translate multiple texts\n    texts = [\"The quick brown fox\", \"jumps over\", \"the lazy dog\"]\n    translations = await translator.translate(texts, dest='fr')\n    for t in translations:\n        print(f\"Original: {t.origin} -> Translated (FR): {t.text}\")\n\n    # Detect language\n    detection = await translator.detect(\"Bonjour\")\n    print(f\"Detected language: {detection.lang} with confidence {detection.confidence}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(translate_text())\n","lang":"python","description":"Initializes a Translator instance to translate a single string, multiple strings in a batch, and detect the language of a given text. Note that the API is now async-only."},"warnings":[{"fix":"Rewrite code to use `await` with `async/await` syntax and run within an `asyncio` event loop. For example, `translator.translate('text')` becomes `await translator.translate('text')`.","message":"Version 4.0.0 introduced an async-only API. All synchronous translation and detection methods have been removed. Existing code using synchronous calls will break.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always install the latest stable version using `pip install googletrans`. If you encounter issues, consider uninstalling `googletrans` and then reinstalling the stable version.","message":"Many older tutorials and Stack Overflow answers still recommend installing `googletrans==4.0.0rc1`. This is an outdated pre-release version and may lead to unexpected behavior, bugs, or missing features compared to the latest stable release.","severity":"gotcha","affected_versions":"<4.0.0 (rc1 specifically)"},{"fix":"Implement robust error handling, rate limiting, and retry mechanisms. Consider using `service_urls` parameter to rotate through different Google Translate domains or use proxies. For critical applications requiring high stability and rate limits, consider Google's official Cloud Translation API.","message":"Googletrans is an unofficial library that relies on the public Google Translate web API. Google frequently updates its web services, which can occasionally cause the library to stop working or return HTTP 5xx errors (e.g., due to IP bans or API changes).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Introduce delays between requests, especially in loops or batch processes (e.g., `time.sleep(1)` or more). Implement exponential backoff for retries. Consider using proxies if making a very high volume of requests.","message":"Making too many requests in a short period can lead to temporary IP bans or rate limiting from Google, resulting in connection errors or HTTP 5xx status codes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For longer texts, split them into smaller chunks and translate them individually, then reassemble the translated parts.","message":"The Google Translate web API (and thus googletrans) has a maximum character limit of approximately 15,000 characters per single translation request.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'3.8':57 '4.0.2':32 'activ':60 'ajax':21 'api':15,22,41,65 'async':39 'async-on':38 'automat':46 'bulk':44 'client':66 'compat':54 'configur':51 'detect':25,48 'featur':35 'free':5 'googl':13,19,63 'googletran':1,2 'implement':11 'languag':24,47,68 'leverag':17 'librari':9,34 'maintain':61 'modern':37 'natur':67 'process':69 'proxi':50 'python':8,56 'support':42 'text':27 'translat':14,20,28,45,62,64 'unlimit':7 'version':31","created_at":"2026-04-09T18:41:30.548250+00:00","updated_at":"2026-04-16T15:26:01.941948+00:00","problems":[{"fix":"Explicitly define `service_urls` when initializing the `Translator` object, for example: `translator = Translator(service_urls=['translate.googleapis.com'])`. For some users, installing a specific pre-release like `pip install googletrans==4.0.0rc1` or `pip install googletrans==3.1.0a0` has also resolved it.","cause":"This error typically occurs when the `googletrans` library fails to parse the response from the Google Translate API, often due to changes in Google's internal API structure, leading to an inability to extract the translation data.","error":"AttributeError: 'NoneType' object has no attribute 'group'"},{"fix":"Install the library using pip: `pip install googletrans`. Ensure you are installing it into the correct Python environment if you are using virtual environments or multiple Python installations.","cause":"The `googletrans` package is not installed in the Python environment currently in use, or the Python interpreter cannot locate the installed package.","error":"ModuleNotFoundError: No module named 'googletrans'"},{"fix":"Rewrite your translation code to use Python's `async` and `await` syntax. Define an `async` function, instantiate the `Translator` within an `async with` block, and `await` the `translate` call.\n\n```python\nimport asyncio\nfrom googletrans import Translator\n\nasync def translate_text(text, dest_lang='en'):\n    async with Translator() as translator:\n        result = await translator.translate(text, dest=dest_lang)\n        return result.text\n\n# Example usage:\n# translated_string = asyncio.run(translate_text('안녕하세요.'))\n# print(translated_string)\n```","cause":"With `googletrans` version 4.0.0 and later (including 4.0.2), the library transitioned to an asynchronous-only API. This error occurs when attempting to call `translate` synchronously without using `await` inside an `async` function.","error":"AttributeError: 'Translator' object has no attribute 'translate'"},{"fix":"To mitigate rate limiting, introduce delays between translation requests, consider using a proxy, or provide multiple service URLs to the `Translator` constructor to distribute requests.\n\n```python\nfrom googletrans import Translator\nimport time\n\ntranslator = Translator(service_urls=[\n  'translate.google.com',\n  'translate.google.co.kr',\n  'translate.google.cn'\n])\n\ndef translate_with_delay(text, dest_lang='en'):\n    # In an async context, you would use await asyncio.sleep(delay)\n    time.sleep(1) # Add a delay between requests\n    result = translator.translate(text, dest=dest_lang)\n    return result.text\n\n# Note: For async API (googletrans 4.0.2), this synchronous example\n# would need to be adapted to use async/await with an async sleep.\n```","cause":"This error, or similar HTTP 5xx errors, indicates that your IP address has been temporarily banned or rate-limited by Google due to sending too many requests in a short period, as `googletrans` uses the unofficial web API.","error":"Exception: Unexpected status code \"429\" from ['translate.google.com']"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.0.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/ssut/py-googletrans","docs":null,"changelog":null,"pypi":"https://pypi.org/project/googletrans/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","http-networking","gcp"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}