0
# V3 Translation Services
1

2
Core translation functionality in the V3 API, including text translation, document translation, batch operations, language detection, romanization, and supported language queries. This is the recommended API version for new applications.
3

4
## Core Imports
5

6
```python
7
from google.cloud import translate_v3
8
from google.cloud.translate_v3 import TranslationServiceClient
9
```
10

11
## Client Classes
12

13
```python { .api }
14
class TranslationServiceClient:
15
    """
16
    Synchronous client for Translation Service V3 API.
17
    
18
    Args:
19
        credentials: OAuth2 credentials for authentication
20
        transport: Transport implementation ('grpc', 'grpc_asyncio', 'rest')
21
        client_options: Client configuration options
22
        client_info: Client info for user-agent string
23
    """
24
    def __init__(
25
        self,
26
        *,
27
        credentials=None,
28
        transport=None,
29
        client_options=None,
30
        client_info=None,
31
    ): ...
32

33
class TranslationServiceAsyncClient:
34
    """
35
    Asynchronous client for Translation Service V3 API.
36
    """
37
    def __init__(
38
        self,
39
        *,
40
        credentials=None,
41
        transport="grpc_asyncio",
42
        client_options=None,
43
        client_info=None,
44
    ): ...
45
```
46

47
## Capabilities
48

49
### Text Translation
50

51
Translate text content with advanced options including glossaries, models, and format specifications.
52

53
```python { .api }
54
def translate_text(
55
    self,
56
    request=None,
57
    *,
58
    parent=None,
59
    contents=None,
60
    mime_type=None,
61
    source_language_code=None,
62
    target_language_code=None,
63
    retry=None,
64
    timeout=None,
65
    metadata=()
66
):
67
    """
68
    Translates input text and returns translated text.
69
    
70
    Args:
71
        request (TranslateTextRequest): The request object
72
        parent (str): Project/location resource name (projects/{project}/locations/{location})
73
        contents (list): Text content to translate
74
        mime_type (str): MIME type of content ('text/plain' or 'text/html')
75
        source_language_code (str): Source language code (BCP-47)
76
        target_language_code (str): Target language code (BCP-47)
77
        retry: Retry configuration
78
        timeout (float): Request timeout in seconds
79
        metadata: Additional metadata
80
    
81
    Returns:
82
        TranslateTextResponse: Translation results with detected language info
83
    """
84
```
85

86
### Document Translation
87

88
Translate entire documents while preserving formatting and structure.
89

90
```python { .api }
91
def translate_document(
92
    self,
93
    request=None,
94
    *,
95
    parent=None,
96
    source_language_code=None,
97
    target_language_code=None,
98
    document_input_config=None,
99
    document_output_config=None,
100
    model=None,
101
    glossary_config=None,
102
    retry=None,
103
    timeout=None,
104
    metadata=()
105
):
106
    """
107
    Translates documents in synchronous mode.
108
    
109
    Args:
110
        request (TranslateDocumentRequest): The request object
111
        parent (str): Project/location resource name
112
        source_language_code (str): Source language code
113
        target_language_code (str): Target language code
114
        document_input_config (DocumentInputConfig): Document input configuration
115
        document_output_config (DocumentOutputConfig): Document output configuration
116
        model (str): Custom model to use for translation
117
        glossary_config (TranslateTextGlossaryConfig): Glossary configuration
118
        retry: Retry configuration
119
        timeout (float): Request timeout in seconds
120
        metadata: Additional metadata
121
    
122
    Returns:
123
        TranslateDocumentResponse: Document translation result
124
    """
125
```
126

127
### Batch Text Translation
128

129
Translate large volumes of text content asynchronously with Cloud Storage integration.
130

131
```python { .api }
132
def batch_translate_text(
133
    self,
134
    request=None,
135
    *,
136
    parent=None,
137
    source_language_code=None,
138
    target_language_codes=None,
139
    input_configs=None,
140
    output_config=None,
141
    retry=None,
142
    timeout=None,
143
    metadata=()
144
):
145
    """
146
    Translates a large volume of text in asynchronous batch mode.
147
    
148
    Args:
149
        request (BatchTranslateTextRequest): The request object
150
        parent (str): Project/location resource name
151
        source_language_code (str): Source language code
152
        target_language_codes (list): List of target language codes
153
        input_configs (list): Input file configurations
154
        output_config (OutputConfig): Output configuration
155
        retry: Retry configuration
156
        timeout (float): Request timeout in seconds
157
        metadata: Additional metadata
158
    
159
    Returns:
160
        Operation: Long-running operation for batch translation
161
    """
162
```
163

164
### Batch Document Translation
165

166
Translate multiple documents asynchronously while preserving formatting.
167

168
```python { .api }
169
def batch_translate_document(
170
    self,
171
    request=None,
172
    *,
173
    parent=None,
174
    source_language_code=None,
175
    target_language_codes=None,
176
    input_configs=None,
177
    output_config=None,
178
    retry=None,
179
    timeout=None,
180
    metadata=()
181
):
182
    """
183
    Translates a large volume of documents in asynchronous batch mode.
184
    
185
    Args:
186
        request (BatchTranslateDocumentRequest): The request object
187
        parent (str): Project/location resource name
188
        source_language_code (str): Source language code
189
        target_language_codes (list): List of target language codes
190
        input_configs (list): Input configuration for documents
191
        output_config (BatchDocumentOutputConfig): Output configuration
192
        retry: Retry configuration
193
        timeout (float): Request timeout in seconds
194
        metadata: Additional metadata
195
    
196
    Returns:
197
        Operation: Long-running operation for batch document translation
198
    """
199
```
200

