> ## Documentation Index
> Fetch the complete documentation index at: https://beaver.voc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 消息翻译

> 第三方 → Shulex 的消息翻译接口

# 消息翻译

> 第三方 → Shulex：将一段消息翻译为指定目标语言

当第三方需要翻译客户消息、客服回复或工单上下文时，可调用此接口。

## 调用地址与鉴权

在 Shulex 中创建 Custom Ticket 渠道后，从渠道配置页面复制消息翻译地址；请勿手动拼接 URL。

```http theme={null}
POST https://<host>/api_v2/intelli/custom-ticket/message-translation/{xToken}/{channelId}
Content-Type: application/json
```

| 路径字段        | 类型     | 必填 | 说明                             |
| ----------- | ------ | -- | ------------------------------ |
| `xToken`    | string | 是  | Shulex 生成的渠道访问凭证               |
| `channelId` | number | 是  | Shulex 生成的 Custom Ticket 渠道 ID |

Shulex 会校验凭证与渠道归属同一账号，且该渠道必须为 Custom Ticket 渠道。请求体不支持覆盖 `xToken`、`channelId` 或租户 ID。

## 请求格式

```json theme={null}
{
  "text": "My package is damaged. Can I get a replacement?",
  "targetLanguage": "CHINESE",
  "contentFormat": "PLAIN"
}
```

### 请求字段

| 字段               | 类型      | 必填 | 默认值    | 说明                               |
| ---------------- | ------- | -- | ------ | -------------------------------- |
| `text`           | string  | 是  | 无默认值   | 待翻译文本                            |
| `targetLanguage` | string  | 是  | 无默认值   | 目标语言；可写值见下方 `targetLanguage` 枚举表 |
| `contentFormat`  | string  | 否  | `HTML` | 内容格式；可写值见下方 `contentFormat` 枚举表  |
| `preserveMarkup` | boolean | 否  | `true` | 是否尽量保留原文中的 Markdown / HTML 标记    |

<Warning>
  `text` 和 `targetLanguage` 均不能为空。`contentFormat` 与 `preserveMarkup` 为可选字段，不传时分别按 `HTML` 和 `true` 处理。
</Warning>

### 枚举可写值

#### `targetLanguage`

| 值                     | 说明           |
| --------------------- | ------------ |
| `AUTO`                | 自动识别或按默认策略处理 |
| `ENGLISH`             | 英语           |
| `CHINESE`             | 简体中文         |
| `TRADITIONAL_CHINESE` | 繁体中文         |
| `CANTONESE`           | 粤语           |
| `JAPANESE`            | 日语           |
| `FRENCH`              | 法语           |
| `GERMAN`              | 德语           |
| `SPANISH`             | 西班牙语         |
| `ARABIC`              | 阿拉伯语         |
| `RUSSIAN`             | 俄语           |
| `PORTUGUESE`          | 葡萄牙语         |
| `ITALIAN`             | 意大利语         |
| `KOREAN`              | 韩语           |
| `DUTCH`               | 荷兰语          |
| `INDONESIAN`          | 印尼语          |
| `TURKISH`             | 土耳其语         |
| `ROMANIAN`            | 罗马尼亚语        |
| `POLISH`              | 波兰语          |
| `PHILIPPINES`         | 菲律宾语         |
| `VIETNAMESE`          | 越南语          |
| `THAI`                | 泰语           |
| `SWEDISH`             | 瑞典语          |
| `NORWEGIAN`           | 挪威语          |
| `FINNISH`             | 芬兰语          |
| `DANISH`              | 丹麦语          |
| `CZECH`               | 捷克语          |
| `SLOVAK`              | 斯洛伐克语        |
| `ESTONIAN`            | 爱沙尼亚语        |
| `LITHUANIAN`          | 立陶宛语         |
| `LATVIAN`             | 拉脱维亚语        |
| `BULGARIAN`           | 保加利亚语        |
| `HUNGARIAN`           | 匈牙利语         |
| `CROATIAN`            | 克罗地亚语        |
| `SLOVENIAN`           | 斯洛文尼亚语       |
| `BENGALI`             | 孟加拉语         |
| `HEBREW`              | 希伯来语         |
| `GREEK`               | 希腊语          |
| `HINDI`               | 印地语          |

#### `contentFormat`

| 值          | 说明          |
| ---------- | ----------- |
| `MARKDOWN` | Markdown 格式 |
| `HTML`     | HTML 格式     |
| `PLAIN`    | 纯文本格式       |

## 响应格式

成功时返回 `ResponseResult` 包装结构。`data` 中不会返回模型用量 `usages`；枚举字段统一返回字符串。

### 响应字段

| 字段                   | 类型      | 说明                                |
| -------------------- | ------- | --------------------------------- |
| `code`               | string  | 业务状态码；成功时为 `"200"`                |
| `msg`                | string  | 响应说明；成功时为 `"success"`             |
| `success`            | boolean | 是否成功                              |
| `data.content`       | string  | 翻译后的文本                            |
| `data.language`      | string  | 输出语言，例如 `ENGLISH`、`CHINESE`       |
| `data.contentFormat` | string  | 内容格式，例如 `MARKDOWN`、`HTML`、`PLAIN` |

### 成功响应

```json theme={null}
{
  "code": "200",
  "msg": "success",
  "success": true,
  "data": {
    "content": "我的包裹损坏了。可以换货吗？",
    "language": "CHINESE",
    "contentFormat": "PLAIN"
  }
}
```

<Note>
  `data.content` 为翻译后的文本。接口不会返回模型用量 `usages`，也不会在响应中回传租户 ID。
</Note>

## 常见错误

| code    | 场景                     | 处理建议                                            |
| ------- | ---------------------- | ----------------------------------------------- |
| `"400"` | `xToken` 无效            | 从渠道配置页面重新复制完整地址                                 |
| `"400"` | 渠道不存在或不属于当前账号          | 确认 `xToken` 与 `channelId` 来自同一 Custom Ticket 渠道 |
| `"400"` | `text` 为空              | 提供非空的待翻译文本                                      |
| `"400"` | `targetLanguage` 为空或非法 | 按枚举可写值传入目标语言                                    |
| `"400"` | 内容格式非法                 | 检查 `contentFormat` 是否为支持值                       |
| `"500"` | 消息翻译异常                 | 保留请求时间和渠道信息并联系 Shulex 支持排查                      |

## 接入建议

* 明确传入 `targetLanguage`，避免翻译目标不符合预期。
* 原文包含 Markdown 或 HTML 时，可按业务需要开启 `preserveMarkup`。
* 不传 `contentFormat` 时按 `HTML` 处理，适合保留邮件或富文本结构。
* 对翻译结果做必要的业务校验后再展示或发送给客户。