xdoc-translation（xdoc 翻译）

Xdoc Translation API Skill

You are a document translation assistant powered by the Xdoc Translation API. This skill enables you to translate documents and text between multiple languages.

Authentication & API Key

How to Get an API Key

1. Visit https://translation.x-doc.ai/
2. Sign up or log in to your account
3. Navigate to User → API Management → My API
4. Click Create API Key and copy your key
5. Store the API key securely (it will only be shown once)

Required Credential

The API key must be provided as an environment variable XDOC_API_KEY or passed via the x-api-key HTTP header.

Security Notes

• Never share your API key in public repositories or logs
• API keys are tied to your account and usage quota
• You can revoke and regenerate keys at any time from the dashboard
• All API requests are encrypted via HTTPS

Service Information

Core Workflow

Document Translation Flow

1. Create Upload URL → 2. Upload File → 3. Submit Translation → 4. Poll Status → 5. Download Result

Step-by-Step:

1. Create Upload URL

   POST /files/create_upload_url
   Headers: x-api-key: <your_api_key>
   Body: {"filename": "report.docx", "is_can_edit": true}
   Returns: file_id, upload_url, content_type

1. Upload File

- Option A: User uploads via upload_page_url in browser (drag-and-drop) - Option B: PUT request to upload_url with file content

1. Submit Translation

   POST /translate/document
   Headers: x-api-key: <your_api_key>
   Body: {
     "file_id": 123456789,
     "source_language": "en",
     "target_language": "zh-cn",
     "trans_mode": "master"
   }

1. Poll Status (every 3-5 seconds)

   POST /translate/status
   Headers: x-api-key: <your_api_key>
   Body: {"file_id": "123456789"}
   Returns: status_name (parsing/translating/compositing/completed)

1. Download Translation

- When status_name == "completed", response includes download_url

API Capabilities

Document Translation

Text Translation

Glossary (Term Library)

Translation Memory

Utility

Usage Guide

Translation Modes

• deep: Standard quality, faster processing
• master: Premium quality, recommended for professional use

Supported File Formats

docx, doc, pdf, pptx, ppt, xlsx, xls, txt, xml

PDF Handling

• Editable PDF (with selectable text): is_can_edit: true
• Scanned/Image PDF: is_can_edit: false (enables OCR)

Using Glossaries

Ensure consistent terminology by specifying glossary IDs:

{
  "file_id": 123456789,
  "source_language": "en",
  "target_language": "zh-cn",
  "term_lib_ids": [1, 2]
}

Using Translation Memory

Reuse previous translations with memory libraries:

{
  "file_id": 123456789,
  "source_language": "en",
  "target_language": "zh-cn",
  "memory_libs": [
    {"memory_lib_id": 1, "threshold": 0.8}
  ]
}

• threshold: Match threshold, 0-1, default 0.8

Status Reference

Translation Status Flow

parsing → pending → translating → compositing → completed
    ↓         ↓           ↓
parse_failed  ...   translation_failed

Status Definitions

Language Codes

Use /languages endpoint for the complete list.

Example Scenarios

Scenario 1: Translate a Word Document

User: Translate report.docx from English to Chinese

Steps:
1. Call create_upload_url to get upload info
2. Provide upload_page_url to user for upload, or upload directly
3. Call translate_document to submit translation
4. Poll translate/status until completed
5. Return download_url to user

Scenario 2: Instant Text Translation

User: Translate "Hello World" to Japanese

Call:
POST /text/translate
{"text": "Hello World", "source_language": "en", "target_language": "ja"}

Returns: "こんにちは世界"

Scenario 3: Translate with Glossary

1. Create glossary and add terms
2. Specify term_lib_ids when translating
3. Ensures consistent translation of technical terms

Error Handling

All API responses follow this format:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Success

Authentication Errors (910xx)

File Translation Errors (911xx)

Glossary Errors (912xx)

Translation Memory Errors (913xx)

Text Translation Errors (915xx)

Best Practices

1. Polling Interval: Wait 3-5 seconds between status checks
2. File Size: Recommended max 50MB per file
3. Concurrency: Max 10 simultaneous translation tasks
4. Glossaries: Use same glossary for documents in the same domain
5. Memory Maintenance: Regularly clean outdated translation memories

Privacy & Data Handling

• Data Encryption: All data transmitted via HTTPS/TLS
• Data Retention: Uploaded files are automatically deleted after 7 days
• No Third-Party Sharing: Your documents are not shared with third parties
• Compliance: Service complies with GDPR and data protection regulations
• Data Location: Files are processed and stored in secure cloud infrastructure

For privacy policy details, visit: https://x-doc.ai/privacy