# SparkChain 在线翻译 Linux SDK集成文档

# 1. 在线翻译简介

在线翻译集成了三种翻译能力，具体如下：

# 2. 兼容性说明

# 3. SDK集成包目录结构

将SDK zip包解压缩，得到如下文件：

├── Demo SparkChain的使用DEMO，DEMO中已经集成了SDK，您可以参考DEMO，集成SDK。集成前，请先测通DEMO，了解调用原理。

├── ReleaseNotes.txt SDK版本日志

├── SDK SparkChain SDK

│ └── libSparkChain.so (opens new window)

└── SparkChain 在线翻译 Linux SDK集成文档.pdf SparkChain集成指南

# 4. SDK工程配置

# 4.1 导入SDK库

将SDK/libs文件夹、头文件文件夹include存放到项目中，并在环境变量里添加库路径；

#include "../../include/sparkchain.h"
#include "../../include/sc_its.h"

# 4.2 配置权限

如果需要存储日志，SDK日志路径需要读写权限，缺少读写权限，日志将无法正常存储。

# 5. 接口流程调用图

# 6. SDK 初始化

在使用SparkChain 在线翻译功能前，需要首先开通在线翻译授权并获取已开通授权的应用信息（appId、apiKey、apiSecret）。SDK全局只需要初始化一次。 初始化时，开发者需要构建一个SparkChainConfig实例config，把相关的appid信息以及日志设置等传入config中，然后再通过SparkChain::init(config)方法把config实例设置到SDK中。SparkChainConfig 结构如下：

class SPARKCHAIN_API SparkChainConfig { 
    public:    
    	static SparkChainConfig* builder();    
    	virtual ~SparkChainConfig();    
    	//配置appid    
    	virtual SparkChainConfig* appID(const char* appid)         = 0;    
    	//配置apiKey    
    	virtual SparkChainConfig* apiKey(const char* apiKey)       = 0;    
    	//配置apiSecret    
    	virtual SparkChainConfig* apiSecret(const char* apiSecret) = 0;    
    	//配置用户自定义标识    
    	virtual SparkChainConfig* uid(const char* uid)             = 0;    
    	//配置SDK工作路径    
    	virtual SparkChainConfig* workDir(const char* workDir)     = 0;    
    	//配置日志等级    
    	virtual SparkChainConfig* logLevel(int logLevel )          = 0;    
    	//配置日志存储路径    
    	virtual SparkChainConfig* logPath(const char* logPath)     = 0; 
};

初始化参数说明：

初始化返回值：0：初始化成功，非0：初始化失败，请根据具体返回值参考错误码章节查询原因。

具体示例如下：

SparkChainConfig* config = SparkChainConfig::builder(); 
config->appID("$appId")      
    ->apiKey("$apiKey")      
    ->apiSecret("$apiSecret");//从平台获取的授权appid，apikey,apisecrety 
int ret = SparkChain::init(config);

# 7. 在线翻译初始化

在使用在线翻译功能前，需先通过其构造方法ITS()方法构建其实例，然后用该实例调用相应的方法去设置翻译参数。

在线翻译构造方法如下：

class SPARKCHAIN_API ITS {
    public: 
    	ITS();
    	ITS(TransType type);
    	ITS(string fromlanguage, string tolanguage, TransType type = ITRANS);
    
    
}

构造方法参数说明：

具体示例如下：

ITS its("cn","en",ITRANS);

# 8. 功能参数配置

SDK支持用户根据自身需求，通过构建的ITS实例访问相关方法配置功能参数。具体方法说明如下：

具体配置示例如下：

its.fromlanguage("cn");
its.tolanguage("en");

# 9. 注册结果监听回调

在线翻译运行结果通过ITSCallbacks异步返回，接口定义如下：

class SPARKCHAIN_API ITSCallbacks {
public:
    virtual void onResult(ITSResult * result, void * usrTag) = 0;
    virtual void onError(ITSError * error,void * usrTag) = 0;
};

ITSCallbacks数据结构说明：

• onResult为在线翻译结果回调方法，参数说明如下：

  参数	类型	说明
  result	ITSResult *	翻译结果实例
  usrTag	void *	用户自定义标识

• ITSResult结构说明：

  方法	返回值类型	说明
  trans_result().src()	string	翻译的源文本
  trans_result().dst()	string	翻译结果
  status()	int	数据状态： 3：once(一次性)
  sid()	string	本次交互的sid
  from()	string	源语种
  to()	string	目标语种

• onError为在线翻译错误回调，参数说明如下：

  参数	类型	说明
  error	ITSError *	错误信息结果实例
  usrTag	void*	用户自定义标识

• ITSError结构说明：

  方法	返回值类型	说明
  code()	int	错误码
  errMsg()	string	错误信息
  sid()	string	交互的Sid

具体示例如下：

class ITSCallbacksImpl:public SparkChain::ITSCallbacks {
    void onResult(ITSResult * result, void * usrTag) override {
        //解析获取的交互结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。
        string sid  = result->sid();                  //本次交互的sid
        int status  = result->status();               //数据状态。3:onece(一次性)
        string from = result->from();                 //源语种
        string to   = result->to();                   //目标语种
        string src  = result->trans_result()->src();  //源文本
        string dst  = result->trans_result()->dst();  //翻译结果     
    }

    void onError(ITSError * error,void * usrTag) override {
        string sid    = error->sid();                  //本次交互的sid
        int code      = error->code();                 //错误码
        string errMsg = error->errMsg();               //错误信息
    }
};
ITSCallbacksImpl cbs{};
its.registerCallbacks(&cbs);

# 10. 请求调用

开发者注册完监听回调后，可通过its.arun()方法开启会话。请求调用接口如下：

class SPARKCHAIN_API ITS {
public: 
    int arun(const char* txt, void* usrTag = nullptr);
}

start方法结构说明：

具体示例如下：

int ret = its.arun("今天天气很好","12345");

# 11. 语种列表

使用不同类型的翻译，其中包含的翻译语种类型并不相同，具体如下：

注意：使用其他语种前，需要确保已开通相关语种的授权！

# 11.1 讯飞翻译语种列表

# 11.2 小牛翻译语种列表

# 11.3 海外翻译语种列表

Translation between Chinese and other languages:

Translation between English and other languages：

# 12. 逆初始化

当SDK需要完整退出时，需调用逆初始化方法释放资源，示例代码如下：

SparkChain::unInit(); //SDK逆初始化

# 13. SDK API介绍

# 13.1 SparkChainConfig API

# 13.2 SparkChain API

# 13.3 ITS API

# 13.4 ITSResult API

# 13.5 ITSError API

# 13.6 TransResult API

# 14. 错误码

错误码包含SDK错误码和云端错误码。

# 14.1 SDK错误码