Skip to content

Commit 356b43e

Browse files
haoxiuwenhaoxiuwen
authored
Merge pull request #1380 from haoxiuwen/doc-v2
Add Translation APIs
2 parents 1ddefee + fcabfa3 commit 356b43e

File tree

5 files changed

+333
-0
lines changed

5 files changed

+333
-0
lines changed

‎docs/.vuepress/sidebar/document.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,14 @@ const documentSidebar = [
390390
{ text: '单向删除会话', link: 'conversation_delete.html' },
391391
{ text: '单向删除漫游消息', link: 'message_delete.html' },
392392
{ text: '修改消息', link: 'message_modify.html' },
393+
{
394+
text: '消息翻译',
395+
children: [
396+
{ text: '翻译消息内容', link: 'message_translation_text.html' },
397+
{ text: '获取翻译语言列表', link: 'message_translation_language_list.html' },
398+
{ text: '检测文本的源语言', link: 'message_translation_detect.html' },
399+
],
400+
},
393401
{ text: '获取离线消息数据', link: 'message_offline.html' },
394402
{ text: '导入消息', link: 'message_import.html' }
395403
]

‎docs/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1949,6 +1949,9 @@ projects:
19491949
- icon: /sdk/windows.svg
19501950
text: Windows
19511951
link: /document/windows/message_translation.html#设置自动翻译
1952+
- icon: /sdk/rest.svg
1953+
text: REST
1954+
link: /document/server-side/message_translation_text.html
19521955
- text: 按需翻译
19531956
desc: 接收方在收到文本消息后，将消息内容翻译为目标语言。
19541957
sdks:

‎docs/document/server-side/message_translation_detect.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# 检测文本的源语言
2+
3+
## 功能说明
4+
5+
- 检测要翻译的文本的源语言。
6+
- 该接口与 [翻译消息内容](message_translation_text.html) 接口的翻译共享翻译配额。
7+
- 若要使用该接口，你需要 **联系环信商务开通翻译服务**。
8+
9+
**调用频率上限**：100 次/秒/App Key
10+
11+
## 前提条件
12+
13+
要调用环信即时通讯 RESTful API，请确保满足以下要求：
14+
15+
- 已在环信即时通讯控制台 [开通配置环信即时通讯 IM 服务](enable_and_configure_IM.html)。
16+
- 了解环信 IM RESTful API 的调用频率限制，详见 [接口频率限制](limitationapi.html)。
17+
18+
## 认证方式
19+
20+
环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 `Authorization` 字段：
21+
22+
`Authorization: Bearer YourAppToken`
23+
24+
为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式，详见 [使用 App Token 鉴权](easemob_app_token.html)。
25+
26+
## HTTP 请求
27+
28+
```http
29+
POST https://{host}/{org_name}/{app_name}/translate/detect
30+
```
31+
32+
### 路径参数
33+
34+
| 参数 | 类型 | 是否必需 | 描述 |
35+
| :--------- | :----- | :------- | :--------------- |
36+
| `host` | String | 是 | 环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
37+
| `org_name` | String | 是 | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
38+
| `app_name` | String | 是 | 你在环信即时通讯云控制台创建应用时填入的应用名称。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
39+
40+
### 请求 header
41+
42+
| 参数 | 类型 | 是否必需 | 描述 |
43+
| :-------------- | :----- | :------- | --------------------------------- |
44+
| `Content-Type` | String | 是 | 内容类型。请填 `application/json`。 |
45+
| `Authorization` | String | 是 | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
46+
47+
### 请求 body
48+
49+
| 参数 | 类型 | 是否必需 | 描述 |
50+
| :-------------- | :----- | :------- | --------------------------------- |
51+
| `text` | String | 是 | 需要检测语言的文本。 |
52+
53+
## HTTP 响应
54+
55+
### 响应 body
56+
57+
如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体的 `data` 中包含以下字段：
58+
59+
| 参数 | 类型 | 描述 |
60+
| :-------------- | :----- | :------- | --------------------------------- |
61+
| `language` | String | 检测出的文本的目标语言。 |
62+
| `score` | Int | 检测出的语言与实际相符的可能性。 |
63+
| `isTranslationSupported` | String | 是否支持翻译该类语言的文本：<br/> - `true`：支持 <br/> - `false`：不支持 |
64+
65+
## 示例
66+
67+
### 请求示例
68+
69+
```shell
70+
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
71+
curl -i -X POST "https://XXXX/XXXX/XXXX/translate/detect" \
72+
-H 'Content-Type: application/json' \
73+
-H "Authorization: Bearer <YourAppToken>" \
74+
-d '{
75+
"text": "你好"
76+
}'
77+
```
78+
79+
### 响应示例
80+
81+
```json
82+
{
83+
"language": "zh-Hans",
84+
"score": 0.98,
85+
"isTranslationSupported": true
86+
}
87+
```
88+
89+
## 错误码
90+
91+
如果返回的 HTTP 状态码非 `200`，表示请求失败，可能提示以下错误码：
92+
93+
| HTTP 状态码 | 错误提示 | 可能原因 | 处理建议 |
94+
|:---------|:----------------------|:--------|:----------|
95+
| 400 | An input text is missing or invalid | 请求中的 `text` 参数未传入或传入的内容无效。 | 请求中的 `text` 参数必传，且需要传入有效字符。 |
96+
| 400 | The input text is too long | 请求中的 `text` 参数传入的内容太长。 | 请求中的 `text` 参数最多可传入 10,000 个字符。|
97+
| 400 | The request has reached the maximum limit | 调用频率超过限制 | 请联系商务提升频率限制或降低调用频率。 |
98+
| 400 | InternalTranslateFailedException | Microsoft Azure 翻译服务出错。 | |
99+
| 503 | service not open | 翻译服务未开通。 | 翻译服务为增值服务。调用接口前，请先联系商务开通翻译服务。 |

