{"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":"en","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,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}