0
# pygtrans
1

2
Google Translate library with support for both free and API key-based translation services. pygtrans provides comprehensive translation capabilities including language detection, text translation, batch processing, and text-to-speech functionality, supporting 242 source languages and 243 target languages.
3

4
## Package Information
5

6
- **Package Name**: pygtrans
7
- **Language**: Python
8
- **Installation**: `pip install pygtrans`
9
- **Version**: 0.0.1
10
- **License**: GPL-3.0
11

12
## Core Imports
13

14
```python
15
from pygtrans import Translate, ApiKeyTranslate
16
```
17

18
Common imports for response handling:
19

20
```python
21
from pygtrans import TranslateResponse, DetectResponse, LanguageResponse, Null
22
```
23

24
Access to language constants:
25

26
```python
27
from pygtrans import SOURCE_LANGUAGES, TARGET_LANGUAGES
28
```
29

30
## Basic Usage
31

32
### Free Translation Client (requires proxy)
33

34
```python
35
from pygtrans import Translate
36

37
# Configure with proxy (required for non-Chinese users)
38
client = Translate(proxies={'https': 'http://localhost:10809'})
39

40
# Language detection
41
detect_result = client.detect('Hello, world!')
42
print(detect_result.language)  # 'en'
43

44
# Single translation
45
result = client.translate('Hello, world!', target='zh-CN')
46
print(result.translatedText)  # '你好世界！'
47

48
# Batch translation
49
results = client.translate([
50
    'Good morning',
51
    'How are you?'
52
], target='zh-CN')
53
for result in results:
54
    print(result.translatedText)
55

56
# Text-to-speech
57
audio_data = client.tts('你好', target='zh-CN')
58
with open('hello.mp3', 'wb') as f:
59
    f.write(audio_data)
60
```
61

62
### API Key Client (paid service)
63

64
```python
65
from pygtrans import ApiKeyTranslate
66

67
# Configure with Google Cloud API key
68
client = ApiKeyTranslate(api_key='your-api-key-here')
69

70
# Get supported languages
71
languages = client.languages()
72
print(languages[0].language, languages[0].name)  # 'en' 'English'
73

74
# Translation with automatic source detection
75
result = client.translate('Hello, world!', target='zh-CN')
76
print(result.translatedText)  # '你好世界！'
77
print(result.detectedSourceLanguage)  # 'en'
78

79
# Batch translation
80
results = client.translate([
81
    'Good morning',
82
    'How are you?'
83
], target='zh-CN')
84
```
85

86
## Architecture
87

88
pygtrans provides two main translation approaches:
89

90
- **Free Translation (`Translate`)**: Uses Google Translate web interface, requires proxy for non-Chinese users, supports basic translation and TTS
91
- **API Key Translation (`ApiKeyTranslate`)**: Uses Google Cloud Translation API, requires valid API key, provides enterprise features and reliability
92

93
Both clients support:
94
- Single string and batch list processing
95
- Automatic language detection
96
- Custom source/target language specification
97
- Configurable timeouts and proxy settings
98
- Error handling through `Null` response objects
99

100
## Capabilities
101

102
### Command Line Interface
103

104
Provides a command-line interface for quick translation tasks via the `pygtrans` command.
105

106
```python { .api }
107
def main():
108
    """
109
    Command-line interface entry point for pygtrans.
110
    
111
    Usage: pygtrans (currently provides basic CLI functionality)
112
    """
113
```
114

115
### Free Translation Client
116

117
Complete free translation functionality using Google Translate web interface. Includes language detection, text translation, batch processing, and text-to-speech capabilities. Requires proxy configuration for users outside China.
118

