Google Cloud Translate Python Client
raw JSON → 3.25.0 verified Tue May 12 auth: no python install: verified
The `google-cloud-translate` client library provides Python programmatic access to Google Cloud Translation API. It allows dynamic translation of text between thousands of language pairs and detection of source languages. The current stable version is 3.25.0, and the library is actively maintained with frequent updates as part of the broader `google-cloud-python` ecosystem.
pip install google-cloud-translate Common errors
error google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials. ↓
cause Your application is unable to find valid Google Cloud authentication credentials in its environment.
fix
Set 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. error 403 Daily Limit Exceeded ↓
cause Your Google Cloud project has exceeded the configured quota for the Cloud Translation API, or billing is not enabled for the project.
fix
Check 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.
error ModuleNotFoundError: No module named 'google' ↓
cause 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.
fix
Ensure 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. error INVALID_ARGUMENT: Text is too long ↓
cause The input text for a single translation request exceeds the maximum character limit allowed by the Cloud Translation API.
fix
Break 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.
error AttributeError: module 'google.cloud.translate' has no attribute 'Client' ↓
cause 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`.
fix
Import and use
TranslationServiceClient from google.cloud.translate_v3 to instantiate the client: from google.cloud import translate_v3; client = translate_v3.TranslationServiceClient(). Warnings
breaking The `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. ↓
fix Update 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.
deprecated The 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. ↓
fix Migrate 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.
gotcha There 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. ↓
fix For 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.
gotcha The 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. ↓
fix Ensure 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`.
gotcha Google 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. ↓
fix Split 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.
gotcha Exceeding API usage quotas (e.g., characters per second, characters per month) can lead to `ResourceExhausted` errors. ↓
fix Monitor 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.
gotcha When 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. ↓
fix Set 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').
gotcha Client 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. ↓
fix Set 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.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 2.16s 71.5M
3.10 alpine (musl) - - 2.00s 70.3M
3.10 slim (glibc) wheel 6.2s 1.23s 69M
3.10 slim (glibc) - - 1.14s 68M
3.11 alpine (musl) wheel - 2.65s 76.5M
3.11 alpine (musl) - - 3.31s 75.3M
3.11 slim (glibc) wheel 5.6s 1.75s 74M
3.11 slim (glibc) - - 1.68s 73M
3.12 alpine (musl) wheel - 2.81s 67.9M
3.12 alpine (musl) - - 2.99s 66.8M
3.12 slim (glibc) wheel 4.5s 2.10s 66M
3.12 slim (glibc) - - 2.31s 64M
3.13 alpine (musl) wheel - 2.56s 67.5M
3.13 alpine (musl) - - 3.02s 66.3M
3.13 slim (glibc) wheel 4.5s 2.01s 65M
3.13 slim (glibc) - - 2.48s 64M
3.9 alpine (musl) wheel - 1.94s 71.6M
3.9 alpine (musl) - - 1.87s 70.5M
3.9 slim (glibc) wheel 7.0s 1.44s 69M
3.9 slim (glibc) - - 1.24s 68M
Imports
- TranslationServiceClient wrong
from google.cloud import translate_v3correctfrom google.cloud import translate - TranslationServiceClient wrong
from google.cloud.translate import Clientcorrectfrom google.cloud.translate_v3 import TranslationServiceClient - Client
from google.cloud import translate_v2
Quickstart last tested: 2026-04-24
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}")