gpytranslate

2.1.0 verified Fri May 01 auth: no python

An async-first Python library for translating text using the Google Translate API. Currently at version 2.1.0, it requires Python >=3.12 and uses aiohttp for async HTTP requests. The library provides both async (Translator) and sync (SyncTranslator) interfaces, along with language detection and text-to-speech (TTS) support. Releases are sporadic, with the last major update in 2025.

pip install gpytranslate

Common errors

error AttributeError: module 'gpytranslate' has no attribute 'Translator' ↓

cause The library was not correctly installed or imported due to a broken installation.

fix

Reinstall: pip install --upgrade gpytranslate. Verify import in a fresh Python session.

error gpytranslate.TranslateError: Too many requests ↓

cause Google Translate API rate limit exceeded.

fix

Add delays between requests or use a proxy rotation. Reduce request frequency.

error RuntimeError: asyncio.run() cannot be called from a running event loop ↓

cause Trying to use asyncio.run() inside an async context (e.g., Jupyter notebook or another async function).

fix

Use await directly in async context or use asyncio.run() only from sync entry points.

Warnings

breaking Version 2.0.0 dropped support for Python <3.12. Install with pip will fail on older interpreters. ↓

fix Upgrade to Python 3.12+ or pin to gpytranslate==1.5.1 if you need older Python.

breaking The Translator class now uses an async context manager (async with) for proper resource cleanup. Using it without a context manager may leak connections in older code. ↓

fix Wrap usage in `async with Translator() as t:` or explicitly call `await t.close()` when done.

gotcha Google Translate may rate-limit requests. The library raises TranslateError in such cases, not JSON errors. Catching generic Exception may hide the cause. ↓

fix Catch `gpytranslate.TranslateError` specifically and implement retry logic with exponential backoff.

gotcha The sync translator (SyncTranslator) is not a context manager; you must create and use it directly. Attempting `async with SyncTranslator()` will raise AttributeError. ↓

fix Use: `t = SyncTranslator(); result = t.translate(...)`

deprecated The `__version__` attribute on Translator instances is deprecated; use `gpytranslate.__version__` instead. ↓

fix Replace `translator.__version__` with `from gpytranslate import __version__`

Imports

Translator

wrong

from gpytranslate.translator import Translator

correct

from gpytranslate import Translator

Translator is re-exported at the package level.

SyncTranslator

wrong

from gpytranslate.sync import SyncTranslator

correct

from gpytranslate import SyncTranslator

SyncTranslator is re-exported at the package level.

Quickstart

Basic async translation example using Translator as an async context manager.

import asyncio
from gpytranslate import Translator

async def main():
    async with Translator() as t:
        result = await t.translate("Hello world", sourcelang="en", targetlang="es")
        print(result.text)  # Output: Hola mundo

asyncio.run(main())