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.4K

[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



Occasional Contributor

In "select_one_listA or Other" type question, is there a way to have "Other" and "Specify other" translated ?

Esri Notable Contributor

Hi Rene Aubut‌  Unfortunately not. If you want to translate Other then follow these steps:

1- Do not use 'or other' in the Type column. Simply use select_one yourlist

2- In the choices worksheet, add a 'other' choice to yourlist and use the language columns to translate

3- In the Survey worksheet add a new 'other' question and use a relevant expression to show it only when appropriate. For example:  selected(${mylistquestion},'other'). Use the language columns to translate teh question as well.

The 'or other' trick is only a shortcut for English.

Occasional Contributor

Thanks Ismael, that workaround will work for me

New Contributor

I have a survey that I have built in connect where I have included Spanish translation. Everything works except one thing. When I switch to Spanish, the image does not load on the web interface. I have insured the the image name is in the right case on the xlsx form and in the media folder, ie jointlogo.jpg. I have tried 4 combinations of .jpg, .JPG, .png, and .PNG with no luck.

Any thoughts?

Esri Esteemed Contributor

Hi Brian,

As images (such as the one you have) can include text, image columns also support language specifications (just as the label, hint, etc).  Add a column with media::image::Español (es) and provide it the image file (or a translated version thereof).

New Contributor

This worked perfectly, thanks!

New Contributor III


Is there a definitive list of languages that Survey123 does support? The help topic page notes that not all ISO 639-1 languages on the Wikipedia list are supported in Survey123 but it doesn't say which ones it does support. Having a clear list would help me on those rare occasions I do need to develop a survey with multiple languages. 

Is there any way to implement a language not on the list? Also, are there plans to implement ISO 639-2 languages? I'm interested in deploying a survey in Tok Pidgin (normally spelling bleeps out) for my staff in PNG but currently there seems to be no support available for this language.

Esri Regular Contributor

Hi @AustenPepper 

When talking about supported languages, there's a distinction between the languages that the Survey123 UI supports (Connect, field app, and web app) and the languages that your survey's XLSForm can accept.

As @IsmaelChivite mentions in this post, the language code is used to determine the app's UI language; when selecting a language, the app's interface (menus, options, etc.) will also switch to that language, if it's supported by Connect, field app, and web app - see the list of supported languages here.

The XLSForm specification references this document as the list of languages supported in XLSForm, which appears to include three-character subtags. So for Tok P**in, you can use ::Tok P**in (tpi) as the suffix for your column headers (labels, hints, etc. as configured in your XLSForm) to translate the content in your survey form.

Note that Tok P**in (tpi) is not a supported language for Survey123's UI, so while your translations will appear in the survey form when this language is selected, the app’s UI will not change (the app will remain in the default language).

Also note that for the language name, you can actually use any string you like, so long as all columns containing this language use the same notation. For example, label::Spanish (es) would work the same as label::Español (es) - the only difference would be how the language name is displayed in the drop-down language selector.

Hope this helps, good luck with your multi-language surveys!


New Contributor III

How would I go about capturing/collecting what language each survey was taken in? We are collecting contact info of people seeking to get the Covid-19 vaccine when it becomes available to them.  If they take the survey in Hindi/Spanish/English/etc. we want to reach out in the same language when their time to get scheduled arrives. 

I envision a hidden text field that uses the pulldata function in the calculation field of the survey tab.  After that I'm lost as to how to request the data I'm looking for. Any help would be appreciated. All solution ideas are welcomed.

Thanks! Great feature!


Occasional Contributor

Hi @IsmaelChivite,

I use Survey123 Connect as designer and publish as Survey123 web app, for note prompt submitted, I try to add a link with parameters  to redirect to another website. As you suggested above, I added "note" as type, "generated_note_prompt_submitted" as name, "Click to Pay" as label, and "concat('<a href="', ${name},'&price=',${price},'"','target="_blank">Go to Pay</a>')" as calculation, but doesn't work, so any suggestion? 

If I use web designer then can add link as prompt message but can't pass input value as URL parameter.

Here is the survey link:

Or is it possible that I change the note name from "generated_note_prompt_submitted" to general one like "pay_link" then show the link in form, after click the link to payment website, redirect back, then click submit button to finish the survey?



Esri Notable Contributor


If you would like to create a Thank You screen with a custom link, try the following:

* Add a calculate question and use the calculation column to generate your HTML with the link. Optionally, you can set the esriFieldType column to null so this value does not get persisted in the feature layer.

* Reference the value you calculated above in the label of your generated_note_prompt_submitted note.

The trick to populate custom HTML in the Thank You screen is to pass it as the label of generated_note_prompt_submitted, rather than as its calculation expression.


Esri Notable Contributor


How would I go about capturing/collecting what language each survey was taken in?

Use pulldata("@property", 'language')

Occasional Contributor


Thank you very much for your response. I tried but the problem is it shows as text of html code instead of a link. With developer tool of browser, I noticed that it shows as this:

<div id="screenContent" class="ql-editor"> <span class="or-output" data-value=" /generated_note_test/pay_link ">&lt;a href=";price=123" target="_blank"&gt;Go to Pay&lt;/a&gt;</span></div>

So basically the Survey123 web app automatically changes < to &lt; and > to &gt,. If manually change above screenContent to 

<div id="screenContent" class="ql-editor"> <span class="or-output" data-value=" /generated_note_test/pay_link "><a href=";price=123" target="_blank">Go to Pay</a></span></div>

Then it shows well as a link.

I tried many other ways like to change calculate question to hidden text question, or use html encoding, etc., none of them works and all show as html text but not link.

So further help will be appreciated!

I am using Survey123 Connect V3.11.123.

Esri Notable Contributor

Hi @Ming   You are correct. This is an oversight in our side. The trick will not work in 3.11. We looked at your case and made a fix for our next release, which should be live before the end of February 2021. You can see the Beta version at work with your survey here:

I suggest you work on your survey changes with Connect 3.11 and then add beta and ?version=latest as shown in the URL above to test your work with 3.12.

To avoid confusion in this forum between released and beta builds, I suggest you post comments touching on 3.12 in our Survey123 Early Adopter Community forum.

I hope this addresses your issue. Otherwise, please let us know through the Early Adopter. Thanks a lot!

Occasional Contributor

Hi @IsmaelChivite  

Thanks again for your help. I got it and case is closed. All the best!

MVP Regular Contributor

Hi @IsmaelChivite 

Have there been any comments regarding the default_language parameter not persisting when looking at a web form?

I'm creating a Survey using 3.12 (it was in 3.11 but I've updated since and been playing around with a trial survey in 3.12)  and I have the default language set to "French(fr)" and it recognizes this for my labels, however it does not for the surround (Next, Back, Page 1 of 4, Submit), meaning these buttons are not in French on launch.