‎docs/document/server-side/message_translation_language_list.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# 获取翻译语言列表
2+
3+
## 功能说明
4+
5+
- 该接口获取翻译语言列表。
6+
- 翻译功能由 Microsoft Azure Translation API 提供，开始前请确保你了解该功能支持的目标语言。详见 [翻译语言支持](https://learn.microsoft.com/zh-cn/azure/ai-services/translator/language-support)。
7+
- 若要使用该接口，你需要 **联系环信商务开通翻译服务**。
8+
9+
**调用频率上限**：100 次/秒/App Key
10+
11+
## 前提条件
12+
13+
要调用环信即时通讯 RESTful API，请确保满足以下要求：
14+
15+
- 已在环信即时通讯控制台 [开通配置环信即时通讯 IM 服务](enable_and_configure_IM.html)。
16+
- 了解环信 IM RESTful API 的调用频率限制，详见 [接口频率限制](limitationapi.html)。
17+
18+
## 认证方式
19+
20+
环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 `Authorization` 字段：
21+
22+
`Authorization: Bearer YourAppToken`
23+
24+
为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式，详见 [使用 App Token 鉴权](easemob_app_token.html)。
25+
26+
## HTTP 请求
27+
28+
```http
29+
POST https://{host}/{org_name}/{app_name}/translate/support/language
30+
```
31+
32+
### 路径参数
33+
34+
| 参数 | 类型 | 是否必需 | 描述 |
35+
| :--------- | :----- | :------- | :--------------- |
36+
| `host` | String | 是 | 环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
37+
| `org_name` | String | 是 | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
38+
| `app_name` | String | 是 | 你在环信即时通讯云控制台创建应用时填入的应用名称。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
39+
40+
### 请求 header
41+
42+
| 参数 | 类型 | 是否必需 | 描述 |
43+
| :-------------- | :----- | :------- | --------------------------------- |
44+
| `Authorization` | String | 是 | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
45+
46+
## HTTP 响应
47+
48+
### 响应 body
49+
50+
如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段：
51+
52+
| 参数 | 类型 | 描述 |
53+
| :-------------- | :----- | :------- | --------------------------------- |
54+
| `code` | String | 语言代码。 |
55+
| `name` | String | 语言名称。 |
56+
| `nativeName` | String | 语言在其起源地的名称，例如，英语在英国称为 `English`。|
57+
58+
如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [响应状态码](error.html) 了解可能的原因。
59+
60+
## 示例
61+
62+
### 请求示例
63+
64+
```shell
65+
curl -i -X POST "https://XXXX/XXXX/XXXX/translate/support/language" \
66+
-H "Authorization: Bearer <YourAppToken>"
67+
```
68+
69+
### 响应示例
70+
71+
以下分别是英语、希腊语和马尔代夫语的示例：
72+
73+
```json
74+
[
75+
{
76+
"code": "en",
77+
"name": "English",
78+
"nativeName": "English"
79+
},
80+
{
81+
"code": "el",
82+
"name": "Greek",
83+
"nativeName": "Ελληνικά"
84+
},
85+
{
86+
"code": "dv",
87+
"name": "Divehi",
88+
"nativeName": "ދިވެހިބަސް"
89+
}
90+
]
91+
```
92+
93+
## 错误码
94+
95+
如果返回的 HTTP 状态码非 `200`，表示请求失败，可能提示以下错误码：
96+
97+
| HTTP 状态码 | 错误提示 | 可能原因 | 处理建议 |
98+
|:---------|:----------------------|:--------|:----------|
99+
| 400 | The request has reached the maximum limit | 调用频率超过限制 | 请联系商务提升频率限制或降低调用频率。 |
100+
| 400 | InternalTranslateFailedException | Microsoft Azure 翻译服务出错。 | |
101+
| 503 | service not open | 翻译服务未开通。 | 翻译服务为增值服务。调用接口前，请先联系商务开通翻译服务。 |

‎docs/document/server-side/message_translation_text.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# 翻译消息内容
2+
3+
## 功能说明
4+
5+
### 功能开通
6+
7+
文本消息翻译为增值服务，开通后才能使用。如需开通，开联系环信商务。
8+
9+
### 功能描述
10+
11+
- 翻译文本消息的内容。
12+
- 该接口只支持文本消息。
13+
14+
**调用频率上限**：100 次/秒/App Key
15+
16+
## 前提条件
17+
18+
要调用环信即时通讯 RESTful API，请确保满足以下要求：
19+
20+
- 已在环信即时通讯控制台 [开通配置环信即时通讯 IM 服务](enable_and_configure_IM.html)。
21+
- 了解环信 IM RESTful API 的调用频率限制，详见 [接口频率限制](limitationapi.html)。
22+
23+
## 认证方式
24+
25+
环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 `Authorization` 字段：
26+
27+
`Authorization: Bearer YourAppToken`
28+
29+
为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式，详见 [使用 App Token 鉴权](easemob_app_token.html)。
30+
31+
## HTTP 请求
32+
33+
```http
34+
POST https://{host}/{org_name}/{app_name}/translate
35+
```
36+
37+
### 路径参数
38+
39+
| 参数 | 类型 | 是否必需 | 描述 |
40+
| :--------- | :----- | :------- | :--------------- |
41+
| `host` | String | 是 | 环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
42+
| `org_name` | String | 是 | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
43+
| `app_name` | String | 是 | 你在环信即时通讯云控制台创建应用时填入的应用名称。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 |
44+
45+
### 请求 header
46+
47+
| 参数 | 类型 | 是否必需 | 描述 |
48+
| :-------------- | :----- | :------- | --------------------------------- |
49+
| `Content-Type` | String | 是 | 内容类型。请填 `application/json`。 |
50+
| `Authorization` | String | 是 | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
51+
52+
### 请求 body
53+
54+
| 参数 | 类型 | 是否必需 | 描述 |
55+
| :-------------- | :----- | :------- | --------------------------------- |
56+
| `from` | String | 否 | 源语言的语言代码。你可以调用 [获取翻译语言列表](message_translation_language_list.html) 获取源语言的语言代码。 |
57+
| `text` | String | 是 | 需要翻译的文本。最多可传入 10,000 个字符。计算方法：需要翻译的文本字符数 x 目标翻译语言的数量，即 `text` 中的字符数 x `to` 中的目标语言数量。例如，你对 `text` 传入了 500 个字符，`to` 中传入了 4 种目标语言代码，则 `text` 中的文本字符数算作 2000。|
58+
| `to` | Array | 是 | 目标语言的代码。你可以调用 [获取翻译语言列表](message_translation_language_list.html) 获取源语言的语言代码。 |
59+
60+
## HTTP 响应
61+
62+
### 响应 body
63+
64+
如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段：
65+
66+
| 参数 | 类型 | 描述 |
67+
| :-------------- | :----- | :------- | --------------------------------- |
68+
| `translations` | JSON Array | 翻译结果。 |
69+
| - `text` | String | 翻译后的文本。 |
70+
| - `to` | String | 翻译目标语言的代码。|
71+
72+
如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [响应状态码](error.html) 了解可能的原因。
73+
74+
## 示例
75+
76+
### 请求示例
77+
78+
```shell
79+
curl -i -X POST "https://XXXX/XXXX/XXXX/translate" \
80+
-H 'Content-Type: application/json' \
81+
-H "Authorization: Bearer <YourAppToken>" \
82+
-d '{
83+
"from": "zh-Hans",
84+
"text": "学习",
85+
"to": [
86+
"en",
87+
"zh-Hant"
88+
]
89+
}'
90+
```
91+
92+
### 响应示例
93+
94+
```json
95+
[
96+
{
97+
"translations": [
98+
{
99+
"text": "study",
100+
"to": "en"
101+
}
102+
{
103+
"text": "學習",
104+
"to": "zh-Hant"
105+
}
106+
]
107+
}
108+
]
109+
```
110+
111+
## 错误码
112+
113+
如果返回的 HTTP 状态码非 `200`，表示请求失败，可能提示以下错误码：
114+
115+
| HTTP 状态码 | 错误提示 | 可能原因 | 处理建议 |
116+
|:---------|:----------------------|:--------|:----------|
117+
| 400 | An input text is missing or invalid | 请求中的 `text` 参数未传入或传入的内容无效。 | 请求中的 `text` 参数必传，且需要传入有效字符。 |
118+
| 400 | The target language is missing or invalid | 请求中的 `to` 参数未传入或传入的内容无效。 | 请求中的 `to` 参数必传且传入有效内容。 |
119+
| 400 | The input text is too long | 请求中的 `text` 参数传入的内容太长。 | 请求中的 `text` 参数最多可传入 10,000 个字符。计算方法：需要翻译的文本字符数 x 目标翻译语言的数量，即 `text` 中的字符数 x `to` 中的目标语言数量。例如，你对 `text` 传入了 500 个字符，`to` 中传入了 4 中目标语言代码，则 `text` 中的文本字符数算作 2000。 |
120+
| 400 | The request has reached the maximum limit | 调用频率超过限制 | 请联系商务提升频率限制或降低调用频率。 |
121+
| 400 | InternalTranslateFailedException | Microsoft Azure 翻译服务出错。 | |
122+
| 503 | service not open | 翻译服务未开通。 | 翻译服务为增值服务。调用接口前，请先联系商务开通翻译服务。 |

0 commit comments

Comments
 (0)