0
# Google Cloud Translate
1

2
A comprehensive Python client library for Google Cloud Translate API, enabling developers to dynamically translate text between thousands of language pairs. The library offers programmatic integration with Google's translation service, supporting both basic text translation and advanced features through multiple API versions (v2, v3, v3beta1).
3

4
## Package Information
5

6
- **Package Name**: google-cloud-translate
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-translate`
9

10
## Core Imports
11

12
Primary import (provides V3 API by default):
13

14
```python
15
from google.cloud import translate
16
```
17

18
This gives access to the main TranslationServiceClient and all V3 types:
19

20
```python
21
from google.cloud.translate import TranslationServiceClient, TranslationServiceAsyncClient
22
```
23

24
For specific API versions:
25

26
```python
27
# V2 API (legacy)
28
from google.cloud import translate_v2
29

30
# V3 API (explicit)
31
from google.cloud import translate_v3
32

33
# V3 Beta API
34
from google.cloud import translate_v3beta1
35
```
36

37
## Basic Usage
38

39
### Simple Translation (V3 - Recommended)
40

41
```python
42
from google.cloud import translate
43

44
# Create a client (uses V3 by default)
45
client = translate.TranslationServiceClient()
46

47
# Configure the parent resource name
48
parent = f"projects/{project_id}/locations/{location}"
49

50
# Translate text
51
response = client.translate_text(
52
    request={
53
        "parent": parent,
54
        "contents": ["Hello, world!"],
55
        "mime_type": "text/plain",
56
        "source_language_code": "en",
57
        "target_language_code": "es",
58
    }
59
)
60

61
for translation in response.translations:
62
    print(f"Translated text: {translation.translated_text}")
63
```
64

65
### Legacy Translation (V2)
66

67
```python
68
from google.cloud import translate_v2 as translate
69

70
client = translate.Client()
71

72
# Translate text
73
result = client.translate(
74
    "Hello, world!",
75
    target_language="es",
76
    source_language="en"
77
)
78

79
print(f"Text: {result['input']}")
80
print(f"Translation: {result['translatedText']}")
81
print(f"Detected source language: {result['detectedSourceLanguage']}")
82
```
83

84
## Architecture
85

86
The library provides three distinct API versions with different capabilities:
87

88
- **V2 API**: Legacy REST-based API with simple translation, detection, and language listing functionality
89
- **V3 API**: Full-featured gRPC/REST API with advanced capabilities including adaptive MT, AutoML, glossaries, and document translation
90
- **V3Beta1 API**: Beta version with core translation features and glossary support
91

92
Each API version provides both synchronous and asynchronous clients, comprehensive type definitions, transport layer abstractions, and pagination support for list operations.
93

94
## Capabilities
95

96
### V2 Legacy API
97

98
Simple REST-based translation API with basic functionality including text translation, language detection, and supported language listing.
99

100
```python { .api }
101
class Client:
102
    def get_languages(self, target_language=None): ...
103
    def detect_language(self, values): ...
104
    def translate(self, values, target_language=None, format_=None, source_language=None, customization_ids=(), model=None): ...
105
```
106

107
[V2 Legacy API](./v2-legacy-api.md)
108

109
### V3 Translation Services
110

111
Core translation functionality including text translation, document translation, batch operations, language detection, and romanization.
112

113
```python { .api }
114
class TranslationServiceClient:
115
    def translate_text(self, request=None, **kwargs): ...
116
    def translate_document(self, request=None, **kwargs): ...
117
    def batch_translate_text(self, request=None, **kwargs): ...
118
    def batch_translate_document(self, request=None, **kwargs): ...
119
    def detect_language(self, request=None, **kwargs): ...
120
    def get_supported_languages(self, request=None, **kwargs): ...
121
    def romanize_text(self, request=None, **kwargs): ...
