{"id":871,"library":"google-cloud-translate","title":"Google Cloud Translate Python Client","description":"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.","status":"active","version":"3.25.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-translate","tags":["google-cloud","translation","nlp","i18n","machine-learning"],"install":[{"cmd":"pip install google-cloud-translate","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for Google Cloud client libraries, handles API requests and common functionalities.","package":"google-api-core","optional":false},{"reason":"Requires Python 3.9 or higher.","package":"python","optional":false}],"imports":[{"note":"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.","wrong":"from google.cloud import translate_v3","symbol":"TranslationServiceClient","correct":"from google.cloud import translate"},{"note":"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.","wrong":"from google.cloud.translate import Client","symbol":"TranslationServiceClient","correct":"from google.cloud.translate_v3 import TranslationServiceClient"},{"note":"For using the older (Basic) v2 API, import explicitly as `translate_v2` and then access `translate_v2.Client()`.","symbol":"Client","correct":"from google.cloud import translate_v2"}],"quickstart":{"code":"import os\nfrom google.cloud import translate\n\n# Your Google Cloud Project ID\n# Set the environment variable GOOGLE_CLOUD_PROJECT or replace with your Project ID\nproject_id = os.environ.get(\"GOOGLE_CLOUD_PROJECT\", \"your-project-id\")\n\nif project_id == \"your-project-id\":\n    print(\"WARNING: Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-project-id' with your actual project ID.\")\n    print(\"Authentication may fail without a valid project ID.\")\n\n# Create a client for the v3 API\nclient = translate.TranslationServiceClient()\n\n# The 'parent' parameter specifies the project and location\n# 'global' is a common location, but you can specify other regions if needed.\nparent = f\"projects/{project_id}/locations/global\"\n\ntext_to_translate = \"Hello, world!\"\ntarget_language = \"es\"\nsource_language = \"en\"\n\n# Translate text using the v3 API\ntry:\n    response = client.translate_text(\n        request={\n            \"parent\": parent,\n            \"contents\": [text_to_translate],\n            \"mime_type\": \"text/plain\",\n            \"source_language_code\": source_language,\n            \"target_language_code\": target_language,\n        }\n    )\n\n    print(f\"Original text: {text_to_translate}\")\n    for translation in response.translations:\n        print(f\"Translated text: {translation.translated_text}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure you have enabled the Cloud Translation API for your project and configured authentication (e.g., GOOGLE_APPLICATION_CREDENTIALS).\")\n\n# Example for language detection (v3)\n# client for v3 is the same\ntext_to_detect = \"Bonjour le monde!\"\n\ntry:\n    response = client.detect_language(\n        request={\n            \"parent\": parent,\n            \"content\": text_to_detect,\n            \"mime_type\": \"text/plain\",\n        }\n    )\n    print(f\"\\nText for detection: {text_to_detect}\")\n    for language in response.languages:\n        print(f\"Detected language: {language.language_code} (Confidence: {language.confidence:.2f})\")\nexcept Exception as e:\n    print(f\"An error occurred during language detection: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<3.0.0 (v2 API is separate but bundled)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Exceeding API usage quotas (e.g., characters per second, characters per month) can lead to `ResourceExhausted` errors.","severity":"gotcha","affected_versions":"All versions"},{"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').","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-05-12T20:36:31.615Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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.","cause":"Your application is unable to find valid Google Cloud authentication credentials in its environment.","error":"google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials."},{"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.","cause":"Your Google Cloud project has exceeded the configured quota for the Cloud Translation API, or billing is not enabled for the project.","error":"403 Daily Limit Exceeded"},{"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.","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.","error":"ModuleNotFoundError: No module named 'google'"},{"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.","cause":"The input text for a single translation request exceeds the maximum character limit allowed by the Cloud Translation API.","error":"INVALID_ARGUMENT: Text is too long"},{"fix":"Import and use `TranslationServiceClient` from `google.cloud.translate_v3` to instantiate the client: `from google.cloud import translate_v3; client = translate_v3.TranslationServiceClient()`.","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`.","error":"AttributeError: module 'google.cloud.translate' has no attribute 'Client'"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.26.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.16,"mem_mb":28.4,"disk_size":"71.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2,"mem_mb":28.6,"disk_size":"70.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.2,"import_time_s":1.23,"mem_mb":22.7,"disk_size":"69M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.14,"mem_mb":22.9,"disk_size":"68M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.65,"mem_mb":30.4,"disk_size":"76.5M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.31,"mem_mb":30.6,"disk_size":"75.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.6,"import_time_s":1.75,"mem_mb":25.1,"disk_size":"74M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.68,"mem_mb":25.3,"disk_size":"73M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.81,"mem_mb":30.1,"disk_size":"67.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.99,"mem_mb":30.3,"disk_size":"66.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.5,"import_time_s":2.1,"mem_mb":24.8,"disk_size":"66M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.31,"mem_mb":25.1,"disk_size":"64M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":2.56,"mem_mb":30.5,"disk_size":"67.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.02,"mem_mb":31.1,"disk_size":"66.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.5,"import_time_s":2.01,"mem_mb":25.2,"disk_size":"65M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.48,"mem_mb":25.7,"disk_size":"64M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.94,"mem_mb":28.4,"disk_size":"71.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.87,"mem_mb":28.2,"disk_size":"70.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":7,"import_time_s":1.44,"mem_mb":22.7,"disk_size":"69M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.24,"mem_mb":22.5,"disk_size":"68M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}