Googletrans

Warnings

• breaking 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.
  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')`.
• gotcha 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.
  Fix: Always install the latest stable version using `pip install googletrans`. If you encounter issues, consider uninstalling `googletrans` and then reinstalling the stable version.
• gotcha 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).
  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.
• gotcha 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.
  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.
• gotcha The Google Translate web API (and thus googletrans) has a maximum character limit of approximately 15,000 characters per single translation request.
  Fix: For longer texts, split them into smaller chunks and translate them individually, then reassemble the translated parts.

Install

• pip install googletrans Latest stable release

Imports

• Translator

  from googletrans import Translator

Quickstart

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.

import asyncio
from googletrans import Translator

async def translate_text():
    translator = Translator()
    text_to_translate = "Hello, how are you?"
    
    # Translate a single text
    translation = await translator.translate(text_to_translate, dest='es')
    print(f"Original: {translation.origin}, Translated (ES): {translation.text}")

    # Translate multiple texts
    texts = ["The quick brown fox", "jumps over", "the lazy dog"]
    translations = await translator.translate(texts, dest='fr')
    for t in translations:
        print(f"Original: {t.origin} -> Translated (FR): {t.text}")

    # Detect language
    detection = await translator.detect("Bonjour")
    print(f"Detected language: {detection.lang} with confidence {detection.confidence}")

if __name__ == "__main__":
    asyncio.run(translate_text())