119
```python { .api }
120
class Translate:
121
    def __init__(
122
        self,
123
        target: str = "zh-CN",
124
        source: str = "auto",
125
        fmt="html",
126
        user_agent: str = None,
127
        domain: str = "com",
128
        proxies: dict = None,
129
        timeout: int = None,
130
        trust_env=False
131
    ): ...
132
    
133
    def detect(self, q: str, timeout=...) -> Union[DetectResponse, Null]: ...
134
    def translate(
135
        self, 
136
        q: Union[str, List[str]], 
137
        target: str = None, 
138
        source: str = None, 
139
        fmt: str = None, 
140
        timeout=...
141
    ) -> Union[TranslateResponse, List[TranslateResponse], Null]: ...
142
    def tts(self, q: str, target: str = None, timeout=...) -> Union[bytes, Null]: ...
143
```
144

145
[Free Translation Client](./free-client.md)
146

147
### API Key Translation Client
148

149
Enterprise translation functionality using Google Cloud Translation API. Provides reliable translation services, batch processing, language enumeration, and language detection with proper API authentication.
150

151
```python { .api }
152
class ApiKeyTranslate:
153
    def __init__(
154
        self,
155
        api_key: str,
156
        target: str = "zh-CN",
157
        source: str = None,
158
        fmt: str = "html",
159
        model: str = "nmt",
160
        proxies: dict = None,
161
        timeout=None,
162
        trust_env=False
163
    ): ...
164
    
165
    def languages(
166
        self, 
167
        target: str = None, 
168
        model: str = None, 
169
        timeout=...
170
    ) -> Union[List[LanguageResponse], Null]: ...
171
    def detect(
172
        self, 
173
        q: Union[str, List[str]], 
174
        timeout=...
175
    ) -> Union[DetectResponse, List[DetectResponse], Null]: ...
176
    def translate(
177
        self,
178
        q: Union[str, List[str]],
179
        target: str = None,
180
        source: str = None,
181
        fmt: str = None,
182
        model: str = None,
183
        timeout=...
184
    ) -> Union[TranslateResponse, List[TranslateResponse], Null]: ...
185
```
186

187
[API Key Translation Client](./api-client.md)
188

189
### Response Objects
190

191
Data structures for handling translation results, language detection outcomes, and error responses. These objects provide structured access to translation data and metadata.
192

193
```python { .api }
194
class TranslateResponse:
195
    def __init__(
196
        self, 
197
        translatedText: str, 
198
        detectedSourceLanguage: str = None, 
199
        model: str = None
200
    ): ...
201

202
class DetectResponse:
203
    def __init__(
204
        self, 
205
        language: str, 
206
        isReliable: bool = True, 
207
        confidence: float = 1.0
208
    ): ...
209

210
class LanguageResponse:
211
    def __init__(self, language: str, name: str = None): ...
212

213
class Null:
214
    def __init__(self, response: requests.Response): ...
215
```
216

217
[Response Objects](./responses.md)
218

219
### Language Support
220

221
Comprehensive language support with 242 source languages and 243 target languages. Includes predefined dictionaries for language code mapping and validation.
222

223
```python { .api }
224
SOURCE_LANGUAGES: dict[str, str] = {
225
    "auto": "检测语言",
226
    "en": "英语",
227
    "zh-CN": "中文",
228
    # ... 239 more languages
229
}
230

231
TARGET_LANGUAGES: dict[str, str] = {
232
    "en": "英语", 
233
    "zh-CN": "中文（简体）",
234
    "zh-TW": "中文（繁体）",
235
    # ... 240 more languages
236
}
237
```
238

239
[Language Support](./languages.md)
240

241
## Types
242

243
```python { .api }
244
from typing import Union, List, Dict
245
import requests
246

247
# Union types for method returns
248
TranslateResult = Union[TranslateResponse, List[TranslateResponse], Null]
249
DetectResult = Union[DetectResponse, List[DetectResponse], Null]
250
LanguageResult = Union[List[LanguageResponse], Null]
251
TTSResult = Union[bytes, Null]
252

253
# Input types
254
TextInput = Union[str, List[str]]
255
ProxyConfig = Dict[str, str]  # e.g., {'https': 'http://localhost:10809'}
256
```