Translating the web forms user interface
Overview
A SurveyCTO form definition contains all the text for the form, including things like field labels, hints, choice labels, and constraint messages. If your form has multiple languages, the translations for each of these bits of text are contained in the form definition as well (see the topic on form languages). But what about all the text that one sees while filling out a form in a web browser that isn't contained in the form definition? This text comes from the web forms user interface, and is the same across all your forms on your server. The web forms interface includes things like button labels, generic text that you see at the start and end of each form (like "You are at the start of a form. When you are ready to begin..."), and error messages. Since these are part of the overall form-filling experience for your users, you will want to make sure these texts are displayed in a language that the user can understand.
Selecting the interface language
Users who are filling out SurveyCTO forms in a web browser will see a language selector dropdown in the toolbar at the top of the screen (on small screens, this toolbar can be accessed by clicking the three lines in the top right of the screen). By default, this selector will show the language labels for all the available interface languages on the server. Selecting a different language in that dropdown will change the user interface language.
When filling out a form that contains multiple languages, this dropdown will contain the form languages (from the form definition) instead. In this case, selecting a different language in that dropdown will change the form language. SurveyCTO will attempt to keep the interface matched to the form language. To ensure this works properly, make sure each language in your form definition is mapped to a user interface language (see below).
Mapping interface languages
Most languages can be referred to in more than one way (for example, "French", and "Français"). SurveyCTO needs a way to connect all of these different language names, so that whether your form definition uses "French", "français", or "FR", the correct French interface language will be shown. Mapping is how you connect these various names. Each interface language needs to be 'mapped' to one or more form or browser languages in order to be actually shown in a live web form.
It's important to map each of the language names you use in your forms to an interface language, otherwise your users may see the form in one language and the web forms user interface in another language. Do this by going to the Configure tab, choosing the Languages option within Server settings, and editing the interface languages as appropriate. For each, add all form languages that should be linked to the interface language. (When editing an interface language, you can click the "Scan existing forms" button to populate the language-mapping selector with all languages currently defined within your server's form definitions.)
Defaults and fallbacks
You can configure a series of fallback options to control which languages are used when the normal methods of selecting the correct language fail. On the Configure tab, scroll down to the Server settings section and click on Languages. You will see a section labeled Default languages for web forms.
- Default for unknown mapping controls which interface language is used if unable to find an interface language to match the current form language (for multi-language forms) or the current web browser (for single-language forms or pages outside forms).
- Default for missing strings controls which interface language is used if the current translation table is missing a translation for a term. This can happen if you upload an incomplete translation table. You will only be able to select one of the four SurveyCTO-managed interface languages for this setting.
Available interface languages
To find out which interface languages are available on your server, you can view them on the Collect tab. This will also show you which form and browser languages they are mapped to. If you are a global admin on your server, this information is also available on the Configure tab. Four interface languages are included automatically in every SurveyCTO server: English, French, Spanish, and Hindi. The translations for these four languages are managed by SurveyCTO, so you can be sure they are always valid and complete. You can change the image or mappings for SurveyCTO-managed languages, but they cannot be deleted.
Adding your own interface languages
If you'd like the web forms user interface on your server to support more languages, you can add as many as you'd like by following these steps:
- Check our GitHub repository to see if another user has already shared a translation table for your language of interest. If so, download the CSV file to your local computer.
- If you have to create your own translation table, download a translation table template from under Languages in the Server settings section of the Configure tab (selecting the reference language that you are most familiar with).
- Fill in the second column in the CSV with your own translations — or, if using somebody else's template, review and edit the translations as needed. For guidance on CSV files, see: What are CSV files and how do I work with them?
- Under Languages in the Server settings section of the Configure tab, add a new language and give it a name.
- Upload your translation table (CSV file).
- Verify that your translations look correct. If something looks off, it's likely an issue with your character encoding. This article can help you troubleshoot those types of issues.
- Specify a language label. This is the label that should appear to users in the language selector dropdown.
- Add an image so that users filling out web forms will be able to identify this language visually in the language dropdown. This is an optional step, but highly recommended.
- Map the appropriate form languages. Tip: use the "Scan existing forms" button to search through all of the multi-language forms on your server and load their languages into the dropdown for easy selection.
- Map the appropriate browser languages by selecting from the list of ISO 639-1 codes provided.
- Click Save changes.
