CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-tencentcloud-sdk-python-tmt

Tencent Cloud Machine Translation (TMT) SDK for Python providing comprehensive text, file, image, and speech translation capabilities

Overview
Eval results
Files

file-translation.mddocs/

File Translation

Document translation supporting multiple formats (PDF, DOCX, PPTX, XLSX, TXT, XML, HTML, Markdown, Properties) with asynchronous processing and progress tracking. File translation operates as a two-step process: submit translation task and retrieve results.

Capabilities

Submit File Translation Task

Submits a document for translation and returns a task ID for tracking. Supports both URL-based and direct file upload methods.

def FileTranslate(self, request: models.FileTranslateRequest) -> models.FileTranslateResponse:
    """
    Submit a file translation task.
    
    Args:
        request: FileTranslateRequest with file and translation parameters
        
    Returns:
        FileTranslateResponse with task ID for tracking
        
    Raises:
        TencentCloudSDKException: For various error conditions
    """

Usage Example:

from tencentcloud.common import credential
from tencentcloud.tmt.v20180321.tmt_client import TmtClient
from tencentcloud.tmt.v20180321 import models

# Initialize client
cred = credential.Credential("SecretId", "SecretKey")
client = TmtClient(cred, "ap-beijing")

# Submit file translation via URL
req = models.FileTranslateRequest()
req.Source = "en"
req.Target = "zh"
req.DocumentType = "pdf"
req.SourceType = 0  # URL source
req.Url = "https://example.com/document.pdf"
req.BasicDocumentType = "pdf"

# Submit translation task
resp = client.FileTranslate(req)
task_id = resp.Data.TaskId
print(f"Translation task submitted: {task_id}")

Retrieve File Translation Results

Retrieves translation results using the task ID. Supports both callback and polling methods for result retrieval.

def GetFileTranslate(self, request: models.GetFileTranslateRequest) -> models.GetFileTranslateResponse:
    """
    Retrieve file translation results by task ID.
    
    Args:
        request: GetFileTranslateRequest with task ID
        
    Returns:
        GetFileTranslateResponse with translation status and results
        
    Raises:
        TencentCloudSDKException: For various error conditions
    """

Usage Example:

import time

# Check translation status and retrieve results
def wait_for_translation(client, task_id, max_wait_time=300):
    """Wait for translation completion and return results."""
    start_time = time.time()
    
    while time.time() - start_time < max_wait_time:
        req = models.GetFileTranslateRequest()
        req.TaskId = task_id
        
        resp = client.GetFileTranslate(req)
        
        if resp.Data.Status == "success":
            return resp.Data.Url  # URL to download translated file
        elif resp.Data.Status == "failed":
            raise Exception(f"Translation failed: {resp.Data.ErrorMsg}")
        elif resp.Data.Status in ["waiting", "processing"]:
            print(f"Translation status: {resp.Data.Status}")
            time.sleep(5)  # Wait 5 seconds before next check
        
    raise Exception("Translation timeout")

# Use the function
try:
    result_url = wait_for_translation(client, task_id)
    print(f"Translation completed: {result_url}")
except Exception as e:
    print(f"Translation error: {e}")

Request/Response Models

FileTranslateRequest

class FileTranslateRequest:
    """
    Request parameters for file translation.
    
    Attributes:
        Source (str): Source language code
        Target (str): Target language code
        DocumentType (str): File format (pdf, docx, pptx, xlsx, txt, xml, html, markdown, properties)
        SourceType (int): Data source type (0: URL, 1: file data)
        Url (str): File URL when SourceType=0
        Data (str): Base64 encoded file data when SourceType=1
        BasicDocumentType (str): Basic document type for processing
        CallbackUrl (str): Optional callback URL for result notification
        ProjectId (int): Project ID (default: 0)
    """

FileTranslateResponse

class FileTranslateResponse:
    """
    Response from file translation submission.
    
    Attributes:
        Data (Task): File translation task data containing TaskId
        RequestId (str): Unique request identifier
    """

GetFileTranslateRequest

class GetFileTranslateRequest:
    """
    Request parameters for retrieving file translation results.
    
    Attributes:
        TaskId (str): Task ID returned from FileTranslate
    """

GetFileTranslateResponse

class GetFileTranslateResponse:
    """
    Response from file translation result retrieval.
    
    Attributes:
        Data (GetFileTranslateData): Translation result data
        RequestId (str): Unique request identifier
    """

Task

class Task:
    """
    File translation task data.
    
    Attributes:
        TaskId (str): Task ID for tracking translation status
    """

GetFileTranslateData

class GetFileTranslateData:
    """
    File translation result data.
    
    Attributes:
        TaskId (str): Task ID for this translation
        Status (str): Task status (init, wait, success, fail)
        FileData (str): Translation result data when successful
        Message (str): Status message
        Progress (int): Translation progress (0-100)
        UsedAmount (int): Characters consumed for billing
    """

Supported File Formats

Document Formats

  • PDF: Portable Document Format files
  • DOCX: Microsoft Word documents
  • PPTX: Microsoft PowerPoint presentations
  • XLSX: Microsoft Excel spreadsheets

Text Formats

  • TXT: Plain text files
  • XML: Structured XML documents
  • HTML: Web page documents
  • Markdown: Markdown formatted text
  • Properties: Java properties files

Translation Workflow

Asynchronous Processing

File translation uses an asynchronous workflow:

  1. Submit Task: Call FileTranslate() to submit file for translation
  2. Get Task ID: Receive task ID for tracking progress
  3. Poll/Wait: Use GetFileTranslate() to check status
  4. Retrieve Results: Download translated file when status is "success"

Result Retrieval Methods

Polling Method:

  • Periodically call GetFileTranslate() with task ID
  • Check status field: "waiting", "processing", "success", "failed"
  • Retrieve result URL when status is "success"

Callback Method:

  • Provide CallbackUrl in FileTranslateRequest
  • Receive POST notification when translation completes
  • Parse callback data for result URL

Data Retention

Translation task data is retained for 7 days after completion. Ensure you download results within this timeframe as data will be permanently deleted afterward.

Error Handling

Common error scenarios for file translation:

  • FAILEDOPERATION_SUBMISSIONLIMITREACHED: Daily task limit exceeded
  • FAILEDOPERATION_TOOMANYWAITPROCESS: Too many pending tasks
  • UNSUPPORTEDOPERATION: Unsupported file format or language pair
  • INVALIDPARAMETER: Invalid file URL or parameters
  • FAILEDOPERATION_DOWNLOADERR: File download error

Example error handling:

try:
    resp = client.FileTranslate(req)
    task_id = resp.Data.TaskId
except TencentCloudSDKException as e:
    if e.code == "FAILEDOPERATION_SUBMISSIONLIMITREACHED":
        print("Daily translation limit reached")
    elif e.code == "FAILEDOPERATION_TOOMANYWAITPROCESS":
        print("Too many pending tasks, try again later")
    else:
        print(f"Translation error: {e.code} - {e.message}")

Install with Tessl CLI

npx tessl i tessl/pypi-tencentcloud-sdk-python-tmt

docs

file-translation.md

image-translation.md

index.md

speech-translation.md

text-translation.md

tile.json