Survey123 Tricks of the Trade: Introducing Multilingual Surveys

7306
18
01-23-2019 02:35 PM
IsmaelChivite
Esri Frequent Contributor
7 18 7,306

[Last updated December 12, 2020]

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. Multilingual surveys are authored in Survey123 Connect, but once published, they are work in both the Survey123 web and field apps. This article describes how you can create multilingual surveys.

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 ISO code 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 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 in your form.  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 ISO 639-1 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)
animalscatgatoγάταcat_es.pngcat_gr.png
animalsbirdpájaroγάταbir_es.pngbir_gr.png

 

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:

 

form_titleform_idinstance_namedefault_language
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:

 

https://survey123.arcgis.com/share/{itemID}?lang=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

 

 

18 Comments
ReneAubut
Occasional Contributor

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

IsmaelChivite
Esri Frequent 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.

ReneAubut
Occasional Contributor

Thanks Ismael, that workaround will work for me

BrianKingery2
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?

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

BrianKingery2
New Contributor

This worked perfectly, thanks!

AustenPepper
New Contributor III

Hi,

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.

Jim-Moore
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!

Jim

BeckyColwell-Ongenae
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!

~Becky

Ming
by
New Contributor III

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="https://payment.com?name=', ${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:

https://survey123.arcgis.com/share/584023cea7284f96a8b498b8abbe59b8

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?

Thanks!

 

IsmaelChivite
Esri Frequent Contributor

@Ming 

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.

 

IsmaelChivite
Esri Frequent Contributor

@BeckyColwell-Ongenae 

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

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

Ming
by
New Contributor III

@IsmaelChivite 

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="https://payment.com?name=abc&amp;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="https://payment.com?name=abc&amp;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.

IsmaelChivite
Esri Frequent 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:

https://survey123beta.arcgis.com/share/584023cea7284f96a8b498b8abbe59b8?version=latest

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!

Ming
by
New Contributor III

Hi @IsmaelChivite  

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

RobertAnderson3
New Contributor III

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.

RobertAnderson3_0-1614699835319.png

 

DezsoLovicsek
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?

Capture.JPG

DanBihari
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".

DanBihari_0-1621360353351.png

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.

DanBihari_1-1621360492230.png

Is this even possible?

Any assistance would be greatly appreciated.

Thank you.