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#

VariableDescriptionRequiredXDOC_API_KEYYour Xdoc API keyYes

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#

PropertyValueProviderXdoc ( https://x-doc.ai)API Base URLhttps://translation.x-doc.ai/api/open_api/v1Supportsupport@x-doc.ai

---

Core Workflow#

Document Translation Flow#

text

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

Step-by-Step:

1. Create Upload URL http

   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
   
   

2. 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

3. Submit Translation http

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

4. Poll Status (every 3-5 seconds) http

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

5. Download Translation

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

---

API Capabilities#

Document Translation#

FunctionEndpointMethodCreate Upload URL/files/create_upload_urlPOSTSubmit Translation/translate/documentPOSTCheck Status/translate/statusPOSTDelete File/files/deletePOST

Text Translation#

FunctionEndpointMethodInstant Translate/text/translatePOST

Glossary (Term Library)#

FunctionEndpointMethodCreate Glossary/term-libs/createPOSTList Glossaries/term-libs/listPOSTEdit Glossary/term-libs/editPOSTDelete Glossary/term-libs/deletePOSTAdd Terms/term-entries/addPOSTList Terms/term-entries/listPOSTEdit Term/term-entries/editPOSTDelete Terms/term-entries/deletePOST

Translation Memory#

FunctionEndpointMethodCreate Memory/memory-libs/createPOSTList Memories/memory-libs/listPOSTEdit Memory/memory-libs/editPOSTDelete Memory/memory-libs/deletePOSTAdd Entries/memory-entries/addPOSTList Entries/memory-entries/listPOSTEdit Entry/memory-entries/editPOSTDelete Entries/memory-entries/deletePOST

Utility#

FunctionEndpointMethodGet Supported Languages/languagesGET

---

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:

json

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

Using Translation Memory#

Reuse previous translations with memory libraries:

json

{
  "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#

text

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

Status Definitions#

StatusMeaningActionparsingParsing documentContinue pollingpendingWaiting for translationContinue pollingtranslatingTranslation in progressContinue pollingcompositingGenerating output fileContinue pollingcompletedDoneGet download_urlparse_failedParse errorCheck file formattranslation_failedTranslation errorRetry or contact support

---

Language Codes#

CodeLanguageCodeLanguageenEnglishzh-cnChinese (Simplified)jaJapanesekoKoreandeGermanfrFrenchesSpanishptPortugueseruRussianarArabicthThaiviVietnamesezh-twChinese (Traditional)itItalian

Use /languages endpoint for the complete list.

---

Example Scenarios#

Scenario 1: Translate a Word Document#

text

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#

text

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#

text

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:

json

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

Success#

CodeMessageDescription0successRequest completed successfully

Authentication Errors (910xx)#

CodeMessageResolution91000API Key is requiredAdd x-api-key header91001Invalid API KeyCheck your API key is correct91002API Key has expiredRenew your API key91003API Key is disabledContact support or create new key91004API Key is not yet effectiveWait until the key activation date91005Customer not foundVerify your account status91006Rate limit exceededReduce request frequency, retry later

File Translation Errors (911xx)#

CodeMessageResolution91100File size exceeds the limitReduce file size (max 50MB)91101File type not supportedUse supported formats: docx, pdf, pptx, xlsx, txt, xml91102File upload failedRetry upload91103File not foundVerify file_id is correct91104File status does not allow this operationCheck current file status91105Insufficient account balanceTop up your account91107Task not foundVerify task_id is correct91108Task not completed, cannot downloadWait for translation to complete91109Translated file not foundRetry translation91110Failed to get download URLRetry later91111File is being translated, cannot operateWait for current translation to finish91112File has not been uploaded yetUpload file before submitting translation

Glossary Errors (912xx)#

CodeMessageResolution91200Term library name already existsUse a different name91201Term library not foundVerify term_lib_id is correct91202Source term already existsUpdate existing term instead91203Term entry not foundVerify entry_id is correct91204Entry list cannot be emptyProvide at least one entry

Translation Memory Errors (913xx)#

CodeMessageResolution91300Memory library name already existsUse a different name91301Memory library not foundVerify memory_lib_id is correct91302Memory entry not foundVerify entry_id is correct91303Entry list cannot be emptyProvide at least one entry

Text Translation Errors (915xx)#

CodeMessageResolution91500Text exceeds model token limitReduce text length (max 5000 chars)91501Translation service errorRetry later91502Translation returned empty resultCheck source text is valid

---

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