122
```
123

124
[V3 Translation Services](./v3-translation-services.md)
125

126
### V3 Adaptive Machine Translation
127

128
Advanced machine translation using custom datasets and models trained on domain-specific translation pairs for improved accuracy in specialized contexts.
129

130
```python { .api }
131
class TranslationServiceClient:
132
    def create_adaptive_mt_dataset(self, request=None, **kwargs): ...
133
    def list_adaptive_mt_datasets(self, request=None, **kwargs): ...
134
    def get_adaptive_mt_dataset(self, request=None, **kwargs): ...
135
    def delete_adaptive_mt_dataset(self, request=None, **kwargs): ...
136
    def adaptive_mt_translate(self, request=None, **kwargs): ...
137
    def import_adaptive_mt_file(self, request=None, **kwargs): ...
138
    def list_adaptive_mt_files(self, request=None, **kwargs): ...
139
    def get_adaptive_mt_file(self, request=None, **kwargs): ...
140
    def delete_adaptive_mt_file(self, request=None, **kwargs): ...
141
    def list_adaptive_mt_sentences(self, request=None, **kwargs): ...
142
```
143

144
[V3 Adaptive Machine Translation](./v3-adaptive-mt.md)
145

146
### V3 Glossary Management
147

148
Translation glossaries for consistent terminology translation, including creation, management, and application of custom dictionaries for domain-specific translations.
149

150
```python { .api }
151
class TranslationServiceClient:
152
    def create_glossary(self, request=None, **kwargs): ...
153
    def update_glossary(self, request=None, **kwargs): ...
154
    def list_glossaries(self, request=None, **kwargs): ...
155
    def get_glossary(self, request=None, **kwargs): ...
156
    def delete_glossary(self, request=None, **kwargs): ...
157
    def create_glossary_entry(self, request=None, **kwargs): ...
158
    def update_glossary_entry(self, request=None, **kwargs): ...
159
    def list_glossary_entries(self, request=None, **kwargs): ...
160
    def get_glossary_entry(self, request=None, **kwargs): ...
161
    def delete_glossary_entry(self, request=None, **kwargs): ...
162
```
163

164
[V3 Glossary Management](./v3-glossary-management.md)
165

166
### V3 AutoML Translation
167

168
Custom machine learning model training and management for specialized translation needs, including dataset creation, model training, and custom model usage.
169

170
```python { .api }
171
class TranslationServiceClient:
172
    def create_dataset(self, request=None, **kwargs): ...
173
    def list_datasets(self, request=None, **kwargs): ...
174
    def get_dataset(self, request=None, **kwargs): ...
175
    def delete_dataset(self, request=None, **kwargs): ...
176
    def import_data(self, request=None, **kwargs): ...
177
    def export_data(self, request=None, **kwargs): ...
178
    def list_examples(self, request=None, **kwargs): ...
179
    def create_model(self, request=None, **kwargs): ...
180
    def list_models(self, request=None, **kwargs): ...
181
    def get_model(self, request=None, **kwargs): ...
182
    def delete_model(self, request=None, **kwargs): ...
183
```
184

185
[V3 AutoML Translation](./v3-automl-translation.md)
186

187
### Request and Response Types
188

189
Complete type definitions for all request and response objects used across the V3 API, including translation requests, document configurations, and metadata structures.
190

191
```python { .api }
192
class TranslateTextRequest: ...
193
class TranslateTextResponse: ...
194
class TranslateDocumentRequest: ...
195
class TranslateDocumentResponse: ...
196
class DetectLanguageRequest: ...
197
class DetectLanguageResponse: ...
198
```
199

200
[Request and Response Types](./v3-request-response-types.md)
201

202
### Data Structures and Enums  
203

204
Core data structures, enums, and configuration objects used throughout the API, including language definitions, operation states, and input/output configurations.
205

206
```python { .api }
207
class SupportedLanguages: ...
208
class DetectedLanguage: ...
209
class Translation: ...
210
class Glossary: ...
211
class AdaptiveMtDataset: ...
212
class Dataset: ...
213
class Model: ...
214
class OperationState: ...
215
```
216

217
[Data Structures and Enums](./v3-data-structures.md)