Registry / gcp / google-cloud-translate

google-cloud-translate

JSON →
library3.27.0pypypi✓ verified 24d ago

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
INSTALL
IMPORT
SIG · GOOGLE-CLOUD-TRANS
G
google-cloud-translate
gcppythonv3.27.0
Install
5.6s avg
Import
1767ms
Disk
71MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 2.142s · 72.4MB
glibc
py 3.103.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.
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.
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.
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.
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.
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.
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.
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`.
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.
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.
affects: All versions
gotchaExceeding 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.
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.
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').
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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`.
fix
Import 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.
Agent activity
48 hits · last 30 days
node
42
Amazon
1
OpenAI (training)
1
Resources
google-cloud-translate — pip install google-cloud-translate · libregistry