Skip to contents

Get and set the languages used in KoboToolbox data

Source: R/kobo_lang.R
kobo_lang.Rd

  • kobo_lang(): Get the languages available in a KoboToolbox survey form.

  • kobo_lang_get(): Get the current language of a dataset returned by kobo_data().

  • kobo_lang_set(): Change the language labels of a dataset without re-downloading.

Usage

kobo_lang(x)

# S3 method for class 'kobo_asset'
kobo_lang(x)

# S3 method for class 'character'
kobo_lang(x)

# Default S3 method
kobo_lang(x)

kobo_lang_get(data, asset)

# S3 method for class 'data.frame'
kobo_lang_get(data, asset)

# S3 method for class 'dm'
kobo_lang_get(data, asset)

# Default S3 method
kobo_lang_get(data, asset)

kobo_lang_set(data, asset, lang)

# S3 method for class 'data.frame'
kobo_lang_set(data, asset, lang)

# S3 method for class 'dm'
kobo_lang_set(data, asset, lang)

# Default S3 method
kobo_lang_set(data, asset, lang)

Arguments

x

For kobo_lang(): the unique identifier of a specific asset (character) or a kobo_asset object.

data

For kobo_lang_get() and kobo_lang_set(): a data.frame or dm object returned by kobo_data().

asset

For kobo_lang_get() and kobo_lang_set(): a kobo_asset object or the unique identifier of a specific asset (character).

lang

For kobo_lang_set(): character, the target language. Use kobo_lang(asset) to see available languages.

Value

  • kobo_lang(): A character vector of the languages of the deployed form version, or of the draft for a form never deployed. Returns "Labels" when no language is set.

  • kobo_lang_get(): A character string of the current language, or NA if it cannot be determined.

  • kobo_lang_set(): The data with updated labels in the new language.

Details

KoboToolbox forms can have multiple language translations. Normally, switching languages requires calling kobo_data() again with a different lang parameter, which re-downloads all data from the server.

kobo_lang_set() applies labels from a different language to existing data instantly, using the cached form metadata. This is useful when you need to work with data in multiple languages or export data with different label sets.

kobo_lang_get() inspects the current variable labels in the data and matches them against the form to determine which language is currently applied.

With data from kobo_data(colnames_label = TRUE), kobo_lang_set() renames the columns to the labels of the new language. It finds the question of each column through the kobo_name attribute, so two questions with the same label keep their own columns.

With data from kobo_data(select_multiple_label = TRUE), kobo_lang_set() also translates the answers of select_multiple questions. It splits each answer into the labels of its question, and stops with an error when an answer splits in more than one way. This happens with "Red Blue" when "Red", "Blue" and "Red Blue" are all choices, or with a code kept without a label, such as Red from an older form version, when "Red" is also the label of another choice. Download the data in the new language with kobo_data(lang = ) in that case.

Examples

if (FALSE) { # \dontrun{
# Setup
asset <- kobo_asset("aYuTZn9vegi3Z49MXwKjep")

# List available languages
kobo_lang(asset)

# Fetch data in English
df <- kobo_data(asset, lang = "English (en)")

# Check current language (using asset object or uid)
kobo_lang_get(df, asset)
kobo_lang_get(df, "aYuTZn9vegi3Z49MXwKjep")

# Switch to French instantly (no API call)
df_fr <- kobo_lang_set(df, asset, lang = "Francais (fr)")
kobo_lang_get(df_fr, asset)

# Works with dm objects (nested forms) too
dm_data <- kobo_data(complex_asset)
dm_fr <- kobo_lang_set(dm_data, complex_asset, lang = "French")
} # }