# Multi-Language Survey Forms

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` 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.

    library(robotoolbox)
    library(dplyr)
    uid <- "aYuTZn9vegi3Z49MXwKjep"
    asset <- kobo_asset(uid)
    asset

    #> <robotoolbox asset>  aYuTZn9vegi3Z49MXwKjep
    #>   Asset name: Multiple languages
    #>   Asset type: survey
    #>   Asset owner: dickoa
    #>   Created: 2022-01-07 10:37:19
    #>   Last modified: 2023-09-07 07:27:34
    #>   Submissions: 5

### Listing available languages

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

    kobo_lang(asset)
    #> [1] "English (en)"  "Francais (fr)" "Arabic (ar)"

### 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`.

    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)

    #> Rows: 5
    #> Columns: 16
    #> $ start                <dttm> 2022-01-07 10:39:37, 2022-01-07 10:39:47, 2022-0…
    #> $ end                  <dttm> 2022-01-07 10:39:47, 2022-01-07 10:40:02, 2022-0…
    #> $ today                <date> 2022-01-07, 2022-01-07, 2022-01-07, 2022-01-07, …
    #> $ full_name            <chr> "Jean-Pierre", "Fatim", "Ahmad", "Michelle", "إبر…
    #> $ pet_yesno            <chr+lbl> "0", "1", "0", "1", "1"
    #> $ `_id`                <int> 17735002, 17735003, 17734994, 17734995, 17735000
    #> $ uuid                 <chr> "5388c680d19148828ea45913af820f30", "5388c680…
    #> $ `__version__`        <chr> "vW6fMPTWKJmBfdSRM7jd4V", "vW6fMPTWKJmBfdSRM7jd4V…
    #> $ instanceID           <chr> "uuid:f3d0f43c-049e-4be8-ba94-a97a7e111516", "uui…
    #> $ `_xform_id_string`   <chr> "aYuTZn9vegi3Z49MXwKjep", "aYuTZn9vegi3Z49MXwKjep…
    #> $ `_uuid`              <chr> "f3d0f43c-049e-4be8-ba94-a97a7e111516", "03093de4…
    #> $ `_status`            <chr> "submitted_via_web", "submitted_via_web", "submit…
    #> $ `_submission_time`   <dttm> 2022-01-07 10:39:57, 2022-01-07 10:40:12, 2022-01…
    #> $ `_validation_status` <chr> NA, NA, NA, NA, NA
    #> $ `_submitted_by`      <lgl> NA, NA, NA, NA, NA
    #> $ `_attachments`       <list> <NULL>, <NULL>, <NULL>, <NULL>, <NULL>

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

    df_default <- kobo_data(asset)
    all.equal(df_default, df_en)

    #> [1] TRUE

### Accessing variable labels

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

    library(labelled)
    var_label(df_en$full_name)
    #> [1] "What is your name?"
    var_label(df_fr$full_name)
    #> [1] "Quel est votre nom ?"
    var_label(df_ar$full_name)
    #> [1] "ما اسمك ؟"

    var_label(df_en$pet_yesno)
    #> [1] "Do you have any pet?"
    var_label(df_fr$pet_yesno)
    #> [1] "Avez-vous un animal de compagnie ?"
    var_label(df_ar$pet_yesno)
    #> [1] "هل تمتلك حيوانا أليفا ؟"

### 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.

    kobo_data(asset_ml,
              colnames_label = TRUE, lang = "Arabic (ar)") |>
    names()

    #>  [1] "start"                   "end"
    #>  [3] "today"                   "ما اسمك ؟"
    #>  [5] "هل تمتلك حيوانا أليفا ؟" "_id"
    #>  [7] "uuid"                    "__version__"
    #>  [9] "instanceID"              "_xform_id_string"
    #> [11] "_uuid"                   "_status"
    #> [13] "_submission_time"        "_validation_status"
    #> [15] "_submitted_by"           "_attachments"

### Accessing labels from `select_one` question type

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

    table(to_factor(df_en$pet_yesno))
    #>
    #> Yes  No
    #>   3   2
    table(to_factor(df_fr$pet_yesno))
    #>
    #> Oui Non
    #>   3   2
    table(to_factor(df_ar$pet_yesno))
    #>
    #> نعم  لا
    #>   3   2

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

    count(df_ar, pet_yesno_ar = to_character(pet_yesno))
    #> # A tibble: 2 × 2
    #>   pet_yesno_ar     n
    #>   <chr>        <int>
    #> 1 لا               2
    #> 2 نعم              3

### Accessing labels for `select_multiple` question type

