or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-googletrans

An unofficial Google Translate API for Python providing free text translation and language detection capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/googletrans@4.0.x

To install, run

npx @tessl/cli install tessl/pypi-googletrans@4.0.0

index.mddocs/

Googletrans

An unofficial Google Translate API for Python that provides free and unlimited text translation capabilities without requiring API keys. Built on top of httpx with HTTP/2 support, it reverse-engineers Google's web translation service to enable automatic language detection, text translation between 450+ languages, batch operations, and includes a command-line interface.

Package Information

  • Package Name: googletrans
  • Package Type: pypi
  • Language: Python 3.8+
  • Installation: pip install googletrans

Core Imports

from googletrans import Translator

For language constants:

from googletrans import LANGUAGES, LANGCODES

For full typing support:

import typing
from typing import Dict, List, Tuple, Union, Optional
from httpx import Timeout
from httpx._types import ProxyTypes

Basic Usage

import asyncio
from googletrans import Translator

async def basic_translation():
    async with Translator() as translator:
        # Simple translation (auto-detect source language)
        result = await translator.translate('안녕하세요.')
        print(f"{result.text} (detected: {result.src})")
        # Output: Hello. (detected: ko)
        
        # Specify source and destination languages
        result = await translator.translate('Hello world', src='en', dest='es')
        print(result.text)  # Hola mundo
        
        # Language detection
        detected = await translator.detect('Bonjour le monde')
        print(f"Language: {detected.lang}, Confidence: {detected.confidence}")
        # Language: fr, Confidence: 0.85

asyncio.run(basic_translation())

Architecture

The googletrans library follows an async-first design:

  • Translator Class: Main client that manages HTTP connections and translation requests
  • Async Context Manager: Handles HTTP client lifecycle with proper resource cleanup
  • Token System: Automatically manages Google Translate authorization tokens
  • Batch Processing: Concurrent translation of multiple texts with configurable limits
  • HTTP/2 Support: Uses modern HTTP protocol for improved performance
  • Proxy Support: Full proxy configuration via httpx integration

Capabilities

Translation

Translate text between any of 450+ supported languages with automatic source language detection, batch processing capabilities, and comprehensive metadata including pronunciation guides.

async def translate(
    self,
    text: typing.Union[str, typing.List[str]],
    dest: str = "en",
    src: str = "auto",
    **kwargs: typing.Any
) -> typing.Union[Translated, typing.List[Translated]]:
    """
    Translate text from source language to destination language.
    
    Args:
        text: Source text(s) to translate. Supports batch via list input.
        dest: Destination language code (e.g., 'en', 'es', 'fr')
        src: Source language code or 'auto' for detection
        **kwargs: Additional options including list_operation_max_concurrency
        
    Returns:
        Translated object or list of Translated objects for batch input
    """

Usage examples:

async with Translator() as translator:
    # Single translation
    result = await translator.translate('Hello', dest='es')
    print(result.text)  # Hola
    
    # Batch translation
    texts = ['Hello', 'Goodbye', 'Thank you']
    results = await translator.translate(texts, dest='fr')
    for result in results:
        print(f"{result.origin} -> {result.text}")
    
    # Control concurrency for large batches
    results = await translator.translate(
        large_text_list, 
        dest='de',
        list_operation_max_concurrency=5
    )

Language Detection

Detect the language of input text with confidence scores, supporting both single texts and batch processing for efficient language identification.

async def detect(
    self,
    text: typing.Union[str, typing.List[str]],
    **kwargs: typing.Any
) -> typing.Union[Detected, typing.List[Detected]]:
    """
    Detect language of input text(s).
    
    Args:
        text: Text(s) for language detection. Supports batch via list input.
        **kwargs: Additional options including list_operation_max_concurrency
        
    Returns:
        Detected object or list of Detected objects for batch input
    """

Usage examples:

async with Translator() as translator:
    # Single detection
    detected = await translator.detect('Hola mundo')
    print(f"Language: {detected.lang}, Confidence: {detected.confidence}")
    
    # Batch detection
    texts = ['Hello', 'Bonjour', 'Hola', 'Guten Tag']
    results = await translator.detect(texts)
    for i, result in enumerate(results):
        print(f"'{texts[i]}' -> {result.lang}")