I even changed my operating system settings to French but it appears it did not change anything.

This becomes a problem because I'm incorporating the Survey into Experience Builder using the Survey123 widget so I cannot use the custom URL, in addition the menu for language change does not display properly (it gets cut off) which is why I'm trying to have a single language French survey as opposed to multi-lingual.



New Contributor III

Is there a way to set bilingual text to show when the survey is closed and not accepting new responses? (i.e. the text set on the Survey123 website shown in the attached screenshot)

Perhaps there is a "generated_note" parameter that can be added to the xlsform to set this text in a manner similar to the "thank you" page displayed after the survey is submitted?


New Contributor III

Hey @IsmaelChivite,

This is a very helpful article.  Is there a way to translate the survey details?  I was able to translate the actual survey (questions and answers) but am struggling to translate the "details".


When I switch to French and make changes, those changes appear in English.  I'd like the details to be in French when French is selected as the language of choice but I have no idea where I can add this translation.


Is this even possible?

Any assistance would be greatly appreciated.

Thank you.

New Contributor III

I have a survey available in English and Spanish, with English the default language.  Is there a way to make the Translation option at the top of the form more obvious?  Currently there is the World Icon and English next to it -- it would be more helpful to have "Español" listed to show there is a second language available.

Is it a setting I could add to my XLS form?



Regular Contributor

When I look at my bilingual survey in the dashboard, the questions are in Spanish and the answers are in English. Is there a setting on the web dashboard that allows me to switch or set the language?

New Contributor

Is there a way to create a bilingual survey in the Survey 123 website as I am using MacBook and am not be able to download Survey 123 Connect. 

Regular Contributor

This is a follow up to my earlier post about the survey dashboard showing questions in Spanish instead of English. After working with tech support, we determined that I needed to use English (en) in the column, default_language, in the settings tab of Connect. Previously, I had only used en

default language.JPG



Regular Contributor

If you ever see something like this:

multiple language list.JPG

for my survey, it meant that I had accidentally deleted the space between the language and the open parentheses. Instead of hint::Español (es), I used hint::Español(es). This (see image) occurred if I made this change to any column heading that had a language and a language code.

New Contributor II

Hello  @IsmaelChivite I copied the suggested calculation for retrieving the language used in the survey:

Then when I go to update the survey I get error "missing calculation"


Any suggestions?

Esri Notable Contributor

@DeclanDevine  You need to put pulldata("@property","language") into the calculation column.
I just tested this with 3.16 and it works as expected. Make sure your survey has multiple languages defined. 




New Contributor II

Thanks so much @IsmaelChivite.! Actually putting the calculation in the calculation field worked...who would have thought ;).

Thank you!





New Contributor II

@IsmaelChivite This is a great article - thanks for posting it! I am utilizing an external choice list in my form and have a Spanish column included in the external table. I am managing the choice list with a search() appearance.

However, I am not able to get the form to utilize the Spanish column of my external table. My current setup will return the choices from Column D of my external table. If I put "Area_Spanish" in the label column (column C in the first image) of my choices tab in the Survey123 Excel workbook, I get the Spanish options.


Is it possible to have Survey123 automatically switch between the English options and the Spanish options in the same way it does with an internal list?

Survey Tab: 

typenamelabelhintguidance_hintappearancerequiredrequired_messagereadonlydefaultcalculationconstraintconstraint_messagerelevantchoice_filterrepeat_countmedia::audiomedia::imagebind::typebind::esri:fieldTypebind::esri:fieldLengthbind::esri:fieldAliasbody::esri:stylebind::esri:parametersparametersbody::acceptbody::esri:visiblebody::esri:inputMasklabel::Español(es)hint::language (xx)guidance_hint::language (xx)required_message::language (xx)body::accuracyThresholdbind::esri:warningbind::esri:warning_messagebind::saveIncomplete
select_one areahwp_areaPlease Select an Area  minimal search('Project_Area_Super_Level_List','matches' ,'Building',${hwp_building},'Level',${hwp_level})yes                     Área       


Choices Tab: 

Area           Area_Spanish


External Table: 

I deleted name and contact information from my table, leaving those cells blank.

EAGEAG 5Level 1EAG 5 A Front of House       Eag 5A - Frente a la Casa
EAGEAG 5Level 1EAG 5 A Back of House       Eag 5A - Trasera de la Casa
EAGEAG 5Level 1EAG 5 B Front of House       Eag 5A - Generador Patio




Alex Steiner

Regular Contributor

Thanks, this blog was great.  Just published my first bilingual survey from connect.