Google Cloud Translate Python Client

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.

Install

• pip install google-cloud-translate Install stable version

Imports

• TranslationServiceClient

  from google.cloud import translate

  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

  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()`.

Quickstart

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}")