Labels from `select_multiple` are 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

    data_sm <- kobo_data(uid)
    glimpse(data_sm)

    #> Rows: 5
    #> Columns: 22
    #> $ start                <dttm> 2022-05-09 18:32:50, 2022-05-09 18:32:33, 2022-0…
    #> $ end                  <dttm> 2022-05-09 18:34:26, 2022-05-09 18:34:37, 2022-0…
    #> $ today                <date> 2022-05-09, 2022-05-09, 2022-05-09, 2022-05-09, …
    #> $ full_name            <chr> "Moh", "Joe", "Remus", "Romulus", "Rufus"
    #> $ pet_type             <chr> "3 4 5", NA, "5", "4", "3 4"
    #> $ pet_type_1           <int> 0, NA, 0, 0, 0
    #> $ pet_type_2           <int> 0, NA, 0, 0, 0
    #> $ pet_type_3           <int> 1, NA, 0, 0, 1
    #> $ pet_type_4           <int> 1, NA, 0, 1, 1
    #> $ pet_type_5           <int> 1, NA, 1, 0, 0
    #> $ `_id`                <int> 20939301, 20939288, 20939278, 20939265, 20939261
    #> $ instanceID           <chr> "uuid:b72a497c-8fcf-43c4-825e-6f1fe7df40ce", "uui…
    #> $ deprecatedID         <chr> "uuid:0bc30cb8-5584-45dc-9264-8c1aa14ad256", "uui…
    #> $ uuid                 <chr> "5c0d08e4deda4a7fbc9634f5e8aba62f", "5c0d08e4deda…
    #> $ `__version__`        <chr> "vjPe5qiVxTmyviYSrQE3x4", "vjPe5qiVxTmyviYSrQE3x4…
    #> $ `_xform_id_string`   <chr> "atbUaNGu5PWR2u4tNDsYaH", "atbUaNGu5PWR2u4tNDsYaH…
    #> $ `_uuid`              <chr> "b72a497c-8fcf-43c4-825e-6f1fe7df40ce", "a2e71f4e…
    #> $ `_status`            <chr> "submitted_via_web", "submitted_via_web", "submit…
    #> $ `_submission_time`   <dttm> 2022-05-09 18:33:15, 2022-05-09 18:33:01, 2022-05…
    #> $ `_validation_status` <chr> NA, NA, NA, NA, NA
    #> $ `_submitted_by`      <lgl> NA, NA, NA, NA, NA
    #> $ `_attachments`       <list> <NULL>, <NULL>, <NULL>, <NULL>, <NULL>

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.

    data_sm_label <- kobo_data(uid,
                               select_multiple_label = TRUE)
    glimpse(data_sm_label)

    #> Rows: 5
    #> Columns: 22
    #> $ start                <dttm> 2022-05-09 18:32:50, 2022-05-09 18:32:33, 2022-0…
    #> $ end                  <dttm> 2022-05-09 18:34:26, 2022-05-09 18:34:37, 2022-0…
    #> $ today                <date> 2022-05-09, 2022-05-09, 2022-05-09, 2022-05-09, …
    #> $ full_name            <chr> "Moh", "Joe", "Remus", "Romulus", "Rufus"
    #> $ pet_type             <chr> "dog cat turtle", NA, "turtle", "cat", "dog cat"
    #> $ pet_type_1           <int> 0, NA, 0, 0, 0
    #> $ pet_type_2           <int> 0, NA, 0, 0, 0
    #> $ pet_type_3           <int> 1, NA, 0, 0, 1
    #> $ pet_type_4           <int> 1, NA, 0, 1, 1
    #> $ pet_type_5           <int> 1, NA, 1, 0, 0
    #> $ `_id`                <int> 20939301, 20939288, 20939278, 20939265, 20939261
    #> $ instanceID           <chr> "uuid:b72a497c-8fcf-43c4-825e-6f1fe7df40ce", "uui…
    #> $ deprecatedID         <chr> "uuid:0bc30cb8-5584-45dc-9264-8c1aa14ad256", "uui…
    #> $ uuid                 <chr> "5c0d08e4deda4a7fbc9634f5e8aba62f", "5c0d08e4deda…
    #> $ `__version__`        <chr> "vjPe5qiVxTmyviYSrQE3x4", "vjPe5qiVxTmyviYSrQE3x4…
    #> $ `_xform_id_string`   <chr> "atbUaNGu5PWR2u4tNDsYaH", "atbUaNGu5PWR2u4tNDsYaH…
    #> $ `_uuid`              <chr> "b72a497c-8fcf-43c4-825e-6f1fe7df40ce", "a2e71f4e…
    #> $ `_status`            <chr> "submitted_via_web", "submitted_via_web", "submit…
    #> $ `_submission_time`   <dttm> 2022-05-09 18:33:15, 2022-05-09 18:33:01, 2022-05…
    #> $ `_validation_status` <chr> NA, NA, NA, NA, NA
    #> $ `_submitted_by`      <lgl> NA, NA, NA, NA, NA
    #> $ `_attachments`       <list> <NULL>, <NULL>, <NULL>, <NULL>, <NULL>

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).

    var_label(data_sm_label)
    #> $start
    #> [1] "start"
    #>
    #> $end
    #> [1] "end"
    #>
    #> $today
    #> [1] "today"
    #>
    #> $full_name
    #> [1] "What is your name?"
    #>
    #> $pet_type
    #> [1] "What type of pet do you own ?"
    #>
    #> $pet_type_1
    #> [1] "What type of pet do you own ?::rabbit"
    #>
    #> $pet_type_2
    #> [1] "What type of pet do you own ?::chicken"
    #>
    #> $pet_type_3
    #> [1] "What type of pet do you own ?::dog"
    #>
    #> $pet_type_4
    #> [1] "What type of pet do you own ?::cat"
    #>
    #> $pet_type_5
    #> [1] "What type of pet do you own ?::turtle"
    #>
    #> $`_id`
    #> [1] "_id"
    #>
    #> $instanceID
    #> [1] "instanceID"
    #>
    #> $deprecatedID
    #> [1] "deprecatedID"
    #>
    #> $uuid
    #> [1] "uuid"
    #>
    #> $`__version__`
    #> [1] "__version__"
    #>
    #> $`_xform_id_string`
    #> [1] "_xform_id_string"
    #>
    #> $`_uuid`
    #> [1] "_uuid"
    #>
    #> $`_status`
    #> [1] "_status"
    #>
    #> $`_submission_time`
    #> [1] "_submission_time"
    #>
    #> $`_validation_status`
    #> [1] "_validation_status"
    #>
    #> $`_submitted_by`
    #> [1] "_submitted_by"
    #>
    #> $`_attachments`
    #> [1] "_attachments"

Most of these functions come from the `labelled` package, you can explore this package further through its documentation.