0
# Text Translation
1
2
Neural machine translation service that renders source text into multiple target languages simultaneously. Supports advanced features including automatic language detection, profanity filtering, text alignment analysis, custom translation models, and sentence boundary detection.
3
4
## Capabilities
5
6
### Translate Text
7
8
Translates input text from source language to one or more target languages using neural machine translation with extensive customization options.
9
10
```python { .api }
11
def translate(
12
body: Union[List[str], List[InputTextItem], IO[bytes]],
13
*,
14
to_language: List[str],
15
client_trace_id: Optional[str] = None,
16
from_language: Optional[str] = None,
17
text_type: Optional[Union[str, TextType]] = None,
18
category: Optional[str] = None,
19
profanity_action: Optional[Union[str, ProfanityAction]] = None,
20
profanity_marker: Optional[Union[str, ProfanityMarker]] = None,
21
include_alignment: Optional[bool] = None,
22
include_sentence_length: Optional[bool] = None,
23
suggested_from: Optional[str] = None,
24
from_script: Optional[str] = None,
25
to_script: Optional[str] = None,
26
allow_fallback: Optional[bool] = None,
27
**kwargs: Any
28
) -> List[TranslatedTextItem]
29
```
30
31
**Parameters:**
32
- `body`: Text to translate (strings, InputTextItem objects, or binary data)
33
- `to_language`: Target language codes (e.g., ["es", "fr", "de"])
34
- `from_language`: Source language code (auto-detected if omitted)
35
- `text_type`: Content type (Plain or Html)
36
- `category`: Custom translator model category ID
37
- `profanity_action`: Profanity handling (NoAction, Marked, Deleted)
38
- `profanity_marker`: Profanity marking style (Asterisk, Tag)
39
- `include_alignment`: Include word alignment projection
40
- `include_sentence_length`: Include sentence boundary information
41
- `suggested_from`: Fallback language for failed detection
42
- `from_script`/`to_script`: Script specifications for transliteration
43
- `allow_fallback`: Allow fallback to general models for custom categories
44
45
**Returns:** List of translation results with metadata
46
47
### Usage Examples
48
49
```python
50
from azure.ai.translation.text import TextTranslationClient
51
from azure.ai.translation.text.models import TextType, ProfanityAction
52
from azure.core.credentials import AzureKeyCredential
53
54
client = TextTranslationClient(
55
credential=AzureKeyCredential("your-api-key"),
56
region="your-region"
57
)
58
59
# Basic translation to multiple languages
60
response = client.translate(
61
body=["Hello, how are you?"],
62
to_language=["es", "fr", "de"]
63
)
64
65
for translation in response:
66
print(f"Detected language: {translation.detected_language.language}")
67
for result in translation.translations:
68
print(f"{result.to}: {result.text}")
69
70
# HTML content translation with profanity filtering
71
html_response = client.translate(
72
body=["<p>This is a <b>damn</b> good example!</p>"],
73
to_language=["es"],
74
text_type=TextType.HTML,
75
profanity_action=ProfanityAction.MARKED,
76
profanity_marker="Asterisk"
77
)
78
79
# Translation with alignment and sentence information
80
detailed_response = client.translate(
81
body=["Hello world. How are you today?"],
82
to_language=["es"],
83
include_alignment=True,
84
include_sentence_length=True
85
)
86
87
translation = detailed_response[0].translations[0]
88
print(f"Alignment: {translation.alignment.proj}")
89
print(f"Source sentences: {translation.sent_len.src_sent_len}")
90
print(f"Target sentences: {translation.sent_len.trans_sent_len}")
91
92
# Custom model translation
93
custom_response = client.translate(
94
body=["Technical documentation text"],
95
to_language=["ja"],
96
from_language="en",
97
category="your-custom-model-id",
98
allow_fallback=False
99
)
100
```
101
102
## Input Types
103
104
### Text Input Models
105
106
```python { .api }
107
class InputTextItem:
108
text: str # Text content to translate
109
```
110
111
### Text Content Types
112
113
```python { .api }
114
class TextType(str, Enum):
115
PLAIN = "Plain" # Plain text content (default)
116
HTML = "Html" # HTML markup content
117
```
118
119
### Profanity Handling
120
121
```python { .api }
122
class ProfanityAction(str, Enum):
123
NO_ACTION = "NoAction" # Leave profanity unchanged (default)
124
MARKED = "Marked" # Mark profanity with specified marker
125
DELETED = "Deleted" # Remove profanity entirely
126
127
class ProfanityMarker(str, Enum):
128
ASTERISK = "Asterisk" # Replace with asterisks (default)
129
TAG = "Tag" # Wrap with XML tags
130
```
131
132
## Response Types
133
134
### Translation Results
135
136
```python { .api }
137
class TranslatedTextItem:
138
translations: List[TranslationText] # Translation results per target language
139
detected_language: Optional[DetectedLanguage] # Auto-detected source language
140
source_text: Optional[SourceText] # Original text in default script
141
```
142
143
### Individual Translation
144
145
```python { .api }
146
class TranslationText:
147
text: str # Translated text
148
to: str # Target language code
149
alignment: Optional[TranslatedTextAlignment] # Word alignment data
150
sent_len: Optional[SentenceBoundaries] # Sentence length information
151
transliteration: Optional[dict] # Script conversion result
152
```
153
154
### Language Detection
155
156
```python { .api }
157
class DetectedLanguage:
158
language: str # Detected language code
159
score: float # Confidence score (0.0 to 1.0)
160
```
161
162
### Text Alignment Analysis
163
164
```python { .api }
165
class TranslatedTextAlignment:
166
proj: str # Alignment projection string
167
# Format: [[SourceStart:SourceEnd–TargetStart:TargetEnd] ...]
168
```
169
170
### Sentence Boundary Information
171
172
```python { .api }
173
class SentenceBoundaries:
174
src_sent_len: List[int] # Source sentence lengths
175
trans_sent_len: List[int] # Translated sentence lengths
176
```
177
178
### Source Text Information
179
180
```python { .api }
181
class SourceText:
182
text: str # Input text in default script of source language
183
```