googletrans: an unofficial Google Translate client for Python

What googletrans actually is, and who reaches for it

googletrans is a Python library that implements a client for Google Translate by calling the same web endpoints that translate.google.com uses. The README calls it a "free and unlimited python library" and states it is compatible with Python 3.8 and above. It is aimed at people who want translation inside a Python program without signing up for a cloud billing account: script authors, data cleaning work, small internal tools, notebooks.

The project is explicit about its status. The README carries a disclaimer that this is an unofficial library using the web API of translate.google.com and is not associated with Google. That sentence is the whole trade-off in miniature. You get translation without an API key; in exchange you get an interface that Google never promised to keep working.

The feature list is short and concrete: auto language detection, bulk translations, a customizable service URL, async support, HTTP/2 support, proxy support, and complete type hints. Those are the things the library actually does. There is no glossary management, no translation memory, no formal quality control layer. If you need those, this is the wrong shelf.

The ticket mechanism, and why the library can break

The README answers a question most users would ask: why does this work when other scrapers stopped? Its explanation is that Google added a ticket mechanism to the translation service to block crawler programs, and that the author reverse engineered the obfuscated and minified JavaScript Google uses to generate that token, then reimplemented it in Python. The README links to the specific minified file it studied.

That is the mechanism. There is no private API contract here. The library reproduces a token generation step that Google controls, and the README says outright that this could be blocked at any time. This is the single most important thing to understand before adopting it. The functionality depends on an implementation detail of a web front end, not on a published interface.

On top of that, the README documents a practical escape hatch for the token problem. Because translate.google.<domain> URLs use the web app and require a token, you can point the library at translate.googleapis.com instead, which the README describes as the direct API that does not need any token to process. The README frames this as a fix for unstable token providing processes. Two service URLs, then, with different failure profiles.

Installing googletrans and translating your first string

Installation is a single pip command. The README gives it as pip install googletrans, and the package name on PyPI is googletrans. The project metadata requires Python 3.8 or newer and declares one runtime dependency, httpx with the http2 extra at version 0.27.2 or above.

$ pip install googletrans

After that, the README's basic usage example is async. You import Translator, open it as an async context manager, and await the translate call. If you omit the source language, the library asks Google to detect it.

import asyncio
from googletrans import Translator

async def translate_text():
    async with Translator() as translator:
        result = await translator.translate('안녕하세요.')
        print(result)

asyncio.run(translate_text())

The README shows the expected output as a Translated object with src=ko, dest=en, the translated text and a pronunciation field. Passing dest='ja' switches the target language, and passing src='la' forces a source language instead of detecting it.

There is also a command line entry point, registered in pyproject.toml as translate. The README's help output shows the flags: -d for destination, -s for source, and -c to detect rather than translate.

$ translate "veritas lux mea" -s la -d en
$ translate -c "안녕하세요."

The first command prints the source text, the detected or declared language, the translation and a pronunciation line. The second prints a language code and a confidence value. If you only need one-off translations, the CLI is the shortest path and requires no Python code at all.

Bulk translation and language detection in one session

The bulk feature is the one that changes how you write code. Instead of looping over strings and calling translate once per string, you pass an array. The README states that a batch of strings goes out in a single method call and a single HTTP session, and the exact same method works for arrays. The example translates three fragments into Korean and iterates over the returned translations, reading .origin and .text from each.

async def translate_bulk():
    async with Translator() as translator:
        translations = await translator.translate(['The quick brown fox', 'jumps over', 'the lazy dog'], dest='ko')
        for translation in translations:
            print(translation.origin, ' -> ', translation.text)

Whether that matters depends on your workload. A single session for a batch avoids reopening connections per string, and the README presents it as the intended way to handle many strings. It is not a documented concurrency control, though, and the README does not describe rate limiting, retry behaviour or backoff. If you are pushing thousands of strings, that silence is worth noticing before you design around it.

Detection is separate. The detect method returns a Detected object with a language code and a confidence value. The README's own examples are instructive: confidence comes back as 0.27 for a Korean sentence, 0.65 for a Japanese one, and 0.22 for an English one. Those are low numbers. Treat the confidence field as a signal to threshold on, not as a guarantee, and do not assume a high-confidence detection is correct without spot-checking your own data.

