Select to view content in your preferred language

Survey123 Tricks of the Trade: Introducing Multilingual Surveys

01-23-2019 02:35 PM
Esri Notable Contributor
7 28 17.8K

[Updated December 12, 2020]

[Updated November 14, 2023. Added link to Survey123 web designer video]


Using multilingual surveys you can present questions to your audience in the language they are most comfortable with, and analyze all survey results in a single data set. This article describes how to author multilingual surveys in Survey123 Connect.  If you are interested in translating your surveys using the Survey123 web designer, check this video instead. 

Before we start


Before we get into how to translate your survey, I want to discuss how the Survey123 apps handle multiple languages. First of all, we need to draw clear distinction between the Survey123 app, and your own survey.

  • The Survey123 web and field apps are translated by Esri.  When you open the Survey123 app in your device, it will automatically switch to the language used by your operating system. The list of supported languages includes: Arabic, Bosnian, Catalan, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hebrew, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian, Polish, Portuguese (Brazil), Portuguese (Portugal), Romanian, Russian, Serbian, Simplified Chinese, Slovak, Slovenian, Spanish, Swedish, Thai, Traditional Chinese (Taiwan), Traditional Chinese (Hong Kong), Turkish, Ukrainian, and Vietnamese. It is not possible for you to add additional languages. If your operating system uses a language not present in the list above, the app will default to English.
  • Translating the survey that gets loaded into the Survey123 app, is your responsibility. It is up to you to decide how many languages you want to support. When your survey is loaded in the app, Survey123 will automatically try to find a translation of your survey that matches the current language used in your operating system. The match is performed comparing the language BCP 47code of your operating system with that of languages available in your survey (more about this later).  If a match is not found, the survey will use the default language as defined in your XLSForm. 

Be aware that the list of supported languages for your survey translations is much larger than the limited number of languages we support in the Survey123 apps. For example, while the Survey123 apps are not available in Euskara (a language spoken in Spain and some parts of France), you can still translate your survey to Euskara.  The Survey123 app will be shown in Spanish or French, but your survey could be presented in Euskara. The same applies to other languages such as Welsh and Swahili.

The Survey123 apps (web and field), will also let the user manually change the language of the survey. For example, if you translated your survey into 3 languages, the list will show these three languages. 

The language chosen for your survey will display question labels, notes and choices in the corresponding language. Additionally, numbers and date values entered by the user within your survey will be formatted accordingly as well.

Adding language codes to XLSForm columns


There are many aspects of your smart form that can be translated. Question labels, hints, constraint and required messages, choice labels and even media (banners, diagrams...).  The technique used to add translations to all these is the same.  The following table demonstrates how to translate question labels:


typenamelabel::English (en)label::Greek (el)
select_one animalanimalWhat is your favorite animal?Ποιο είναι το αγαπημένο σας ζώο


Note that each language column is qualified with a descriptive string for the language it represents, followed by its corresponding BCP 47 code  enclosed in parenthesis. For example, the XLSForm column with the question label in Spanish is label::Español (es), and the label for English is label::English (en).

The hint, constraint_message and required_message XLSForm columns are translated following the same pattern. For example:


typename       label::English (en)hint::English (en)
select_one ananimalWhat is your favorite animal?Choose an animal from the list


And the same applies to the choices worksheet in your XLSForm:


list_namenamelabel::Español (es)label::Ελληνικά (el)media::image::Español (es)media::image::Ελληνικά (el)


Once you start adding new languages into your survey design, you will want to add translations for every question and choice label at the very least. If you use optional columns such as hint, contraint_message or  required_message, make sure you translate them into every language. The same goes for the media, audio and image columns!


Translating the survey header (title), footer and other elements


There are a number of survey elements that are translated by adding note questions with specific names into your survey design. The next screenshot provides the details:


006 Survey123 Multilingual Support.png


The survey header (title) is used in both the Survey123 field and web app. The remaining elements (submit button text, footer and thank you screen), are only relevant in the Survey123 web app.


How to launch a survey using a specific language


When a multilingual survey is loaded into the field or web app, Survey123 will automatically try to match the language of your survey with the language of your operating system.  This is why using the ISO codes is important.  For example, if the language set in your operating system is (es), Survey123 will look for the (es) translation in your survey and if found, switch the language accordingly.  If no match is found, then the default_language will be used.  The default language is defined in the settings XLSForm worksheet:


Multiple Languages  English (en)


If using the Survey123 web app, you can also always force a survey to be displayed in a specific language (independently from the language of the operating system).  This is done through the lang URL parameter. For example:{itemID}?locale=es


Of course, end users always have a choice to manually change he language if they choose to. Both the Survey123 field and web apps will provide a menu listing all the available languages.

How to tell in what language the user completed the survey


Use pulldata("@property", 'language') to retrieve the language used by the user to complete the survey. You can use this expression in a calculate question for example.

typename       calculation
calculatesurveylangpulldata("@property", 'language')


Other resources