文本翻译-V2

一、服务概述

云上曲率翻译开放平台是面向游戏行业广大开发者提供开放服务的平台（推荐您使用最新版本接口V3）

二、服务申请

翻译 API 采用全流程自助申请的模式。

点击云上曲率官网(https://www.ilivedata.com/) 右上方的“免费试用”按钮，按照提示信息“注册账号-创建企业”后，在控制台选择“实时文本翻译”服务并创建应用，即可获得pid和服务密钥。

如需开通更多服务，可在管理控制台-总览页面开通其他服务。

三、接入方式

请求 URL: 从云上曲率“控制台-服务配置”中获取
HTTP 请求Header: Accept: application/json;charset=UTF-8
请求方法: GET/POST
请求参数

参数	必需	描述
q	必需	需要翻译的原文文本。此文本为不超过1024个字符的UTF-8编码字符串
source	必需	原文本的语种（下称“源语言”）。此参数需设置为语言支持中列举的ISO 639-1标准的语言代码之一。API会自动进行语种检测，在句子中仅包含无意义文本时，会参考该值，可以设定该参数值为auto。关于不同翻译模式，请参见下文textType参数的介绍。
target	必需	翻译的目标语言，同上需设置为语言支持文档中列举的ISO 639-1标准的语言代码之一。
appId	必需	项目或应用的唯一标识符。需要在官网注册账号及公司后，在控制台创建实时翻译项目，即可得到项目的appId。
profanity	可选	敏感内容过滤功能。可选值为censor和off，分别对应开启和关闭，如未指定则默认为off。此功能仅通过关键词屏蔽，如果您的业务对于文本审核有更高要求或需要定制内容，建议接入云上曲率的多语言文本审核服务。
textType	可选	翻译模式参数。可选值为chat和mail，如未指定则默认为chat。两种参数分别用于不同的翻译场景：使用chat参数时，API会默认对原文进行语种识别并按识别结果进行翻译。在常见的实时翻译场景，如文字聊天、直播弹幕等，推荐使用chat模式。在如软件内的系统信件、官方公告等原文标准、且有换行格式的长文本场景中，则推荐使用mail模式。该模式能够保证\t、\n和空格符在译文中保持不变。此模式下默认不会识别原文语种，而是会严格按照指定的源语言参数进行翻译。如果在mail模式下需要进行语种识别，请指定源语言参数source为auto。
timeStamp	必需	请求的UTC时间戳。需要把时间戳按W3C标准格式化，例如: 2010-01-31T23:59:59Z.（格式标准详见：http://www.w3.org/TR/xmlschema-2/#dateTime）

请求签名:

当用户请求Translation API时，可以使用appId和secretKey对请求做签名，当API收到带签名信息的请求之后，将使用相同的算法验证签名，如果发现签名不一致，API将会返回401给用户。如果API验证签名一致，且appId对应的用户有权限操作请求的资源，则请求成功，否则API返回401。

通过 HTTP 请求 Header 发送签名

方法: 在请求中加入名为 Authorization 的 Header，值为签名值。如下：

	Authorization: *****

签名计算方法
1. 构造规范化的请求字符串（Canonicalized Query String）:
  
  a. 由于签名要求唯一性，包括顺序，所以需要按照参数名称排序。
  
  b. 依据以下规则对参数名和参数值做URL编码。有关更多信息，请参见 RFC 3986
```
* A-Z, a-z, 0-9, 减号 ( - ), 下划线 ( _ ), 点号 ( . ), 和 波浪号 ( ~ ) 不编码。
* 其它字符编码成 %XY 的格式，其中 XY 是字符对应 ASCII 码的 16 进制表示，字母要大写。比如英文的双引号（”）对应的编码为 %22
* 对于扩展的 UTF-8 字符，编码成 %XY%ZA… 的格式
* 英文空格（ ）要编码成 %20，而不是加号（+）。
```
  c. 使用等号字符 (=) 将参数名称与参数值分离，即使参数值为空也如此。使用与字符 (&) 分隔参数和值对。将参数及其值连接组成一个长字符串，中间没有空格。允许参数值内有空格，但空格必须经 URL 编码成 %20。在连接后的字符串中，句点字符 (.) 未进行转义。RFC 3986 将句点字符视为非保留字符，因此未对其进行 URL 编码。
  
  d. 一般支持URL编码的库（比如 Java 中的 java.net.URLEncoder）都是按照 “application/x-www-form-urlencoded”的 MIME 类型的规则进行编码的。实现时可以直接使用这类方式进行编码，把编码后的字符串中加号（+）替换成 %20、星号（*）替换成 %2A、%7E 替换回波浪号（~），即可得到上述规则描述的编码字符串。
2. 构造被签名字符串 StringToSign ("\n" 代表ASCII里的换行符):
```
    StringToSign = HTTPMethod + "\n" + 
                   HostHeaderInLowercase + "\n" + 
                   HTTPRequestURI + "\n" + 
                   CanonicalizedQueryString <从上一步得到>
```
  HTTPRequestURI是请求URI的绝对路径，不包含请求串。如果HTTPRequestURI为空，也要保留一个正斜杠 ( / )
3. 使用 HMAC-SHA256 协议创建基于哈希的消息身份验证代码 (HMAC)，然后计算签名。
  
  StringToSign作为签名字符串，secretKey作为秘钥，SHA256作为哈希算法
  
  有关 HMAC 的更多信息，请参阅 HMAC：用于消息身份验证的哈希密钥（https://tools.ietf.org/html/rfc2104）。
4. 将上一步的结果转换为BASE64串
5. 将BASE64串放入HTTP请求Header的Authorization
签名示例

下面是appId & secretKey的示例
```
 appId=***
 secrectKey=***
```

下面是示例请求

 https://translate.ilivedata.com/api/v2/translate?source=en&target=zh-CN&q=hello%20world&appId=***&timeStamp=2015-09-23T04%3A55%3A07Z

生成StringToSign

 POST\n
 translate.ilivedata.com\n
 /api/v2/translate\n
 appId=***&q=hello%20world&source=en&target=zh-CN&timeStamp=2015-09-23T04%3A55%3A07Z

HMAC计算得到的签名
```
 ******
```

HTTP响应:

Content-Type: application/json;charset=UTF-8

结果为JSON格式，请参考以下示例。

HTTP响应

示例1: GET https://translate.ilivedata.com/api/v2/translate?source=en&target=zh-TW&q=hello%20world

 JSON response
     HTTPSTATUS: 200
     {
        "errorCode": 0,
        "translation": {
           "source": "en",
           "target": "zh-TW",
           "sourceText": "hello world",
           "targetText": "妳好世界"
        }
     }

示例2: GET https://translate.ilivedata.com/api/v2/translate

 JSON response
     HTTPSTATUS: 404
     {
         "errorCode":1006,
         "errorMessage":"Not Found"
     }

示例3: GET https://translate.ilivedata.com/api/v2/translate?target=zh-TW&q=hello%20world!

 JSON response
     HTTPSTATUS: 400
     {
         "errorCode":2000,
         "errorMessage":"Missing Parameter"
     }

文本翻译-V2

一、 服务概述

二、 服务申请

三、 接入方式

一、服务概述

二、服务申请

三、接入方式