201
### Language Detection
202

203
Detect the language of input text with confidence scores and multiple language detection.
204

205
```python { .api }
206
def detect_language(
207
    self,
208
    request=None,
209
    *,
210
    parent=None,
211
    content=None,
212
    mime_type=None,
213
    model=None,
214
    retry=None,
215
    timeout=None,
216
    metadata=()
217
):
218
    """
219
    Detects the language of text within a request.
220
    
221
    Args:
222
        request (DetectLanguageRequest): The request object
223
        parent (str): Project/location resource name
224
        content (str): Text content to analyze
225
        mime_type (str): MIME type of content
226
        model (str): Optional model to use for detection
227
        retry: Retry configuration
228
        timeout (float): Request timeout in seconds
229
        metadata: Additional metadata
230
    
231
    Returns:
232
        DetectLanguageResponse: Language detection results with confidence scores
233
    """
234
```
235

236
### Supported Languages
237

238
Query available translation languages and their capabilities.
239

240
```python { .api }
241
def get_supported_languages(
242
    self,
243
    request=None,
244
    *,
245
    parent=None,
246
    display_language_code=None,
247
    model=None,
248
    retry=None,
249
    timeout=None,
250
    metadata=()
251
):
252
    """
253
    Returns a list of supported languages for translation.
254
    
255
    Args:
256
        request (GetSupportedLanguagesRequest): The request object
257
        parent (str): Project/location resource name
258
        display_language_code (str): Language code for language names
259
        model (str): Optional model to get languages for
260
        retry: Retry configuration
261
        timeout (float): Request timeout in seconds
262
        metadata: Additional metadata
263
    
264
    Returns:
265
        SupportedLanguages: List of supported languages with metadata
266
    """
267
```
268

269
### Text Romanization
270

271
Convert text to Latin script for languages that use non-Latin writing systems.
272

273
```python { .api }
274
def romanize_text(
275
    self,
276
    request=None,
277
    *,
278
    parent=None,
279
    contents=None,
280
    source_language_code=None,
281
    retry=None,
282
    timeout=None,
283
    metadata=()
284
):
285
    """
286
    Romanize input text to Latin script.
287
    
288
    Args:
289
        request (RomanizeTextRequest): The request object
290
        parent (str): Project/location resource name
291
        contents (list): Text content to romanize
292
        source_language_code (str): Source language code
293
        retry: Retry configuration
294
        timeout (float): Request timeout in seconds
295
        metadata: Additional metadata
296
    
297
    Returns:
298
        RomanizeTextResponse: Romanized text results
299
    """
300
```
301

302
## Usage Examples
303

304
### Basic Text Translation
305

306
```python
307
from google.cloud import translate_v3
308

309
client = translate_v3.TranslationServiceClient()
310

311
parent = "projects/my-project/locations/us-central1"
312

313
response = client.translate_text(
314
    request={
315
        "parent": parent,
316
        "contents": ["Hello, world!", "How are you?"],
317
        "mime_type": "text/plain",
318
        "source_language_code": "en",
319
        "target_language_code": "es",
320
    }
321
)
322

323
for translation in response.translations:
324
    print(f"Translated: {translation.translated_text}")
325
```
326

327
### Document Translation
328

329
```python
330
from google.cloud import translate_v3
331

332
client = translate_v3.TranslationServiceClient()
333

334
parent = "projects/my-project/locations/us-central1"
335

336
# Read document content
337
with open("document.txt", "rb") as f:
338
    document_content = f.read()
339

340
document_input_config = {
341
    "content": document_content,
342
    "mime_type": "text/plain"
343
}
344

345
response = client.translate_document(
346
    request={
347
        "parent": parent,
348
        "source_language_code": "en",
349
        "target_language_code": "fr",
350
        "document_input_config": document_input_config,
351
    }
352
)
353

354
print(f"Translated document: {response.document_translation.byte_stream_outputs}")
355
```
356

357
### Language Detection
358

359
```python
360
from google.cloud import translate_v3
361

362
client = translate_v3.TranslationServiceClient()
363

364
parent = "projects/my-project/locations/us-central1"
365

366
response = client.detect_language(
367
    request={
368
        "parent": parent,
369
        "content": "Bonjour le monde",
370
        "mime_type": "text/plain",
371
    }
372
)
373

374
for language in response.languages:
375
    print(f"Language: {language.language_code}")
376
    print(f"Confidence: {language.confidence}")
377
```
378

379
### Batch Translation with Cloud Storage
380

381
```python
382
from google.cloud import translate_v3
383

384
client = translate_v3.TranslationServiceClient()
385

386
parent = "projects/my-project/locations/us-central1"
387

388
input_config = {
389
    "gcs_source": {
390
        "input_uri": "gs://my-bucket/input/"
391
    },
392
    "mime_type": "text/plain"
393
}
394

395
output_config = {
396
    "gcs_destination": {
397
        "output_uri_prefix": "gs://my-bucket/output/"
398
    }
399
}
400

401
operation = client.batch_translate_text(
402
    request={
403
        "parent": parent,
404
        "source_language_code": "en",
405
        "target_language_codes": ["es", "fr"],
406
        "input_configs": [input_config],
407
        "output_config": output_config,
408
    }
409
)
410

411
print(f"Operation name: {operation.name}")
412

413
# Wait for operation to complete
414
result = operation.result(timeout=3600)
415
print(f"Total characters: {result.total_characters}")
416
print(f"Translated characters: {result.translated_characters}")
417
```