Manage multiple languages

Including one or multiple sets of translations for surveys allows both data collectors and respondents to understand survey questions. The translation steps listed in this topic are specifically about the languages supported by the form.

To learn more about the behavior of each of the apps of Survey123 in relation to language settings, see Supported languages.

Translate survey questions

The process for including translations for survey questions in ArcGIS Survey123 is as follows:

1. Add a column to the survey worksheet and name it label:: followed by the name and code used to identify the language, with the code in parentheses, for example, label::Español (es).

   For a list of language codes that XLSForm accepts and will display in your form, see the list of BCP 47 codes. For a list of language codes that not only display in your form but will also trigger the options, menus, buttons, and other user interface elements in the apps of Survey123 to change when the language is selected, see Supported languages.

2. For each question to be translated, type the translated text in this column.
3. Repeat for each additional language.

Note:

When you use a four-letter language code in the column title of an XLSForm, you will see the following warning when you update the form preview: The following language declarations do not contain valid machine-readable codes: 中文 (zh-cn). Learn more: http://xlsform.org/#language. The survey will still publish successfully, and if your four-letter code is a supported language, the menus, buttons, and other user interface elements in Survey123 will change when the language is selected.

Translate hints and messages

Hints and messages are translated the same way as labels.

1. Add a column to the survey worksheet and name it with the hint or message type, followed by the name and code used to identify the language. See the following examples:
   • hint::Español (es)
   • guidance_hint::Español (es)
   • constraint_message::Español (es)
   • required_message::Español (es)
2. For each hint or message to be translated, type the translated text in this column.
3. Repeat for each additional language.

Translate choice lists

You can provide translations for the options in choice lists.

1. Add a column to the choices worksheet and name it label:: followed by the name and code used to identify the language, for example, label::Español (es).
2. For each option to be translated, type the translated text in this column.
3. Repeat for each additional language.

Caution:

Duplicate choice names in a choice list are not supported for multilingual surveys.

The or_other option for select_one and select_multiple questions is not supported for multilingual surveys. It is recommended that you add a separate text question to collect the other response. For more information, see Multiple choice questions.

Translate images and media

You can also provide translated images across languages.

1. Add a column to the survey or choices worksheet and name it image:: followed by the name and code used to identify the language, for example, image::Español (es).
2. For each image to be translated, place the translated image in the survey's media folder, and type its file name in the new column.
3. Repeat for each additional language.

You can translate audio files attached to a question or choice similarly with an audio:: column, such as audio::Español (es).

Translate form elements

You can translate the title that appears at the top of your survey and various form elements that appear in the Survey123 web app. For more information on these elements, see Customize form elements.

1. Add a note question to the survey and name it one of the following:
   • generated_note_form_title
   • generated_note_form_submit_text
   • generated_note_form_footer
   • generated_note_prompt_submitted
2. Enter the translated text in a column named label:: followed by the name and code used to identify the language, for example, label::Español (es).
3. Repeat for each additional language.

Export and import translations

The following text elements in a survey can be exported to Microsoft Excel files to enable distributed translation:

• Question labels, hints, and guidance hints
• Constraint messages and required messages
• File names for audio and images used in questions and choices
• Customized form elements, for example, the survey's title and description
• Choice labels

To export and import translations, the survey's XLSForm must contain at least one label:: language column other than the default in either the survey or choices worksheet. It is also recommended that you set the default language on the settings worksheet.

Note:

To run the Export translations and Import translations tools, you must configure a Python environment in Survey123 Connect. For more information, see Configure Python.

You must be signed in to Survey123 Connect to export and import translations.

To export text elements for translation, open the survey in Survey123 Connect. Click Tools and choose Export translations. An .xlsx file for each language is created in the survey's translations folder.

Each .xlsx file contains a worksheet with three columns:

• Column A—Key that represents the survey element
• Column B—Text in the default language
• Column C—Text entered by the translator

The key that represents the translatable text is a concatenation of the survey element's type, name, and value, and it can provide context to the translator as to how the text is used in the survey. The following lists examples of common keys:

• #/questions["status"]/label—The label of the question named status
• #/questions["status"]/hint—The hint of the question named status
• #/choicelists["yes_no"]/choices["yes"]/label—The label of the choice named yes
• #/choicelists["yes_no"]/choices["no"]/label—The label of the choice named no

The keys and column headings in translation files must not be changed. Modified keys or column headings will lead to import failures.

To import completed translation files, click Tools and choose Import translations. The translated text is imported into columns in the survey's XLSForm.

Default languages other than English

If you intend to use a survey with non-English labels on a device with a locale that is set to English, there is a subtle difference in behavior depending on how the non-English language is identified. The default column titled label can contain text in any language, and this content is displayed for the labels of the questions by default. In most cases, this works as expected. In some cases, you may see right-to-left text displayed from left to right, or dates, currency, and calendars displayed in English.

To ensure the best translation experience, it is recommended that you do the following:

• Ensure all text columns (labels, hints, and messages) have the language's name and code in their titles, for example, label::Español (es).
• Define a default_language setting on the settings tab.

When you use a language code from the Supported languages list, Survey123 not only ensures that the text you include in the spreadsheet is displayed as expected but also uses the locale preferences to display the expected numbers, currency values, and calendar pickers.