Install & Compatibility
Where this runs
tested against v3.27.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.142s · 72.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.6s · import 1.392s · 71MB
71MB installed
● package 71MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TranslationServiceClient
✓ from google.cloud import translate
✗ from google.cloud import translate_v3
While `translate_v3` works, the idiomatic import is `from google.cloud import translate` which provides `translate.TranslationServiceClient`. Using `translate_v3` directly is not incorrect but less common in quickstarts.
TranslationServiceClient
✓ from google.cloud.translate_v3 import TranslationServiceClient
✗ from google.cloud.translate import Client
The `Client` class is for the older v2 API. For v3, use `TranslationServiceClient`. Directly importing `Client` from `google.cloud.translate` will result in an AttributeError for v3 setups.
Client
✓ from google.cloud import translate_v2
For using the older (Basic) v2 API, import explicitly as `translate_v2` and then access `translate_v2.Client()`.
This quickstart demonstrates how to translate text and detect its language using the Google Cloud Translation v3 API. It relies on Application Default Credentials for authentication and requires a Google Cloud project with the Cloud Translation API enabled. Set your `GOOGLE_CLOUD_PROJECT` environment variable for seamless authentication.
import os
from google.cloud import translate
# Your Google Cloud Project ID
# Set the environment variable GOOGLE_CLOUD_PROJECT or replace with your Project ID
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT", "your-project-id")
if project_id == "your-project-id":
print("WARNING: Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-project-id' with your actual project ID.")
print("Authentication may fail without a valid project ID.")
# Create a client for the v3 API
client = translate.TranslationServiceClient()
# The 'parent' parameter specifies the project and location
# 'global' is a common location, but you can specify other regions if needed.
parent = f"projects/{project_id}/locations/global"
text_to_translate = "Hello, world!"
target_language = "es"
source_language = "en"
# Translate text using the v3 API
try:
response = client.translate_text(
request={
"parent": parent,
"contents": [text_to_translate],
"mime_type": "text/plain",
"source_language_code": source_language,
"target_language_code": target_language,
}
)
print(f"Original text: {text_to_translate}")
for translation in response.translations:
print(f"Translated text: {translation.translated_text}")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure you have enabled the Cloud Translation API for your project and configured authentication (e.g., GOOGLE_APPLICATION_CREDENTIALS).")
# Example for language detection (v3)
# client for v3 is the same
text_to_detect = "Bonjour le monde!"
try:
response = client.detect_language(
request={
"parent": parent,
"content": text_to_detect,
"mime_type": "text/plain",
}
)
print(f"\nText for detection: {text_to_detect}")
for language in response.languages:
print(f"Detected language: {language.language_code} (Confidence: {language.confidence:.2f})")
except Exception as e:
print(f"An error occurred during language detection: {e}")
Debug
Known issues
breakingThe `google-cloud-translate` library version 3.0.0 introduced significant breaking changes. Method calls now typically require a single `request` parameter (a dictionary or a request object) instead of multiple positional arguments.fixUpdate method calls to pass parameters within a `request` dictionary, e.g., `client.translate_text(request={'parent': parent, 'contents': [text]})` instead of `client.translate_text(parent, [text])`. A migration script (`fixup_translation_v3_keywords.py`) is provided with the library for common use cases. affects: >=3.0.0
deprecatedThe v2 (Basic) API and its corresponding `google.cloud.translate_v2` module are considered legacy. While still functional for basic translations, new development should strongly prefer the v3 (Advanced) API for access to features like glossaries, batch document translation, and AutoML models.fixMigrate new projects to use the v3 API (`google.cloud.translate.TranslationServiceClient`). For existing v2 applications, assess if new features are needed and plan migration. Authentication for v3 also strongly prefers IAM service accounts over API keys.
affects: <3.0.0 (v2 API is separate but bundled)
gotchaThere are distinct client classes and import paths for v2 and v3 of the Translation API. Attempting to use `from google.cloud.translate import Client` for v3, or `from google.cloud import translate` and expecting v2 behavior will lead to `AttributeError` or unexpected results.fixFor v2, use `from google.cloud import translate_v2; client = translate_v2.Client()`. For v3, use `from google.cloud import translate; client = translate.TranslationServiceClient()`. Be mindful of which API version you intend to use.
affects: All versions
gotchaThe v3 API requires explicit specification of the `parent` parameter (formatted as `projects/{PROJECT_ID}/locations/{LOCATION}`) for almost all requests. This differs from v2, which could often infer project context or use simpler API key authentication.fixEnsure all v3 API calls include the `parent` parameter, typically set to `f"projects/{YOUR_PROJECT_ID}/locations/global"` or a specific region like `us-central1`. affects: >=3.0.0
gotchaGoogle Cloud Translation API has content size limits per request (e.g., 30,000 code points for v3 Advanced, 100,000 bytes for v2 Basic). Exceeding these limits will result in a `400 INVALID_ARGUMENT` error.fixSplit large texts into smaller chunks before sending them for translation. Consider using batch translation features for very large datasets where supported by the API version.
affects: All versions
gotchaExceeding API usage quotas (e.g., characters per second, characters per month) can lead to `ResourceExhausted` errors.fixMonitor your API usage in the Google Cloud Console. Implement strategies like exponential backoff for retries and batching multiple small translation requests into a single API call to optimize usage and stay within limits.
affects: All versions
gotchaWhen running Google Cloud Translation client libraries outside of Google Cloud environments (e.g., on a local machine or a non-GCP server), Application Default Credentials (ADC) must be explicitly set up. Failure to do so will result in a `google.auth.exceptions.DefaultCredentialsError` because the client cannot find credentials to authenticate.fixSet up Application Default Credentials by running `gcloud auth application-default login` or by explicitly setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key file. Ensure the authenticated principal has the necessary permissions (e.g., 'Cloud Translation API User').
affects: All versions
gotchaClient instantiation for v3 services (e.g., `TranslationServiceClient`) requires valid Google Cloud authentication. Without Application Default Credentials (ADC) or explicitly provided credentials, a `google.auth.exceptions.DefaultCredentialsError` will occur.fixSet up Application Default Credentials (ADC) for your environment. This can typically be done by running `gcloud auth application-default login` (for user credentials) or by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key file.
affects: >=3.0.0
Errors
Common errors & fixes
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials.
Your application is unable to find valid Google Cloud authentication credentials in its environment.
fixSet the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account key file (JSON), or run `gcloud auth application-default login` to set up Application Default Credentials for local development.
403 Daily Limit Exceeded
Your Google Cloud project has exceeded the configured quota for the Cloud Translation API, or billing is not enabled for the project.
fixCheck your API quotas and billing status in the Google Cloud Console. Enable billing if it's disabled, or request a quota increase if your daily usage legitimately exceeds the current limits.
ModuleNotFoundError: No module named 'google'
The `google-cloud-translate` library or its foundational `google-api-core` package is not correctly installed or accessible within your Python environment, or there's an issue with Python path configuration.
fixEnsure the `google-cloud-translate` library is installed in your active Python environment using `pip install google-cloud-translate`. Verify your Python environment and package paths, especially in isolated environments like virtualenvs or Docker.
INVALID_ARGUMENT: Text is too long
The input text for a single translation request exceeds the maximum character limit allowed by the Cloud Translation API.
fixBreak down your input text into smaller segments to comply with the API's character limits (e.g., 30K characters for Translation API v3 Advanced) or consider using batch translation for larger volumes.
AttributeError: module 'google.cloud.translate' has no attribute 'Client'
You are attempting to instantiate the translation client using an outdated or incorrect class name, often a relic from older library versions (like v2's `Client`). The current `google-cloud-translate` library (v3) uses `TranslationServiceClient`.
fixImport and use `TranslationServiceClient` from `google.cloud.translate_v3` to instantiate the client: `from google.cloud import translate_v3; client = translate_v3.TranslationServiceClient()`.
Upgrade
Version history
3.27.0latest on PyPI · released Jun 22, 2026
Audit
Dependencies
google-api-corerequiredCore dependency for Google Cloud client libraries, handles API requests and common functionalities.
pythonrequiredRequires Python 3.9 or higher.