Configuration

Customize translator behavior including service URLs, proxy settings, HTTP/2 support, timeout configuration, and error handling preferences.

def __init__(
    self,
    service_urls: typing.Sequence[str] = DEFAULT_CLIENT_SERVICE_URLS,
    user_agent: str = DEFAULT_USER_AGENT,
    raise_exception: bool = DEFAULT_RAISE_EXCEPTION,
    proxy: typing.Optional[ProxyTypes] = None,
    timeout: typing.Optional[Timeout] = None,
    http2: bool = True,
    list_operation_max_concurrency: int = 2
):
    """
    Initialize Translator with custom configuration.
    
    Args:
        service_urls: Google Translate URLs (randomly selected)
        user_agent: Custom User-Agent header
        raise_exception: Whether to raise exceptions on errors
        proxy: HTTP proxy configuration
        timeout: Request timeout settings  
        http2: Enable HTTP/2 support
        list_operation_max_concurrency: Max concurrent batch operations
    """

Usage examples:

from httpx import Timeout

# Custom configuration
translator = Translator(
    service_urls=['translate.google.com', 'translate.google.co.kr'],
    proxy='http://proxy.example.com:8080',
    timeout=Timeout(30.0),
    raise_exception=True,
    list_operation_max_concurrency=5
)

async with translator:
    result = await translator.translate('Hello', dest='ja')

Language Constants

Access comprehensive language code mappings for all 450+ supported languages, enabling validation and conversion between language codes and human-readable names.

# Language code to name mapping
LANGUAGES: Dict[str, str]

# Language name to code mapping  
LANGCODES: Dict[str, str]

Usage examples:

from googletrans import LANGUAGES, LANGCODES

# Check supported languages
print(LANGUAGES['ko'])  # korean
print(LANGCODES['french'])  # fr

# Validate language codes
if 'zh-cn' in LANGUAGES:
    print("Chinese (Simplified) is supported")

# List all supported languages
for code, name in LANGUAGES.items():
    print(f"{code}: {name}")

Command Line Interface

The package includes a CLI script that provides command-line access to translation functionality, though the current implementation has compatibility issues with the async API.

# Basic translation (auto-detect source)
translate "Hello world" --dest es

# Specify source and destination  
translate "Hello world" --src en --dest fr

# Language detection only
translate "Bonjour le monde" --detect

Note: The CLI script (translate) currently calls async methods synchronously, which may cause runtime errors. The script would need to be updated to properly handle the async API using asyncio.run().

Types

class Translator:
    """Main translation client with async context manager support."""
    
    def __init__(self, **config): ...
    async def translate(self, text, dest="en", src="auto", **kwargs): ...
    async def detect(self, text, **kwargs): ...
    async def __aenter__(self): ...
    async def __aexit__(self, exc_type, exc_val, exc_tb): ...

class Translated:
    """Translation result with source text, translated text, and metadata."""
    
    src: str                    # Source language code
    dest: str                   # Destination language code
    origin: str                 # Original input text
    text: str                   # Translated text
    pronunciation: str          # Pronunciation guide
    extra_data: dict | None     # Additional data (synonyms, definitions, etc.)

class Detected:
    """Language detection result with detected language and confidence."""
    
    lang: str                   # Detected language code
    confidence: float           # Detection confidence (0.0 to 1.0)

# Configuration constants  
DEFAULT_CLIENT_SERVICE_URLS: Tuple[str, ...]
DEFAULT_USER_AGENT: str
DEFAULT_RAISE_EXCEPTION: bool

# Language mapping constants
LANGUAGES: Dict[str, str]       # Language code -> name mapping
LANGCODES: Dict[str, str]       # Language name -> code mapping

Error Handling

The library handles errors gracefully with configurable exception behavior:

# Default: returns dummy data on errors
translator = Translator(raise_exception=False)  # Default
result = await translator.translate("text")  # Returns fallback on error

# Strict mode: raises exceptions
translator = Translator(raise_exception=True)
try:
    result = await translator.translate("text")
except Exception as e:
    print(f"Translation failed: {e}")

Common errors include network connectivity issues, invalid language codes, and Google service limitations. The library includes automatic token refresh and retry logic for transient failures.