The 15k character limit, IP bans and the wrong-tool case

The README's note on library usage lists the constraints without softening them. The maximum character limit on a single text is 15k. Due to limitations of the web version of Google Translate, the API does not guarantee that the library works properly at all times, and the README asks users to use it only if they do not care about stability. If you get HTTP 5xx errors or errors like #6, the README says it is probably because Google has banned your client IP address.

That last point is the failure mode that bites hardest in production. An IP ban is not a transient error you retry through; it is a signal that your traffic pattern looks like the crawler behaviour the ticket mechanism was built to stop. The README does not document a retry policy, a backoff strategy or a way to rotate credentials. It does document proxy support as a feature, which tells you the maintainers expect some users to be routing around network-level blocks.

Where is this the wrong tool? Anywhere the answer has to be right or has to arrive. Customer-facing translation, legal or medical content, anything with an uptime commitment. For those, the README itself points elsewhere: it recommends Google's official translate API if you want a stable API. That is the project telling you where its own boundary is, and it is worth taking at face value.

googletrans compared with the official Google Cloud Translation API

The real alternative named in the README is Google's official translate API, at cloud.google.com/translate/docs. The difference is not speed or language coverage; it is the nature of the contract. The official API is a documented, versioned service you authenticate to, with a published interface and a support path. googletrans is a reverse-engineered client for a web front end, with no token of its own and no association with Google.

That difference shows up in three places. First, credentials: the official API needs a cloud project and authentication; googletrans needs nothing but a network path to Google. Second, stability: the README states plainly that googletrans does not guarantee it works properly at all times, while a commercial API carries a service commitment. Third, cost: googletrans is free, and the official API is not. The README's own recommendation is to use the official API when stability matters, which is an unusually direct piece of positioning from a project about itself.

There is a middle option inside googletrans itself. Pointing service_urls at translate.googleapis.com uses the direct API that does not need a token, per the README. That avoids the token generation step that the README says could be blocked at any time, but it does not turn the library into a supported product. It is a different endpoint, not a different guarantee.

Maintenance, licence and what an upgrade costs you

The repository is not archived. The last push was on 2026-08-08. The most recent release is v4.0.0, dated 2024-12-13, following 1.2 from 2015. The version in pyproject.toml is 4.0.2, which is ahead of the last tagged release, so the packaged version and the tagged release do not line up. If you pin by tag you may not get what is on the default branch.

The dependency surface is small: httpx[http2]>=0.27.2, which pulls in httpcore, h11, h2, hpack, hyperframe, certifi, idna, anyio and sniffio. That is a modest tree, and the lower bound on httpx is open-ended, so a future major httpx release could land in your environment without the project having tested against it. Pinning httpx yourself is a reasonable precaution given that the library's HTTP/2 support depends on it.

Development tooling is declared in pyproject.toml as pytest, pytest-asyncio, pytest-cov and ruff>=0.7. The repository also carries tox.ini, pytest.ini and a uv.lock, so there is a reproducible development setup. Note that the classifiers still list Python 3.8 through 3.12 while requires-python is >=3.8; the upper end is not capped, so newer interpreters are untested territory rather than unsupported.

The licence is MIT, declared in pyproject.toml and shipped as a LICENSE file. MIT is permissive: it lets you use, modify and redistribute the code with the copyright notice and permission notice retained. What MIT does not do is grant you anything from Google. The library is unofficial, and the README says it is not associated with Google. Your use of the underlying translation service is a separate question from the code's licence, and this article is not legal advice on that point.

Editorial conclusion

Adopt googletrans when you need quick, free translation in a script, a notebook or an internal tool, and you can tolerate the instability the README itself admits. Do not adopt it for anything user-facing or contractual: the project states it uses the web API of translate.google.com, is not associated with Google, and does not guarantee that it works properly at all times. Before writing it into a pipeline, verify two things yourself: that a translation call succeeds from your network, and that your inputs stay under the 15k character limit on a single text. Everything else follows from those two checks.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ssut/py-googletrans on GitHub