Survey123 Tricks of the Trade: Automatically translate survey designs in Survey123 Connect
Note:
The Auto translate [BETA] tool in Survey123 Connect is a beta feature, and it is not intended
for use in production environments. It is recommended to try beta tools on a copy of your
survey. Please describe any bugs or enhancements for the tool in the Survey123 Early Adopter
Community (Connect & Field App Beta Feedback forum).
Translating your survey designs into languages applicable to your target audience is incredibly powerful and ensures that they can understand the questions and provide the best responses. Survey123 has supported authoring multilingual surveys for quite some time but has recently added tools to streamline that authoring process.
Before we begin
Before jumping into automatically translating survey designs in Survey123 Connect, it is very important to understand how multilingual surveys are configured in Survey123 Connect. Please review the Survey123 Tricks of the Trade: Introducing Multilingual Surveys Esri Community blog for more information and resources on configuring your survey to support multiple languages.
Connect Tools
Survey123 contains tools that assist with some of your form authoring tasks. When publishing surveys in Connect, you may have noticed the Tools button in the side panel.
If you see this button in your Connect window, fantastic! You can skip to the next section and start preparing your XLSForm for automatic translation.
If you do not see the Tools button, you will need to complete a couple additional steps to get access to the tools in Connect. To set up, follow the steps outlined in the Configure tools in Survey123 Connect documentation so you can run the Auto-translate tool.
Prepare your XLSForm for translation
The first step to preparing your XLSForm for automatic translation is to define the default_language for the survey in the settings worksheet of the XLSForm. The default_language value will serve as the `from` language or the language that contains the strings that need to be translated into other languages.
Go to the settings worksheet in the XLSForm and under the default_language column, set your language followed by the locale code. In my example here, I've defined my default_language as English (en).
With the default_language defined in the settings worksheet, now you need to update all the default translatable columns in your survey and choices worksheets (don't forget your choices worksheet!). For best results, all columns that can be translated should be updated with the language and locale code that matches your default language. This includes the following columns:
- label ➡️ label::English (en)
- hint ➡️ hint::English (en)
- guidance_hint ➡️ guidance_hint::English (en)
- required_message ➡️ required_message::English (en)
- constraint_message ➡️ constraint_message::English (en)
- media::audio ➡️ media::audio::English (en)
- media::image ➡️ media::image::English (en)
Don't forget choices:
Next, you will need to add columns for your target languages. Your XLSForm template already contains language (xx) columns that you can take advantage of for your first target language. To add target languages, add at least one column with that language defined. For example, if I want to translate my survey into Spanish and French, at minimum, I would need to add the following columns:
- label::Español (es)
- label::Français (fr)
Technically, you do not need to add target language columns for all the translatable columns, as long as you add at least one for each language. Any translated strings returned for columns that don't have a corresponding language column in the XLSForm will be appended to the end of the worksheet. If you want to control where those columns are in your XLSForm, add them in prior to running the tool.
Automatically translate your survey
After preparing your XLSForm for translation, you are ready to automatically translate your survey design into your target languages. Before running the auto translate Connect tool, you must save and close your XLSForm. Why? The tool needs to be able to edit your XLSForm with the translated strings, so if it's open on your machine, the tool will not be able to apply those edits.
With your survey opened in Connect, click the Tools button in the side panel and choose Auto translate [BETA].
The tool will run for a few seconds to a minute or so, depending on your network connectivity, the size of your survey, and the number of languages you are translating. When the tool finishes, you will see the Converting XLSForm message (because the tool has modified and saved your XLSForm) and Connect automatically refreshes your form preview.
Verify translations
When your form finishes converting, you will see the language switcher on the top of your form, which allows you to choose between your default language and the additional languages that were automatically translated.
It is necessary to thoroughly review the results of the Auto translate [BETA] tool. Machine translation is not 100% correct and will require human review and verification.
💡Tip:
Take advantage of the Survey123 Connect tools for exporting and importing translations.
You can use the Export translations tool to export the automatically translated strings and
pass them along for review to colleagues who are fluent in that language. Any necessary changes
can be made in the respective language .xlsx file. You can then use the Import translations
tool to apply those changes to your survey design.
And you're done! Your survey has been automatically translated into the defined target languages, including all the applicable columns: label, hint, required_message, and so on.