README.Rmd

---
output:
  md_document:
    variant: gfm
html_preview: false
---

<!-- README.md is generated from README.Rmd. Please edit that file -->


# `fanyi`: Translate Words or Sentences via Online Translators



[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/fanyi?color=green)](https://cran.r-project.org/package=fanyi)
![](http://cranlogs.r-pkg.org/badges/grand-total/fanyi?color=green)
![](http://cranlogs.r-pkg.org/badges/fanyi?color=green)
![](http://cranlogs.r-pkg.org/badges/last-week/fanyi?color=green)


```{r comment="", echo=FALSE, results='asis'}
cat(packageDescription('fanyi')$Description)
```

To cite fanyi in publications use:

+ D Wang, G Chen, L Li, S Wen, Z Xie, X Luo, L Zhan, S Xu, J Li, R Wang, Q Wang<sup>\*</sup>, __G Yu__<sup>\*</sup>. [Reducing language barriers, promoting information absorption, and communication using *fanyi*](https://journals.lww.com/cmj/fulltext/2024/08200/reducing_language_barriers,_promoting_information.7.aspx). __*Chinese Medical Journal*__. 2024, 137(16):1950-1956.

## :writing_hand: Authors

Guangchuang YU

School of Basic Medical Sciences, Southern Medical University

<https://yulab-smu.top>



## :arrow_double_down: Installation

Get the released version from CRAN:

```r
install.packages("fanyi")
```

Or the development version from github:

```r
## install.packages("yulab.utils")
yulab.utils::install_zip_gh("YuLab-SMU/fanyi")
```

## :beginner: Usages

### to switch from different online translators:

You should use `set_translate_source()` to set the default translator using in `translate()`.

Alternatively, you can call specific functions to use a specific translator, (e.g., `baidu_translate()`, `bing_translate()`, `youdao_translate()`, etc.).


### to use `baidu` translate:

1. go to <https://fanyi-api.baidu.com/manage/developer> and regist as an individual developer
2. get `appid` and `key` (密钥) 
3. set  `appid` and `key`  with `source = "baidu"` using `set_translate_option()`
4. have fun with `baidu_translate()` 

### to use `bing` translate:

1. regist a free azure account
2. enable `Azure AI services | Translator` from <https://portal.azure.com/>
3. create a translation service with free tier pricing version (you need a visa/master card to complete registion and will not be charged until exceed 2 million characters monthly)
4. get your `key` and `region`
5. set `key` and `region` with `source = "bing"` using `set_translate_option()`
6. have fun with `bing_translate()`

### to use `youdao`(有道智云) translate:
1. go to <https://ai.youdao.com/> and register an account
2. click `自然语言翻译服务` and create an app from subsection `文本翻译`
3. get your `应用ID` as appid, and `应用秘钥` as key
4. set `appid` and `key` with `source = "youdao"` using `set_translate_option()`
5. have fun with `youdao_translate()`
6. (bonus) you can also create `术语表` (dictionary for the terms) as a user-defined dictionary and get the dict id to help you get precise translation in certain domain.

### to use `volcengine` (火山引擎) translate:
1. go to <https://www.volcengine.com/> and register an account
2. enable `Machine Translation` (`机器翻译`)
3. get app key 
    - click `控制台`
    - click your avatar at the upper-right corner
    - select `API访问密钥` 
    - click `新建密钥`
4. for security concerns, you are highly advised to add a sub-account (新建子用户)
5. click the subaccount name in `身份管理` - `用户`, and click `permissions` (权限)
6. in `Global permissions` (全局权限), add the following permissions:
   "TranslateFullAccess"、"I18nTranslateFullAccess"
7.  set `appid` and `key` with `source = "volcengine"` and
    have fun with `volcengine_translate()`

### to use `caiyun` (彩云小译) translate:

1.  go to <https://platform.caiyunapp.com/login> and register
2.  login with your account, create a translation app (`创建应用`)
    choose `翻译` as `接口类型`
3.  get the token, set it as the `key` with `source = "caiyun"`
    using `set_translate_option()`
4.  have fun with `caiyun_translate()`
5.  caiyun currently supports `from` = {zh(中文), en, ja(日语), auto(自动识别)}
    and `to` = {en, ja, zh}, default `from` is `auto`

### to use `tencent` (腾讯机器翻译) translate:

1.  go to <https://console.cloud.tencent.com> and register;
2.  login with your account, go to <https://console.cloud.tencent.com/tmt>
    to enable machine translation (启用机器翻译);
3.  go to <https://console.cloud.tencent.com/cam/user/userType>, create a sub-account,
    in `Permissions` (权限) - `Permissions policy` (权限策略), search and add `QcloudTMTFullAccess`;
4.  get your API keys at `API keys` (API 密钥) of the same page in step 3.
    set `SecretId` as the `appid` and `SecretKey` as `secrets` respectively with `source = "tencent"` using `set_translate_option()`
4.  have fun with `tencent_translate()`
5.  for supported languages, visit <https://cloud.tencent.com/document/product/551/15611> for more information.

### to use `chatglm` (智谱清言[ChatGLM](https://arxiv.org/abs/2210.02414)) translate:

1.  go to <https://open.bigmodel.cn> and register;
2.  login with your account, go to <https://open.bigmodel.cn/usercenter/apikeys> to get your API key;
3.  set the one-line API key as `key` (no need for setting `appid`) with `source = "chatglm"` using `set_translate_option()`
4.  have fun with `chatglm_translate()`
5.  you can also set model you prefer to use with the option `user_model` when using `set_translate_option()`,
    currently `user_model` can be set as `glm-4` (by default), `glm-4v`, `glm-3-turbo`.

### helper functions:

+ `gene_summary()` allows retrieving gene information from NCBI.
+ `translate_ggplot()` allows translating axis labels of a ggplot graph.
+ `ydict()` allows query word from youdao dictionary.

## :ideograph_advantage: Examples

```{r include=FALSE}
options(width = 80)
library(fanyi)
library(DOSE)
library(enrichplot)

```{r translate, results='asis'}
library(fanyi)

##
## run `set_translate_option()` to setup
##

text <- '我都不知道做人该怎么办，总之报纸写啥就信啥，电视演啥我就看啥。'
```

```{r eval=FALSE}
translate(text, from='zh', to='en')
```

```{r results='asis', echo=FALSE}
cat(sprintf(">%s", translate(text, from='zh', to='en')), sep="\n\n")
```

```{r eval=FALSE}
translate(text, from='zh', to='th')
```

```{r results='asis', echo=FALSE}
cat(sprintf(">%s", translate(text, from='zh', to='th')), sep="\n\n")
```

```{r eval=FALSE}
translate(text, from='zh', to='jp')
```

```{r results='asis', echo=FALSE}
cat(sprintf(">%s", translate(text, from='zh', to='jp')), sep="\n\n")
```


```{r eval=FALSE}
translate(text, from='zh', to='fra')
```

```{r results='asis', echo=FALSE}
cat(sprintf(">%s", translate(text, from='zh', to='fra')), sep="\n\n")
```

```{r ggplot-fanyi, fig.width=10, fig.height=9}
library(DOSE)
library(enrichplot)
data(geneList)
de <- names(geneList)[1:200]
x <- enrichDO(de)
p <- dotplot(x)
p2 <- translate_ggplot(p, axis='y')
p3 <- translate_ggplot(p, axis='y', to='kor')
p4 <- translate_ggplot(p, axis='y', to='ara')
aplot::plot_list(English = p, Chinese = p2, 
                Korean = p3, Arabic = p4, ncol=2)
```

```{r dict}
ydict("cell")
```

```{r message=FALSE}
symbol <- c("CCR7", "CD3E")
gene <- clusterProfiler::bitr(symbol, 
            fromType = 'SYMBOL', 
            toType = 'ENTREZID', 
            OrgDb = 'org.Hs.eg.db')

gene

res <- gene_summary(gene$ENTREZID)
names(res)
d <- data.frame(desc=res$description,
              desc2=translate(res$description))
d
```

```{r eval=FALSE}
res$summary
```

```{r message=FALSE, results='asis', echo=FALSE}
format_print <- function(x) {
  # add item label
  x2 <- paste0("[", seq_along(x), "] ", x)
  # print as quoted text
  cat(sprintf(">%s", x2), sep="\n\n")
}

format_print(res$summary)
```

```{r eval=FALSE}
translate(res$summary)
```

```{r message=FALSE, results='asis', echo=FALSE}
format_print(translate(res$summary))
```


## :book: Documents

+ [把R当成你的翻译器](https://mp.weixin.qq.com/s/caHpUOyTqToJn6tqNspIyg)
+ [fanyi支持有道智云，每年立省30万！](https://mp.weixin.qq.com/s/x829_4P7bui_zEbn3GrIyw)
+ [不仅仅是翻译的fanyi包](https://mp.weixin.qq.com/s/E2jBPKs083bKJFX3gitjNg)