---
title: "Multi-Language Survey Forms"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Multi-Language Survey Forms}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  message = FALSE,
  warning = FALSE,
  echo = TRUE,
  comment = "#>")
```

During data collection, it is often necessary to translate survey forms into multiple languages. Forms in `KoboToolbox` allow users to easily add translations, which can be used to label questions and choice values in either single or multiple-choice questions.

`robotoolbox` provides the capability to access these labels used in the form. The [`labelled`](https://cran.r-project.org/package=labelled/vignettes/intro_labelled.html) package is used to encode variable labels for question labels and value labels for choice labels.

The following example showcases a project in `KoboToolbox` that employs three languages: English, French, and Arabic.

- **Survey questions**

| type             | name      | label::English (en)  | label::Francais (fr)               | label::Arabic (ar) |
|:-----------------|:----------|:---------------------|:-----------------------------------|:-------------------|
| start            | start     |                      |                                    |                    |
| end              | end       |                      |                                    |                    |
| today            | today     |                      |                                    |                    |
| text             | full_name | What is your name?   | Quel est votre nom ?               | ما اسمك ؟          |
| select_one yesno | pet_yesno | Do you have any pet? | Avez-vous un animal de compagnie ? | هل تمتلك حيوانا أليفا ؟ |


- **Choices**

| list_name | name | label::English (en) | label::Francais (fr) | label::Arabic (ar) |
|:----------|-----:|:--------------------|:---------------------|:-------------------|
| yesno     |    1 | Yes                 | Oui                  | نعم                |
| yesno     |    0 | No                  | Non                  | لا                 |


### Loading the survey

To load this survey from your `KoboToolbox` server into your `R` session, you can use its unique identifier (`uid = aYuTZn9vegi3Z49MXwKjep`) with the `kobo_asset` function.

```{r, eval = FALSE}
library(robotoolbox)
library(dplyr)
uid <- "aYuTZn9vegi3Z49MXwKjep"
asset <- kobo_asset(uid)
asset
```

```{r, echo = FALSE}
library(robotoolbox)
library(dplyr)
asset <- asset_ml
asset
```

### Listing available languages

The `kobo_lang` function can be used to list all available languages for this survey.

```{r list_lang}
kobo_lang(asset)
```

### Reading data in each language

The `kobo_data` function allows you to specify the language to be loaded using the `lang` parameter. You can check the spelling of each language using `kobo_lang`.

```{r, eval = FALSE}
df_en <- kobo_data(asset, lang = "English (en)")
df_fr <- kobo_data(asset, lang = "Francais (fr)")
df_ar <- kobo_data(asset, lang = "Arabic (ar)")
glimpse(df_en)
```

```{r, echo = FALSE}
df_en <- data_ml_en
df_fr <- data_ml_fr
df_ar <- data_ml_ar
glimpse(df_en)
```

If the `lang` parameter is not specified, the default language is used. In this project, the default language is `English (en)`.

```{r, eval = FALSE}
df_default <- kobo_data(asset)
all.equal(df_default, df_en)
```

```{r, echo = FALSE}
df_default <- data_ml_default
all.equal(df_default, df_en)
```

### Accessing variable labels

You can use the `var_label` function from the `labelled` package to access question labels.

```{r var_label1}
library(labelled)
var_label(df_en$full_name)
var_label(df_fr$full_name)
var_label(df_ar$full_name)
```


```{r var_label2}
var_label(df_en$pet_yesno)
var_label(df_fr$pet_yesno)
var_label(df_ar$pet_yesno)
```

### Variable labels as column names

The `kobo_data` function has an additional parameter `colnames_label` (default is `FALSE`) that allows you to use the variable labels as column names. While it is not recommended for data analysis, it can be useful when exporting your `data.frame` to a spreadsheet. This feature is already available in the traditional `KoboToolbox` export tools.

```{r colvar1, eval = FALSE, echo = TRUE}
kobo_data(asset_ml,
          colnames_label = TRUE, lang = "Arabic (ar)") |>
names()
```

```{r colvar2, eval = TRUE, echo = FALSE}
names(data_ml_vlabel)
```

### Accessing labels from `select_one` question type

The `to_factor` function can convert the values of single-choice questions into labels.

```{r val_label}
table(to_factor(df_en$pet_yesno))
table(to_factor(df_fr$pet_yesno))
table(to_factor(df_ar$pet_yesno))
```

If you prefer character values over factors, you can use `to_character` to have the labels in character format instead of factors.

```{r val_label_character}
count(df_ar, pet_yesno_ar = to_character(pet_yesno))
```

### Accessing labels for `select_multiple` question type

Labels from `select_multiple` is also accessible using the `kobo_data` parameter `select_multiple_label`. Let's show this new feature, with the following form:

- **Survey questions**

| type                | name      | label::English (en)         |
|---------------------|-----------|-----------------------------|
| start               | start     |                             |
| end                 | end       |                             |
| today               | today     |                             |
| text                | full_name | What is your name?          |
| select_multiple pet | pet_type  | What type of pet do you own |


- **Choices**

| list_name | name | label::English (en) |
|-----------|------|---------------------|
| pet       | 1    | rabbit              |
| pet       | 2    | chicken             |
| pet       | 3    | dog                 |
| pet       | 4    | cat                 |
| pet       | 5    | turtle              |


```{r, echo = TRUE, eval = FALSE}
data_sm <- kobo_data(uid)
glimpse(data_sm)
```

```{r, echo = FALSE, eval = TRUE}
library(dplyr)
library(robotoolbox)
glimpse(data_sm)
```

The column `pet_type` contains values (`1` to `5`) instead of the labels (`dog`, `cat`, etc.). Now, let's set the new `select_multiple_label` to `TRUE` and read again the data.

```{r, echo = TRUE, eval = FALSE}
data_sm_label <- kobo_data(uid,
                           select_multiple_label = TRUE)
glimpse(data_sm_label)
```

```{r, echo = FALSE, eval = TRUE}
glimpse(data_sm_label)
```

We can now see the `labels` (`dog`, `cat`, etc.) instead of the values (`1` to `5`) for the `pet_type` question.

Variable labels have been improved for all the dummy variables related to the `select_multiple` question (whether or not you use the `select_multiple_label` parameter).

```{r, eval = TRUE}
var_label(data_sm_label)
```

Most of these functions come from the `labelled` package, you can explore this package further through its [documentation](https://larmarange.github.io/labelled/).