---
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. `KoboToolbox` forms 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 this 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 demonstrate this 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/).